ReplaceSystemDisk-阿里云帮助中心

Replaces the operating system (system disk) of an ECS instance. After the operating system of the ECS instance is replaced, the original system disk of the instance is released and a new system disk is generated for the instance. This causes the ID of the system disk to change.

Operation description

调用该接口前请您仔细阅读更换系统盘（更换操作系统）。

更换系统盘时，您需要注意：

不支持变更系统盘计费方式。
不支持更换系统盘的云盘类型。
系统盘挂载的 ECS 实例不能有未支付的订单。
实例的状态必须为已停止（Stopped）状态。

Note
仅适用于专有网络 VPC 类型实例。如果 ECS 实例为按量付费计费模式，且开启默认启用节省停机模式，为防止地域范围内的 ECS 实例库存不足，引起的更换系统盘后无法重启实例。您需要在停止该实例时设置为普通停机模式。具体操作，请参见 StopInstance 。
您可以通过参数SystemDisk.Size重新指定系统盘的容量大小（不能低于原系统盘容量）。
ECS 实例被安全锁定，即实例的OperationLocks参数值包含"LockReason": "security"，不支持更换系统盘。更多信息，请参见安全锁定时的 API 行为。

更换系统盘后，可通过 DescribeInstances 接口查询更换系统盘的实例的状态验证是否更换成功。如果返回值OperationLocks为空，则表示更换系统盘的操作已完成。

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 instance whose operating system you want to replace. Note Make sure that the instance is in the `Stopped` (`Stopped`) state.	i-bp67acfmxazb4ph****
ImageId	string	No	The ID of the image used to replace the system disk. This parameter is required.	m-bp67acfmxazb4ph****
SystemDisk.Size	integer	No	The capacity of the new system disk. Unit: GiB. Valid values: Basic disk: Max{20, Size of the image specified by ImageId} to 500. Enterprise SSD (ESSD): PL0 ESSD: Max{1, Size of the image specified by ImageId} to 2048. PL1 ESSD: Max{20, Size of the image specified by ImageId} to 2048. PL2 ESSD: Max{461, Size of the image specified by ImageId} to 2048. PL3 ESSD: Max{1261, Size of the image specified by ImageId} to 2048. ESSD AutoPL disk: Max{1, Size of the image specified by ImageId} to 2048. Other disk categories: Max{20, Size of the image specified by ImageId} to 2048. Default value: Max{40, Size of the image specified by ImageId}. Note If the capacity of the new system disk exceeds `Max{20, Capacity of the original system disk}`, you are charged for the excess capacity.	80
ClientToken	string	No	The client token that is used to ensure the idempotency of the request. You can use the client to generate the token, but make sure that the token is unique across requests. The token 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 system configurations for virtual machines provided by Alibaba Cloud. System configurations for Windows: NTP and KMS. System configurations for Linux: NTP and YUM. Note This parameter takes effect only when you attach a system disk whose device name is /dev/xvda.	true
Password	string	No	Specifies whether to reset the password for the instance. The password must be 8 to 30 characters in length and contain at least three of the following items: uppercase letters, lowercase letters, digits, and special characters. Special characters include: ()`~!@#$%^&-_+=\|{}[]:;'<>,.?/ The passwords of Windows instances cannot start with a forward slash (/). This parameter is empty by default, which indicates that the current password remains unchanged. Note* If you specify `Password`, we recommend that you send requests over HTTPS to prevent password leaks.	EcsV587!
PasswordInherit	boolean	No	Specifies whether to use the preset password of the image. Default value: false Note If the PasswordInherit parameter is specified, you must leave the Password parameter empty. Before you use this parameter, make sure that a password is preset for the image.	false
KeyPairName	string	No	The name of the key pair. Note This parameter is applicable only to Linux instances. You can bind an SSH key pair to the instance as a logon credential. After you bind the SSH key pair, the username and password logon method is disabled for the instance.	testKeyPairName
DiskId	string	No	Note This parameter is deprecated. To improve compatibility, we recommend that you use `ImageId`.	d-bp67acfmxazb4ph****
Platform	string	No	Note This parameter is deprecated.	CentOS
Architecture	string	No	Note This parameter is deprecated.	i386
SecurityEnhancementStrategy	string	No	Specifies whether to use Security Center Basic after the system disk is replaced. Valid values: Active: uses Security Center Basic after the system disk is re-initialized. This value is applicable only to public images. Deactive: does not use Security Center Basic after the system disk is re-initialized. This value is applicable to all images. Default value: Deactive.	Active
Encrypted	boolean	No	Specifies whether to encrypt the disk. Valid values: true false Default value: false. Note When you use a shared encrypted image to create the disk based on an encrypted snapshot, you must set Encrypted to true to ensure that the disk uses an encryption key of your own.	false
KMSKeyId	string	No	The ID of the KMS key to use for the system disk.	e522b26d-abf6-4e0d-b5da-04b7******3c
EncryptAlgorithm	string	No	Note This parameter is not available for public use.	hide
Arn	array<object>	No	This parameter is not available for public use.
	object	No
RoleType	string	No	Note This parameter is not available for public use.	null
Rolearn	string	No	Note This parameter is not available for public use.	null
AssumeRoleFor	integer	No	Note This parameter is unavailable.	0

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.
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,does not support this operation.	Images that contain data disk snapshots do not support this operation.
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.
400	InvalidDatadisk.DiskStatusViolation	The operation is not permitted due to status of the Datadisk.
400	InvalidDatadisk.DiskCategoryViolation	The operation is not permitted due to category of the Datadisk.
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.
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 with encrypted snapshots is not supported.	Creating a non-encrypted disk with an encrypted snapshot is not supported.
500	OperationDenied	Internal Error.
500	InternalError	The request processing has failed due to some unknown error.
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, system disk is transfering.	The resource is in a state that does not support the current operation. Try again after the system disk stops transmitting data.
403	IncorrectDiskStatus	The current disk status does not support this operation.
403	IncorrectInstanceStatus	The current status of the resource does not support this operation.
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 market image is not available, Or the specified user defined image includes product code because it is based on an image subscribed from marketplace, and that image in marketplace includeing exact the same product code has been removed.	The specified Alibaba Cloud Marketplace image is unavailable, or the specified custom image contains the product code of the Alibaba Cloud Marketplace image from which the custom image is derived and the Alibaba Cloud Marketplace image was removed from Alibaba Cloud Marketplace.
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 is not support IoOptimized Instance.
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.	You cannot use the specified Alibaba Cloud Marketplace image because you have not purchased the image or your image quota has been used up.
403	INST_HAS_UNPAID_ORDER	The instance has unpaid order.
403	OperationDenied.InstanceCreating	The specified instance is creating.
403	DependencyViolation.WindowsInstance	The instance creating is windows, cannot use ssh key pair to 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 parameter EncryptAlgorithm is not valid.
403	InvalidEncrypted.NotMatchKmsKeyId	The specified parameter Encrypted must be true when KmsKeyId is not empty.
403	InvalidEncrypted.NotMatchEncryptAlgorithm	The specified parameter Encrypted must be true when EncryptAlgorithm is not empty.
403	InvalidParameter.KmsNotEnabled	The specified operation need enable KMS.
403	InvalidParameter.DataEncryptedKeyCreateFailed	Create kms data encrypted key fail. If you need further assistance, you can contact the KMS Technical Support.	Failed to create a data key using the KMS master key. Please contact the KMS attendant for further troubleshooting.
403	InvalidParameter.KMSKeyId.NotFound	The specified KMSKeyId does not exist.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service have no right to access your KMS.	ECS is not authorized to access your KMS resources.
403	InvalidKMSKeyId.NotSymmetric	The specified parameter KmsKeyId must be symmetric.
403	InvalidDiskId.NotSupportReplaceEncryptedSystemDisk	The specified diskId not support replace encrypted system disk.
403	NotSupportSnapshotEncrypted.DiskCategory	The specified disk category does not support creating encrypted system disks or creating encrypted data disks from snapshots. Check the DiskCategory or Encrypted parameter, or check your account for default encryption settings.	This disk type does not support creating encrypted system disks or creating encrypted data disks in snapshot mode. Please check the disk type and encryption parameters you entered, or check whether you have configured the default encryption configuration for account cloud disks.
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.ImageNotValid	The specified Image is disabled or deleted, please check the status of the image.	The specified image is disabled or deleted. Check the image status.
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 CMK (Customer Master Key) must be in an active state.	The CMK (Customer Master Key) must be in an active state.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The CMK(Customer Master Key) lacks authorization to add tags to the ECS service.	The CMK(Customer Master Key) lacks authorization to add tags to the ECS service.
403	InvalidEncrypted.NotMatchSnapshot	The specified parameter Encrypted must be set to true when creating disks with encrypted snapshots.	When you create a disk using an encrypted snapshot, the specified parameter Encrypted must be set to true.
403	InvalidEncrypted.NotMatchDiskDefaultEncryption	Enabling disk default encryption prevents the creation of non-encrypted disks.	After the default encryption of the cloud disk account is enabled, an unencrypted disk cannot be created.
403	InvalidPayMethod.SyncPaymentNotSupport	Synchronous payment is not supported. Use another payment method.	Synchronous payment is not supported. Please select another payment method.
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.