Changes the deployment set of an Elastic Compute Service (ECS) instance or migrates an ECS instance to a dedicated host. You can change the instance type of the ECS instance when you migrate the instance.

Description

When you call this operation for an ECS instance, take note of the following items:

  • The ECS instance must be in the Stopped state. The instance is automatically restarted after it is migrated.
  • The network type of the ECS instance must be Virtual Private Cloud (VPC).
  • The ECS instance and the destination dedicated host to which to migrate the instance must belong to the same account and reside in the same region and zone.
  • A pay-as-you-go ECS instance can be migrated to a subscription dedicated host. A subscription ECS instance can be migrated only between subscription dedicated hosts. The expiration date of the subscription ECS instance cannot be later than that of the destination dedicated host.
  • You can migrate only pay-as-you-go ECS instances from a shared host to a dedicated host. You cannot migrate subscription or preemptible instances from a shared host to a dedicated host.
  • You can redeploy an ECS instance to a specific dedicated host cluster.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

ParameterTypeRequiredExampleDescription
ActionStringYesModifyInstanceDeployment

The operation that you want to perform. Set the value to ModifyInstanceDeployment.

RegionIdStringYescn-hangzhou

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

InstanceIdStringYesi-bp67acfmxazb4ph***

The IDs of instances.

DedicatedHostIdStringNodh-bp67acfmxazb4ph****

The ID of the destination dedicated host. You can call the DescribeDedicatedHosts operation to query the most recent list of dedicated hosts.

When you migrate an instance from a shared host to a dedicated host or between dedicated hosts, take note of the following items:

  • To migrate the instance to a specific dedicated host, specify a value for this parameter.
  • To migrate the instance to a system-selected dedicated host, leave this parameter empty and set Tenancy to host.

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

DeploymentSetIdStringNods-bp67acfmxazb4ph****

The ID of the destination deployment set.

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

Note You cannot change the deployment set when you modify the configurations of dedicated hosts, including parameters such as Tenancy, Affinity, and DedicatedHostId.
DeploymentSetGroupNoIntegerNo3

The number of the deployment set group in which to deploy the instance in the destination deployment set. This parameter is valid only when the destination deployment set uses the high availability group strategy (AvailabilityGroup). Valid values: 1 to 7.

Note If you call this operation to deploy an instance to a deployment set that uses the high availability group strategy (AvailabilityGroup) and this parameter is left empty, the system evenly distributes ECS instances among the deployment set groups in the deployment set. If you call this operation to change the deployment set of an instance and specify the current deployment set of the instance as the destination deployment set, the system evenly distributes ECS instances again among the deployment set groups in the deployment set.
ForceBooleanNofalse

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

  • true: forcibly changes the host of the instance when the deployment set of the instance is changed. Hosts can be forcibly changed only for instances in the Running or Stopped state. The instances in the Stopped state do not include pay-as-you-go instances that are stopped in economical mode.
    Note If the specified ECS instance has local disks attached, the local disks are forcibly changed when the host of the instance is forcibly changed. This may cause data loss in the local disks. Proceed with caution.
  • false: does not forcibly change the host of the instance when the deployment set of the instance is changed. You can add the instance to a deployment set only when the instance remains on the current host. When the Force parameter is set to false, the deployment set may fail to be changed.

Default value: false.

AffinityStringNohost

Specifies whether to associate the instance with a dedicated host. Valid values:

  • host: associates the instance with a dedicated host. When you start a stopped instance in economical mode, the instance remains on its original dedicated host.
  • default: does not associate the instance with a dedicated host. When you start a stopped instance in economical mode, the instance can be automatically deployed to another dedicated host in the automatic deployment resource pool if resources of the original dedicated host are insufficient.

If you want to migrate the instance from a shared host to a dedicated host, use the default value. Default value: default.

TenancyStringNohost

Specifies whether to deploy the instance on a dedicated host. Set the value to host to deploy the instance on a dedicated host.

MigrationTypeStringNolive

Specifies whether to stop the instance before it is migrated to the destination dedicated host. Valid values:

  • reboot: stops the instance before it is migrated.
  • live: migrates the instance without stopping it. If you set the MigrationType parameter to live, you must specify the DedicatedHostId parameter. In this case, you cannot change the instance type of the ECS instance when the instance is migrated.

Default value: reboot.

InstanceTypeStringNoecs.c6.large

The instance type to which the instance is changed. You can call the DescribeInstanceTypes operation to query the most recent list of instance types.

You can change the instance type of the ECS instance when you migrate the instance to a dedicated host. The new instance type must match the type of the specified dedicated host. For more information, see Dedicated host types.

  • If you specify this parameter, you must also specify the DedicatedHostId parameter.
  • You cannot change the instance type of the ECS instance if you use the automatic deployment feature to migrate the instance.
DedicatedHostClusterIdStringNodc-bp67acfmxazb4ph****

The ID of the dedicated host cluster.

RemoveFromDeploymentSetBooleanNofalse

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

  • true.
  • false.

Default value: false.

Note If you set this parameter to true, you must specify the InstanceId of the selected ECS instance and DeploymentSetId of the deployment set to which the ECS instance belongs.

Response parameters

ParameterTypeExampleDescription
RequestIdString04F0F334-1335-436C-A1D7-6C044FE7****

The ID of the request.

Examples

Sample requests

http(s)://ecs.aliyuncs.com/?Action=ModifyInstanceDeployment
&RegionId=cn-hangzhou
&InstanceId=i-bp67acfmxazb4ph***
&DedicatedHostId=dh-bp67acfmxazb4ph****
&DeploymentSetId=ds-bp67acfmxazb4ph****
&Tenancy=host
&MigrationType=live
&DedicatedHostClusterId=dc-bp67acfmxazb4ph****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<ModifyInstanceDeploymentResponse>
    <RequestId>04F0F334-1335-436C-A1D7-6C044FE7****</RequestId>
</ModifyInstanceDeploymentResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

HttpCodeError codeError messageDescription
400OperationDenied.UnstoppedInstanceOperation denied due to unstopped instance.The error message returned because the current operation is invalid. Check whether the instance is in the Stopped state.
400InvalidDedicatedHostStatus.NotSupportOperation denied due to dedicated host status.The error message returned because the operation is not supported while the dedicated host is in the current state.
400InvalidPeriod.ExceededDedicatedHostInstance expired date can't exceed dedicated host expired date.The error message returned because the expiration date of the instance is later than that of the dedicated host.
400InvalidParam.TenancyThe specified Tenancy is invalid.The error message returned because the specified Tenancy parameter is invalid.
400OperationDenied.InvalidInstanceThe specified instance is not dedicated instance.The error message returned because the specified instance is not deployed on a dedicated host.
400ChargeTypeViolation.PostPaidDedicatedHostPrepaid instance onto postpaid dedicated host is not allowed.The error message returned because subscription instances cannot be deployed on pay-as-you-go dedicated hosts.
400InvalidDedicatedHostId.NotFoundThe specified DedicatedHostId does not exist.The error message returned because the specified DedicatedHostId parameter does not exist.
400InvalidInstanceType.ValueNotSupportedThe specified InstanceType does not exist or beyond the permitted range.The error message returned because the specified InstanceType parameter does not exist or because you are not authorized to manage instances of the specified instance type.
403IncorrectInstanceStatus%sThe error message returned because the operation is not supported while the instance is in the current state.
403OperationDenied.NoStockThe resource is out of usage.The error message returned because the instance is not in the Running state. Start the instance or check whether the operation is valid.
404InvalidInstanceId.NotFoundThe specified InstanceId does not exist.The error message returned because the specified instance ID does not exist. Check whether the instance ID is correct.
404InvalidInstanceNetworkType.NotSupportThe specified Instance network type not support.The error message returned because the network type of the instance does not support this operation.
404InvalidInstanceType.NotSupportThe Dedicated host not support the specified instance type.The error message returned because the current dedicated host does not support the specified instance type.

For a list of error codes, visit the API Error Center.