ModifyInstanceDeployment-阿里云帮助中心

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 an ECS instance when you migrate the instance.

Operation description

Take note of the following items:

The instance must be in the Stopped (Stopped) state. The instance is automatically restarted after it is migrated.
The network type of the instance must be Virtual Private Cloud (VPC).
The 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 instance can be migrated to a subscription dedicated host. A subscription instance can be migrated only between subscription dedicated hosts. The expiration date of the subscription instance cannot be later than that of the destination dedicated host.
You can migrate only pay-as-you-go instances from a shared host to a dedicated host. You cannot migrate subscription instances or spot instances from a shared host to a dedicated host.
You can redeploy an instance to a specific dedicated host cluster.

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}

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 ID of the instance.	i-bp67acfmxazb4ph***
DedicatedHostId	string	No	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 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 Functions and features.	dh-bp67acfmxazb4ph****
DeploymentSetId	string	No	The ID of the destination deployment set. This parameter is required when you add an instance to a deployment set or change the deployment set of an instance. Note You cannot change the deployment set when you modify dedicated host configurations, including the `Tenancy`, `Affinity`, and `DedicatedHostId` parameters.	ds-bp67acfmxazb4ph****
DeploymentSetGroupNo	integer	No	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 (`AvailablilityGroup`) and leave this parameter empty, the system evenly distributes 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 instances again among the deployment set groups in the deployment set.	3
Force	boolean	No	Specifies whether to forcefully change the host of the instance when the deployment set of the instance is changed. Valid values: true: forcefully changes the host of the instance when the deployment set of the instance is changed. Hosts can be forcefully changed only for instances in the Running (Running) or Stopped (Stopped) state. The instances that are in the Stopped (Stopped) state do not include pay-as-you-go instances that are stopped in economical mode. Note** If the specified instance has local disks attached, the local disks are forcefully changed when the host of the instance is forcefully changed. This may cause data loss in the local disks. Proceed with caution. false: does not forcefully 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.	false
Affinity	string	No	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 the 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.	host
Tenancy	string	No	Specifies whether to deploy the instance on a dedicated host. Set the value to host, which indicates that the instance is deployed on a dedicated host.	host
MigrationType	string	No	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 MigrationType to live, you must specify DedicatedHostId. In this case, you cannot change the instance type of the instance when the instance is migrated. Default value: reboot.	live
InstanceType	string	No	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 an 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 `DedicatedHostId`. You cannot change the instance type of an instance if you use the automatic deployment feature to migrate the instance.	ecs.c6.large
DedicatedHostClusterId	string	No	The ID of the dedicated host cluster.	dc-bp67acfmxazb4ph****
RemoveFromDeploymentSet	boolean	No	Specifies whether to remove the specified instance from the specified deployment set. Valid values: true false Default value: false. Note If you set this parameter to true, you must specify InstanceId and DeploymentSetId and make sure that the specified instance belongs to the specified deployment set.	false

Response elements

Element	Type	Description	Example
	object
RequestId	string	The ID of the request.	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.
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.
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.
400	OperationDenied.NotSupport	Ecs on dedicatedHost has been migrated.
400	InvalidDedicatedHostId.NotFound	The specified DedicatedHostId 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.
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.
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.