Use ReplaceSystemDisk to replace the system disk of an ECS instance - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Replaces the operating system of an ECS instance by replacing its system disk. After the replacement, the disk ID of the system disk changes and the original disk is released.

Operation description

Before calling this operation, carefully read Replace the system disk (replace the operating system).

When replacing the system disk, note the following:

You cannot change the billing method of the system disk.
You cannot change the disk type of the system disk.
The ECS instance to which the system disk is attached must have no unpaid orders.
The instance must be in the Stopped (Stopped) state.

Note
This applies only to VPC-type instances. If the ECS instance uses the pay-as-you-go billing method and the economical mode is enabled by default, set the instance to the standard stop mode when stopping it. This prevents the instance from failing to restart after the system disk is replaced due to insufficient ECS instance inventory in the region. For more information, see StopInstance.
You can use the SystemDisk.Size parameter to specify a new capacity for the system disk. The new capacity cannot be smaller than the original capacity.
If the ECS instance is security-locked, meaning the OperationLocks parameter of the instance contains "LockReason": "security", replacing the system disk is not supported. For more information, see API behavior when an instance is locked for security reasons.

After replacing the system disk, call DescribeInstances to query the instance status and verify whether the replacement was successful. If the returned OperationLocks value is empty, the system disk replacement is complete.

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:ReplaceSystemDisk

update

Disk

acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}

Image

acs:ecs:{#regionId}:{#accountId}:image/{#imageId}

*Instance

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

ecs:IsDiskEncrypted
ecs:IsSystemDiskEncrypted
ecs:PasswordInherit
ecs:PasswordCustomized
ecs:IsDiskByokEncrypted
ecs:IsSystemDiskByokEncrypted
ecs:LoginAsNonRoot
ecs:ImagePlatform

None

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	Yes	The ID of the target instance. Note Make sure that the target instance is in the `Stopped` instance status before you send the request.	i-bp67acfmxazb4ph****
ImageId	string	No	The ID of the image to use when resetting the system disk. This parameter is required.	m-bp67acfmxazb4ph****
SystemDisk.Size	integer	No	The new capacity of the system disk. Unit: GiB. Valid values: Basic disk: Max{20, image size specified by the ImageId parameter} to 500. Enterprise SSD: PL0: Max{1, image size specified by the ImageId parameter} to 2048. PL1: Max{20, image size specified by the ImageId parameter} to 2048. PL2: Max{461, image size specified by the ImageId parameter} to 2048. PL3: Max{1261, image size specified by the ImageId parameter} to 2048. ESSD AutoPL disk: Max{1, image size specified by the ImageId parameter} to 2048. Other disk types: Max{20, image size specified by the ImageId parameter} to 2048. Default value: Max{40, image size specified by the ImageId parameter}. Note Disk capacity that exceeds `Max{20, original system disk capacity}` incurs additional charges.	80
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. ClientToken can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-426655440000
UseAdditionalService	boolean	No	Specifies whether to use the virtual machine system configurations provided by Alibaba Cloud (Windows: NTP and KMS. Linux: NTP and YUM). Note This parameter takes effect only when the system disk is attached (that is, the device name is /dev/xvda).	true
Password	string	No	Specifies whether to reset the password of the ECS instance. The password must be 8 to 30 characters in length and must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. The following special characters are supported: ()`~!@#$%^&-_+=\|{}[]:;'<>,.?/ For Windows instances, the password cannot start with a forward slash (/). Default value: The password remains unchanged. Note* If you specify the `Password` parameter, use HTTPS to send the request to prevent password leaks.	EcsV587!
PasswordInherit	boolean	No	Specifies whether to use the preset password of the image. Default value: false. Note If you use this parameter, the Password parameter must be empty. Make sure that the image you use has a preset password.	false
KeyPairName	string	No	The name of the key pair. Note This parameter applies only to Linux ECS instances. You can bind an SSH key pair to an ECS instance as a logon credential. After an SSH key pair is bound, username and password-based logon is disabled.	testKeyPairName
DiskId	string	No	Note [Deprecated] This parameter is deprecated. To improve compatibility, use `ImageId` instead.	d-bp67acfmxazb4ph****
Platform	string	No	Note [Deprecated] This parameter is deprecated.	CentOS
Architecture	string	No	Note [Deprecated] This parameter is deprecated.	i386
SecurityEnhancementStrategy	string	No	Specifies whether to use Security Center for free after the system disk is replaced. Valid values: Active: Uses Security Center. This value is supported only for public images. Deactive: Does not use Security Center. This value is supported for all images. Default value: Deactive.	Active
Encrypted	boolean	No	Specifies whether to encrypt the disk. Valid values: true: encrypts the disk. false: does not encrypt the disk. Default value: false. Important When you use a shared encrypted image to create a disk based on an encrypted snapshot, you must set the request parameter Encrypted=true for the disk to ensure that the disk uses the key of the account that receives the shared image.	false
KMSKeyId	string	No	The KMS key ID of the system disk.	e522b26d-abf6-4e0d-b5da-04b7******3c
EncryptAlgorithm	string	No	Note This parameter is not available for use.	hide
Arn	array<object>	No	This parameter is not available for use.
	object	No
AssumeRoleFor	integer	No	Note This parameter is not available for use.	0
RoleType	string	No	Note This parameter is not available for use.	null
Rolearn	string	No	Note This parameter is not available for use.	null

Response elements

Element	Type	Description	Example
	object
DiskId	string	The ID of the new system disk.	d-bp67acfmxazb4ph****
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

Examples

Success response

JSON format

{
  "DiskId": "d-bp67acfmxazb4ph****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

Error codes

HTTP status code	Error code	Error message	Description
400	LoginAsNonRoot.ImageNotSupport	The specified image does not support login as non-root.	The image does not support the logons of non-root users.
400	InvalidSystemDiskSize.ValueNotSupported	The specified parameter SystemDisk.Size is invalid.
400	InvalidParameter.Conflict	The specified image does not support the specified instance type.	The specified image cannot be used for instances of the specified instance type.
400	InvalidSystemDiskSize.ImageNotSupportResize	The specified image does not support resize.	The specified image does not support resizing.
400	InvalidSystemDiskSize	The specified parameter SystemDisk.Size is invalid.
400	InvalidPassword.Malformed	The specified parameter "Password" is not valid.	The specified Password parameter is invalid.
400	InvalidPasswordParam.Mismatch	The input password should be null when passwdInherit is true.	The Password parameter must be left empty when the PasswdInherit parameter is used.
400	OperationDenied	The specified image contains the snapshot of the data disk. This operation is not supported.
400	InvalidDiskCategory.ValueNotSupported	The specified parameter "DiskCategory" is not valid.	The specified cloud disk type DiskCategory is invalid.
400	InvalidKeyPairName.NotFound	The specified KeyPairName does not exist.	The specified KeyPairName parameter does not exist.
400	DependencyViolation.IoOptimize	The specified parameter InstanceId is not valid.	The I/O optimization configuration of the instance is invalid.
400	MissingParameter.Architecture	Architecture should not be null.	The Architecture parameter is required.
400	InvalidArchitecture.Malformed	Architecture is not valid.	The specified Architecture parameter is invalid.
400	MissingParameter.Platform	Platform should not be null.	The Platform parameter is required.
400	InvalidPlatform.Malformed	Platform is not valid.	The specified Platform parameter is invalid.
400	InvalidDiskId.NotFound	The specified disk do not exist.	The specified disk does not exist. Check whether the disk ID is correct.
400	InvalidDatadisk.DiskStatusViolation	The operation is not permitted due to status of the Datadisk.	The current data cloud disk state does not support this operation.
400	InvalidDatadisk.DiskCategoryViolation	The operation is not permitted due to category of the Datadisk.	The type of the data cloud disk does not support this operation.
400	InvalidDatadisk.ChargeTypeViolation	The operation is not permitted due to charge type of the Datadisk.
400	MissingParameter	The input parameter "ImageId" that is mandatory for processing this request is not supplied.
400	InvalidInstance.NotFoundSystemDisk	The specified instance has no system disk.	The specified instance does not have a system disk. Make sure that the instance has a system disk. You can call the DescribeInstances operation to query the details of the instance.
400	InvalidParameter.DiskType	The specified disk type which has kms key can't convert to system disk.
400	DISK_IN_DEDICATED_BLOCK_STORAGE_CLUSTER	The disk in dedicated block storage cluster is not allowed to do this operation.
400	IncorrectDiskStatus.ReplicationStatusNotFound	Disk replication status not found.
400	IncorrectDiskStatus.InReplication	Disk already in replication.
400	InvalidInstanceType.NotSupported	The specified instanceType is not supported by the image architecture.	The specified image schema does not support this instance type.
400	InvalidRegionId.NotSupportReplaceEncryptedSystemDisk	The specified region not support replace encrypted system disk.
400	InvalidStorageClusterId.CapacityNotEnough	The remaining capacity of the current dedicated storage cluster is less than the size of disk.	The remaining capacity of the dedicated block storage cluster to which the disk belongs is insufficient.
400	QuotaExceed.DiskCapacity	The used capacity of disk type has exceeded the quota in the zone, %s.	The capacity of disks that belong to the specified disk category exceeds the quota limit for the zone.
400	AccountForbidden.ProductCreationLimited	The commodity must be officially operated by Aliyun and in pay-as-you-go billing method.	Enterprise cloud migration customers can purchase only pay-as-you-go ECS instances and cannot purchase third-party products such as images provided by Alibaba Cloud Marketplace. Check the parameters and retry with valid parameters.
400	InternalError	The requested services is not available now. Please try again later.	An internal error has occurred. Try again later.
400	InvalidDiskName.Malformed	The specified parameter "SyatemDisk.DiskName or DataDisk.n.DiskName" is not valid.	The disk name specified in the parameter DiskName invalid.
400	InvalidParameter.Encrypted	Creating non-encrypted disks from encrypted snapshots is not allowed. Please set Encrypted to true or use an unencrypted snapshot.
400	InvalidParam.EncryptedMismatch	Creating a disk from a shared encrypted image requires encryption with your own KMS key. Please set the Encrypted parameter to true.
500	OperationDenied	Internal Error.
500	InternalError	The request processing has failed due to an internal error and you may retry later or contact support with the request ID.
403	LoginAsNonRoot.RegionNotSupport	The specified region does not support login as non-root.
403	InvalidSystemDiskStatus.IsTransfering	The current status of the resource does not support this operation. The system disk is transferring.
403	IncorrectDiskStatus	The current disk status does not support this operation.
403	IncorrectInstanceStatus	The instance must be in the Stopped state when you replace the system disk. Please stop the instance and try again.
403	InstanceLockedForSecurity	The instance is locked due to security.	The operation is not supported while the instance is locked for security reasons.
403	ImageNotSubscribed	The specified image has not be subscribed.
403	ImageRemovedInMarket	The specified marketplace image is not available. Or the specified user-defined image includes a product code because it is based on an image subscribed from the marketplace; and that marketplace image including the exact same product code has been removed.
403	InstanceExpiredOrInArrears	The specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode).
403	ChargeTypeViolation	The operation is not permitted due to charge type of the instance.
403	DiskCreatingSnapshot	The operation is denied due to a snapshot of the specified disk is not completed yet.
403	IoOptimized.NotSupported	The specified image does not support IoOptimized instances.
403	OperationDenied.ImageNotValid	The specified marketplace image is not authorized. Please verify the marketplace image authorization and try again.
403	ImageNotSupportInstanceType	The specified image don not support the InstanceType instance.
403	QuotaExceed.BuyImage	The specified image is from the image market. You have not bought it or your quota has been exceeded.
403	INST_HAS_UNPAID_ORDER	The instance has unpaid order.
403	OperationDenied.InstanceCreating	The specified instance is creating.
403	DependencyViolation.WindowsInstance	The instance runs Windows and does not support SSH key pair login.
403	InvalidParameter.NotMatch	%s	A specified parameter is invalid. Check whether parameter conflicts exist.
403	ResourcesNotInSameZone	The specified instance and disk are not in the same zone.
403	OperationDenied.UnpaidOrder	The specified instance has unpaid order.	Your account has unpaid orders for the specified instance. You can log on to the ECS console to pay for the orders.
403	InvalidHostname.MismatchImage	The hostname of the current instance can not be applied to the image you choose.
403	HibernationConfigured.InstanceOperationForbidden	The operation is not permitted due to limit of the hibernation configured instance.	The operation cannot be performed due to the limitations of instances for which the instance hibernation feature is enabled.
403	InvalidOperation.MultiAttachDisk	Multi attach disk does not support this operation.	Disks for which the multi-attach feature is enabled do not support the operation.
403	InvalidRegionId.NotSupportEncryptAlgorithm	The current region does not support creating encrypted disks with EncryptAlgorithm.
403	InvalidRegionId.NotExists	The region not exists.
403	InvalidEncryptAlgorithm	The specified EncryptAlgorithm is not valid. Ensure the value is a supported encryption algorithm such as AES-256.
403	InvalidEncrypted.NotMatchKmsKeyId	The Encrypted parameter must be set to true when KMSKeyId is specified. Please adjust the parameters and try again.
403	InvalidEncrypted.NotMatchEncryptAlgorithm	The Encrypted parameter must be set to true when EncryptAlgorithm is specified. Please adjust the parameters and try again.
403	InvalidParameter.KmsNotEnabled	The specified operation need enable KMS.
403	InvalidParameter.DataEncryptedKeyCreateFailed	The ECS service is not authorized to access your KMS key. Please grant the ECS service permission to use the key and try again.
403	InvalidParameter.KMSKeyId.NotFound	The specified KMSKeyId does not exist. Please verify that the key ID is correct and that the key resides in the current region.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service does not have permission to access your KMS key. Please verify that the specified KMS key has authorized the ECS service.
403	InvalidKMSKeyId.NotSymmetric	The specified KMSKeyId must be a symmetric key. Please use a symmetric KMS key such as an AES-256 key.
403	InvalidDiskId.NotSupportReplaceEncryptedSystemDisk	The specified diskId not support replace encrypted system disk.
403	NotSupportSnapshotEncrypted.DiskCategory	The specified disk category does not support re-encrypting a disk with a new KMSKeyId from a snapshot. Please use a disk category that supports encryption such as cloud_essd.
403	InvalidParameter.AllEmpty	The current operation does not allow both diskId and imageId to be empty. Make sure that either diskId or imageId is not empty.	The current operation does not allow both diskId and imageId to be empty. Make sure that either diskId or imageId is not empty.
403	InvalidParameter.Conflict	The current operation does not allow both diskId and imageId to be set. Make sure that either diskId or imageId is not empty.	The current operation does not allow both diskId and imageId to be set. Make sure that either diskId or imageId is not empty.
403	OperationDenied	The current region does not support changing the image type.	The current region does not support changing the image type.
403	OperationDenied.DiskNoStock	The requested disk category is sold out in the specified zone. Please try a different disk category or another zone.	The requested disk category is sold out in the specified zone. Please try a different disk category or another zone.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The specified KMS key must be in an enabled state. Please enable the key in the KMS console and try again.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The specified KMS key is not authorized for the ECS service. Please grant the ECS service permission to use the key in the KMS console and try again.
403	InvalidEncrypted.NotMatchSnapshot	The Encrypted parameter must be set to true when creating disks from encrypted snapshots. Please set Encrypted to true or use an unencrypted snapshot.
403	InvalidEncrypted.NotMatchDiskDefaultEncryption	The operation failed because default disk encryption is enforced on your account. Please set the Encrypted parameter to true.
403	InvalidPayMethod.SyncPaymentNotSupport	Synchronous payment is not supported. Use another payment method.	Synchronous payment is not supported. Please select another payment method.
403	InvalidOperation.ImageSecureBootUnsupported	The image does not support secure boot.	The mirror does not support secure boot.
403	InvalidDiskCategory.NotSupported	The disk category is not supported in the current zone. Please call DescribeAvailableResource to check supported categories.
403	OperationDenied.KMSKeyUnauthorized	The operation is denied due to missing KMS key authorization. Please check the KMS key permissions and ensure the key is properly authorized for this operation.
403	InvalidOperation.TargetImageIncompatible	The source image cannot be replaced by the target image.	The target mirror you specified cannot replace the current mirror.
404	InvalidInstanceId.NotFound	The specified InstanceId does not exist.	The specified instanceId is invalid.
404	InvalidImageId.NotFound	The specified ImageId does not exist.	The specified image does not exist in this account. Check whether the image ID is correct.
404	InvalidSystemDiskSize.MoreThanMaxSize	The specified SystemDisk.Size parameter exceeds the maximum size.
404	InvalidSystemDiskSize.LessThanImageSize	The specified parameter SystemDisk.Size is less than the image size.
404	InvalidSystemDiskSize.LessThanMinSize	The specified parameter SystemDisk.Size is less than the min size.
404	NoSuchResource	The specified resource is not found.	The specified resource does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.