All Products
Search
Document Center

Elastic Compute Service:ModifyInstanceDeployment

Last Updated:Oct 16, 2026

Modifies the deployment set of an ECS instance or migrates an ECS instance to a dedicated host. Supports changing the instance type during the migration.

Operation description

When you migrate an ECS instance to a dedicated host or change the ECS instance type during the migration, the following conditions must be met:

  • The ECS instance must be in the Stopped state. The instance automatically restarts after the migration.

  • Only ECS instances in a virtual private cloud (VPC) are supported.

  • The ECS instance and the dedicated host must belong to the same account, region, and zone.

  • Pay-as-you-go ECS instances can be migrated to subscription dedicated hosts. Subscription ECS instances can only be migrated between subscription dedicated hosts, and the time when the instance expires cannot be later than the expiration time of the destination dedicated host.

  • When you migrate an ECS instance from a shared host to a dedicated host, the billing method of the instance must be pay-as-you-go. Subscription instances and spot instances are not supported.

  • You can specify a dedicated host cluster for the deployment of ECS instances.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:ModifyInstanceDeployment

update

DedicatedHost

acs:ecs:{#regionId}:{#accountId}:ddh/{#ddhId}

*Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

DedicatedHostCluster

acs:ecs:{#regionId}:{#accountId}:ddhcluster/{#ddhClusterId}

None None

Request parameters

Parameter

Type

Required

Description

Example

RegionId

string

Yes

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou

InstanceId

string

Yes

The instance ID.

i-bp67acfmxazb4ph***

DedicatedHostId

string

No

The ID of the dedicated host. You can call the DescribeDedicatedHosts operation to query available dedicated hosts.

When you change the host of an ECS instance (that is, instance migration from a shared host to a dedicated host, or instance migration between dedicated hosts):

  • To migrate the instance to a specified dedicated host, you must specify this parameter.

  • To migrate the instance to a dedicated host automatically selected by the system, you must leave this parameter empty and set the Tenancy parameter to host.

For more information about the automatic deployment feature, see Features of dedicated hosts.

dh-bp67acfmxazb4ph****

DeploymentSetId

string

No

The ID of the deployment set.

This parameter is required when you add an ECS instance to a deployment set or change the deployment set of an ECS instance.

Note

When you modify the dedicated host-related parameters (Tenancy, Affinity, and DedicatedHostId), you cannot modify the deployment set at the same time.

ds-bp67acfmxazb4ph****

DeploymentSetGroupNo

integer

No

The group number of the instance in the deployment set. This parameter is valid when the deployment set strategy of the deployment set to which the ECS instance is to be added or adjusted is the high availability strategy for deployment set groups (AvailabilityGroup). Valid values: 1 to 7.

Note

If you change the deployment set of an ECS instance and the deployment set strategy is AvailabilityGroup, the system automatically distributes ECS instances evenly among the groups when you do not specify this parameter. If you specify the current deployment set of the ECS instance, the system also redistributes the ECS instances evenly among the groups.

3

Force

boolean

No

Specifies whether to forcibly change the host of the instance when you adjust the deployment set. Valid values:

  • true: Yes. ECS instances in the Running or Stopped state can be restarted. Stopped instances do not include pay-as-you-go ECS instances for which the economical mode is enabled.

    Note

    If the specified ECS instance is equipped with local disks, the local disks are also forcibly changed. This may cause data loss on the local disks during the host change. Proceed with caution.

  • false: No. The instance is added to the deployment set only on the current host. This may cause the deployment set change to fail.

Default value: false.

false

Affinity

string

No

Specifies whether the instance is associated with the dedicated host. Valid values:

  • host: Associated. When an instance for which the economical mode is enabled is stopped and then started, the instance is still deployed on the original dedicated host.

  • default: Not associated. When an instance for which the economical mode is enabled is stopped and then started, if the resources on the original dedicated host are insufficient, the instance can be migrated to another dedicated host in the automatic deployment resource pool.

When an instance is migrated from a shared host to a dedicated host, the default value is default.

host

Tenancy

string

No

Specifies whether the instance is deployed on a dedicated host. Valid value: host. Only deployment on a dedicated host is supported.

host

MigrationType

string

No

Specifies whether to stop ECS instance before migrating it to the destination dedicated host. Valid values:

  • reboot: Stop ECS instance before migration.

  • live: Migrate ECS instance without stopping it. In this case, you must specify the DedicatedHostId parameter. This value does not support changing ECS instance type during the migration.

Default value: reboot.

live

InstanceType

string

No

The target instance type to which the ECS instance is to be changed. You can call the DescribeInstanceTypes operation to query the most recent instance type list.

When you change the host of an ECS instance, you can also change ECS instance type. The target instance type must match the specifications of the specified dedicated host. For more information, see Dedicated host types.

  • When you change ECS instance type, you must specify the dedicated host ID by setting the DedicatedHostId parameter.

  • When you use the automatic deployment feature to migrate an ECS instance, you cannot change ECS instance type.

ecs.c6.large

DedicatedHostClusterId

string

No

The ID of the dedicated host cluster.

dc-bp67acfmxazb4ph****

RemoveFromDeploymentSet

boolean

No

Specifies whether to remove the selected instance from the selected deployment set. Valid values:

  • true: Yes.

  • false: No.

Default value: false.

Note

When this parameter is set to true, you must specify the InstanceId and DeploymentSetId parameters that have an association.

false

Response elements

Element

Type

Description

Example

object

RequestId

string

The request ID.

04F0F334-1335-436C-A1D7-6C044FE7****

Examples

Success response

JSON format

{
  "RequestId": "04F0F334-1335-436C-A1D7-6C044FE7****"
}

Error codes

HTTP status code

Error code

Error message

Description

400 OperationDenied.UnstoppedInstance Operation denied due to unstopped instance. The operation is invalid. Check whether the instance is stopped.
400 InvalidDedicatedHostStatus.NotSupport Operation denied due to dedicated host status. This operation is not supported for the dedicated host in its current state.
400 InvalidPeriod.ExceededDedicatedHost Instance expired date can't exceed dedicated host expired date.
400 NoAvaliableDedicatedHost There's no enough resource on the specified dedicated host. No available dedicated hosts were found.
400 OperationDenied.LocalDiskInstance Operation denied due to instance has local disk.
400 InvalidParameter.Param Requested param is invalid.
400 InvalidParam.Tenancy The specified Tenancy is invalid. The specified Tenancy parameter is invalid.
400 InvalidParam.DedicatedHostId The specified dedicated host id is the same with present host id!
400 InvalidDedicatedHost.NotEnoughResource There's no available dedicated host to perform the operation.
400 OperationDenied.InvalidInstance The specified instance is not dedicated instance. The specified instance is not deployed on a dedicated host.
400 ChargeTypeViolation.PostPaidDedicatedHost Prepaid instance onto postpaid dedicated host is not allowed. Subscription instances cannot be added to pay-as-you-go dedicated hosts.
400 OperationDenied.NotSupport Ecs on dedicatedHost has been migrated.
400 InvalidDedicatedHostId.NotFound The specified DedicatedHostId does not exist. The specified dedicated host does not exist.
400 OperationDenied.CannotPerform Live migration cannot be performed. Hot migration cannot be performed.
400 InvalidInstanceType.ValueNotSupported The specified InstanceType does not exist or beyond the permitted range. The specified instance type does not exist or you are not authorized to manage instances of this instance type.
400 InvalidParameter.Tenancy The specified Tenancy is invalid.
400 InvalidParameter.Affinity The specified Affinity is invalid.
400 InvalidInstanceType.NotSupport The parameter EcsMigrationType conflict with InstanceType, live migration do not support InstanceType alter on ddh.
400 InvalidParam.InstanceId The specified InstanceId should be on dedicatedHost. The specified instance must be deployed on a dedicated host.
400 InvalidDedicatedHostClusterId.NotFound The specified DedicatedHostClusterId does not exist.
400 InvalidDedicatedHostClusterId.Invalid The specified Dedicated Host Cluster is invalid.
400 InvalidDestinationZone.DeploymentSetMismatch Error happened, %s. If the deployment set that the instance joins uses the LowLatency strategy and already contains instances, the new instance must be in the same zone as the existing instances.
403 IncorrectInstanceStatus %s The instance is in a state that does not support the current operation.
403 OperationDenied.NoStock The resource is out of usage.
403 InvalidDeploymentSetId.NoAvailableResources There are no available resources for the specified deployment, you can set the parameter force to true to retry, or wait for additional resource to become available. There are no available resources for the specified deployment, you can set the parameter force to true to retry, or wait for additional resource to become available.
403 InvalidInstanceType.ValueNotSupported The specified InstanceType does not support the current category of data disk. The specified InstanceType does not support the current category of data disk.
404 InvalidDeploymentSetId.NotFound The specified deployment set does not exist.
404 InvalidDedicatedHostId.NotFound The specified DedicatedHostId does not exist.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The specified instanceId is invalid.
404 OperationDenied.UnstoppedInstance Operation denied due to unstopped instance.
404 InvalidInstanceNetworkType.NotSupport The specified Instance network type not support. The operation is not supported while the instance is of the current network type.
404 InvalidInstanceChargeType.NotSupport The Dedicated host not support the specified instance charge type.
404 InvalidInstanceType.NotSupport The Dedicated host not support the specified instance type. The dedicated host does not support the specified instance type.
404 InvalidParameter.DeploymentSetGroupNo Parameter DeploymentSetGroupNo is invalid.
404 InvalidDedicatedHostId.NotSupport Cannot choose instance present host as destination host.
404 InvalidDedicatedHost.NotFound No available host.
404 InvalidParam.DedicatedHostId Parameter dedicated host id must been provided in such operation.
404 InvalidDedicatedHost.ZoneNotMatch The specify dedicated host zone location not match the instance zone location.
404 InvalidOperation.NotSupport The specified DedicatedHost operation not supported on MPS.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.