Replaces the operating system of an Elastic Compute Service (ECS) instance. After you perform an operating system replacement operation, the original disk is released and a new system disk is created. This causes the ID of the system disk to change.
Usage notes
Take note of the following items:
The category of the system disk cannot be changed.
The billing method of the system disk cannot be changed.
The instance must be in the
Stoppedstate.NoteThis item is applicable to only instances that reside in virtual private clouds (VPCs). If the instance is a pay-as-you-go instance and economical mode is enabled by default for the instance, you must disable economical mode and enable standard mode when you stop the instance. This prevents the instance from being unable to restart due to insufficient ECS resources after the system disk is replaced. For more information, see StopInstance.
If the response contains
{"OperationLocks":{"LockReason" : "security"}}, the instance is locked for security reasons and no operations are allowed on the instance. For more information, see API behavior when an instance is locked for security reasons.You cannot have unpaid orders that are associated with the instance.
You can configure the
SystemDisk.Sizeparameter to specify the capacity of the new system disk.
After you call this operation, you can use one of the following methods to check whether the system disk is replaced:
Call the DescribeDisks operation to query the state of the new system disk. If the new system disk is in the In_use state, the system disk is replaced.
Call the DescribeInstances operation to query the state of the instance whose system disk is replaced. If the
OperationLocksresponse parameter is empty, the system disk is replaced.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
Action | String | Yes | ReplaceSystemDisk | The operation that you want to perform. Set the value to ReplaceSystemDisk. |
InstanceId | String | Yes | i-bp67acfmxazb4ph**** | The instance ID. |
ImageId | String | No | m-bp67acfmxazb4ph**** | The ID of the image to use to replace the system disk. If you do not configure the |
SystemDisk.Size | Integer | No | 80 | The capacity of the new system disk. Unit: GiB. Valid values:
Default value: Max{40, Size of the image specified by the ImageId parameter}. Note If the capacity of the new system disk exceeds |
ClientToken | String | No | 123e4567-e89b-12d3-a456-426655440000 | 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. The token can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence. |
UseAdditionalService | Boolean | No | true | 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 if you attach a system disk whose device name is /dev/xvda. |
Password | String | No | EcsV587! | Specifies whether to reset the password for the instance. The password must be 8 to 30 characters in length and can contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. The password can contain the following special characters: The password of a Windows instance cannot start with a forward slash (/). This parameter is empty by default, which indicates that the current password remains unchanged. Note For security reasons, we recommend that you use HTTPS to send requests if the |
PasswordInherit | Boolean | No | false | Specifies whether to use the password preset in the image. Default value: false. Note If you configure the PasswordInherit parameter, you must leave the Password parameter empty and make sure that the selected image has a password preset. |
KeyPairName | String | No | testKeyPairName | The name of the key pair. Note This parameter is applicable to only Linux instances. You can bind an SSH key pair to the instance as a logon credential. After the SSH key pair is bound, the username-password logon method is disabled for the instance. |
DiskId | String | No | d-bp67acfmxazb4ph**** | Note This parameter is deprecated. We recommend that you use the |
Platform | String | No | CentOS | Note This parameter is deprecated. |
Architecture | String | No | i386 | Note This parameter is deprecated. |
SecurityEnhancementStrategy | String | No | Active | Specifies whether to use Security Center free of charge after the system disk is replaced. Valid values:
Default value: Deactive. |
Encrypted | Boolean | No | false | Specifies whether to encrypt the new system disk. Valid values:
Default value: false. |
KMSKeyId | String | No | e522b26d-abf6-4e0d-b5da-04b7******3c | The ID of the Key Management Service (KMS) key to be used for the system disk. |
EncryptAlgorithm | String | No | hide | Note This parameter is not publicly available. |
Arn.N.RoleType | String | No | null | Note This parameter is not publicly available. |
Arn.N.Rolearn | String | No | null | Note This parameter is not publicly available. |
Arn.N.AssumeRoleFor | Long | No | 0 | Note This parameter is not publicly available. |
Response parameters
Parameter | Type | Example | Description |
DiskId | String | d-bp67acfmxazb4ph**** | The new system disk ID. |
RequestId | String | 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E | The request ID. |
Examples
Sample requests
http(s)://ecs.aliyuncs.com/?Action=ReplaceSystemDisk
&InstanceId=i-bp67acfmxazb4ph****
&ImageId=m-bp67acfmxazb4ph****
&SystemDisk.Size=80
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&UseAdditionalService=true
&Password=EcsV587!
&PasswordInherit=false
&KeyPairName=testKeyPairName
&SecurityEnhancementStrategy=Active
&<Common request parameters>Sample success responses
XML format
HTTP/1.1 200 OK
Content-Type:application/xml
<ReplaceSystemDiskResponse>
<DiskId>d-bp67acfmxazb4ph****</DiskId>
<RequestId>F3CD6886-D8D0-4FEE-B93E-1B73239673DE</RequestId>
</ReplaceSystemDiskResponse>JSON format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "337568C5-64F3-4B76-8CDD-D3D8C57B5B8C",
"DiskId" : "d-bp67acfmxazb4ph****"
}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 logons of non-root users. |
400 | InvalidSystemDiskSize.ValueNotSupported | The specified parameter SystemDisk.Size is invalid. | Invalid SystemDisk.Size value. |
400 | InvalidParameter.Conflict | The specified image does not support the specified instance type. | The image cannot be used for instances of the 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. | Invalid SystemDisk.Size value. |
400 | InvalidPasswordParam.Mismatch | The input password should be null when passwdInherit is true. | Password is not left empty when PasswdInherit is set to true. |
400 | OperationDenied | The specified image contains the snapshot of the data disk,does not support this operation. | The operation is not allowed when the specified image contains data disk snapshots. |
400 | InvalidParameter.Conflict | %s | Invalid parameter value. Check whether parameter conflicts exist. %s is a variable. An error message is dynamically returned based on call conditions. |
400 | InvalidSystemDiskSize.ValueNotSupported | %s | Invalid SystemDisk.Size value. |
400 | OperationDenied | %s | The operation is denied. |
400 | InvalidKeyPairName.NotFound | The specified KeyPairName does not exist. | The KeyPairName is not found. |
400 | DependencyViolation.IoOptimize | The specified parameter InstanceId is not valid. | Invalid I/O optimization configuration of the instance. |
400 | MissingParameter.Architecture | Architecture should not be null. | Architecture is required. |
400 | InvalidArchitecture.Malformed | Architecture is not valid. | Invalid Architecture value. |
400 | MissingParameter.Platform | Platform should not be null. | Platform is required. |
400 | InvalidPlatform.Malformed | Platform is not valid. | Invalid Platform value. |
400 | InvalidParameter.AllEmpty | %s | The required parameters are not specified. |
400 | InvalidDiskId.NotFound | The specified disk do not exist. | The DiskId is not found. |
400 | InvalidDatadisk.DiskStatusViolation | The operation is not permitted due to status of the Datadisk. | The data disk in the current state does not support this operation. |
400 | InvalidDatadisk.DiskCategoryViolation | The operation is not permitted due to category of the Datadisk. | The data disk of the category does not support this operation. |
400 | InvalidSystemDiskSize.ValueNotSupported | The specified SystemDiskSize is not valid. | Invalid SystemDisk.Size value. |
400 | InvalidInstance.NotFoundSystemDisk | The specified instance has no system disk. | The specified instance has no system disk attached. Make sure that the specified instance has a system disk attached. You can call the DescribeInstances operation to query the details of the instance. |
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 used capacity of disks that belong to the specified disk category exceeds the quota limit for the zone. You can go to Quota Center to view and increase the disk capacity quota. |
403 | InvalidSystemDiskStatus.IsTransfering | The current status of the resource does not support this operation, system disk is transfering. | The resource in the current state does not support this operation. Try again after the system disk stops transmitting data. |
403 | IncorrectDiskStatus | The current disk status does not support this operation. | This operation cannot be performed on the disk in the current state. Make sure that the disk is available and that you have no overdue payments for it. |
403 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | The resource in the current state does not support this operation. |
403 | InstanceLockedForSecurity | The instance is locked due to security. | The operation is not allowed when the resource is locked for security reasons. |
403 | ImageNotSubscribed | The specified image has not be subscribed. | You have not subscribed to the image in Alibaba Cloud Marketplace. |
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 Alibaba Cloud Marketplace image is unavailable, or the 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). | The instance has expired or has an overdue payment. Renew or complete the payment for the instance and try again. |
403 | ChargeTypeViolation | The operation is not permitted due to charge type of the instance. | This operation cannot be performed on the instance that uses the current billing method. |
403 | DiskCreatingSnapshot | The operation is denied due to a snapshot of the specified disk is not completed yet. | A snapshot is being created for the specified disk. |
403 | IoOptimized.NotSupported | The specified image is not support IoOptimized Instance. | The image does not support I/O optimized instances. |
403 | ImageNotSupportInstanceType | The specified image don not support the InstanceType instance. | The specified image does not support the instance type. |
403 | QuotaExceed.BuyImage | The specified image is from the image market,You have not bought it or your quota has been exceeded. | You have not purchased the specified Alibaba Cloud Marketplace image or your image quota was used up. |
403 | INST_HAS_UNPAID_ORDER | The instance has unpaid order. | Your account has unpaid orders for the instance. |
403 | OperationDenied.InstanceCreating | The specified instance is creating. | The specified instance is being created. |
403 | InvalidParameter.NotMatch | %s | Invalid parameter value. Check whether parameter conflicts exist. |
403 | ResourcesNotInSameZone | The specified instance and disk are not in the same zone. | The instance and disk do not reside in the same zone. |
403 | ImageNotSupportInstanceType | The specified instanceType is not supported by instance with marketplace image. | The specified Alibaba Cloud Marketplace image does not support the instance type. |
403 | OperationDenied.UnpaidOrder | The specified instance has unpaid order. | You have unpaid orders for the instance. You can log on to the ECS console to pay for the orders. |
403 | OperationDenied.ImageNotValid | %s | The image does not support this operation. |
403 | HibernationConfigured.InstanceOperationForbidden | The operation is not permitted due to limit of the hibernation configured instance. | The operation is not allowed due to the limits of instances for which the instance hibernation feature is enabled. |
403 | InvalidOperation.MultiAttachDisk | Multi attach disk does not support this operation. | The disk for which the multi-attach feature is enabled does not support this operation. |
403 | InvalidParameter.KmsNotEnabled | The specified operation need enable KMS. | You must activate KMS. |
403 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | The KMSKeyId is not found. |
403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | The CMK is not enabled when the ID of the CMK is specified for a disk. You can call the DescribeKey operation of KMS to query the information about the specified CMK. |
403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service have no right to access your KMS. | ECS is not authorized to access your KMS resources. |
404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | The InstanceId is not found. |
404 | InvalidInstanceId.NotFound | The specified instance does not exist. | The instance is not found. Check whether the instance ID is correct. |
404 | InvalidImageId.NotFound | The specified ImageId does not exist. | The image is not found in this account. Check whether the image ID is correct. |
404 | InvalidSystemDiskSize.MoreThanMaxSize | The specified SystemDisk.Size parameter exceeds the maximum size. | The maximum system disk size is exceeded. |
404 | InvalidSystemDiskSize.LessThanImageSize | The specified parameter SystemDisk.Size is less than the image size. | The system disk size is smaller than the image size. |
404 | InvalidSystemDiskSize.LessThanMinSize | The specified parameter SystemDisk.Size is less than the min size. | The specified system disk size is smaller than the minimum allowable size. |
404 | NoSuchResource | The specified resource is not found. | The specified resource is not found. |
500 | OperationDenied | Internal Error. | An internal error occurred. |
500 | InternalError | The request processing has failed due to some unknown error. | An internal error occurred. Try again later. |
500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | An internal error occurred. Try again later. |
For a list of error codes, see Service error codes.