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.
Operation description
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.**
Note The operation is applicable only to instances of the Virtual Private Cloud (VPC) type. 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 .
-
The ECS instance cannot be locked for security reasons. If the value of
OperationLocksin the DescribeInstances response contains"LockReason": "security"for an instance, the instance is locked for security reasons. For more information, see API behavior when an instance is locked for security reasons. -
No unpaid orders are associated with the instance.
-
You can configure
SystemDisk.Sizeto specify the capacity of the new system disk.
After you call the ReplaceSystemDisk operation, you can use one of the following methods to check whether the system disk is replaced:
- Call the DescribeDisks operation to query the status 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 status of the instance whose system disk is replaced. If the
OperationLocksparameter is empty, the system disk is replaced.
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resourcesis used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| ecs:ReplaceSystemDisk | update | *Disk acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}*Image acs:ecs:{#regionId}:{#accountId}:image/{#imageId}*Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId} |
| none |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| InstanceId | string | Yes | The instance ID. | i-bp67acfmxazb4ph**** |
| ImageId | string | No | The ID of the image to be used to replace the system disk. If the | m-bp67acfmxazb4ph**** |
| SystemDisk.Size | integer | No | The capacity of the new system disk. Unit: GiB. Valid values for different disk categories:
Default value: 40 or the size of the image specified by ImageId, whichever is greater. 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:
Default value: Deactive. | Active |
| Encrypted | boolean | No | Specifies whether to encrypt the disk. Valid values:
Default value: false | 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 | long | No | Note
This parameter is unavailable.
| 0 |
Response parameters
Examples
Sample success responses
JSONformat
{
"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. | The specified SystemDisk.Size parameter 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. | The specified SystemDisk.Size parameter 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. | - |
| 400 | InvalidParameter.Conflict | %s | The specified parameter is invalid. Check whether parameter conflicts exist. %s is a variable. An error message is dynamically returned based on call conditions. |
| 400 | InvalidSystemDiskSize.ValueNotSupported | %s | The specified system disk size is invalid. |
| 400 | OperationDenied | %s | The operation is denied. |
| 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 | InvalidParameter.AllEmpty | %s | The required parameters are not specified. |
| 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 | InvalidSystemDiskSize.ValueNotSupported | The specified SystemDiskSize is not valid. | The specified SystemDisk.Size parameter is invalid. |
| 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. | - |
| 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. |
| 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. | The disk is in a state that does not support the current operation. Make sure that the disk is available and that your account has no overdue payments. |
| 403 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | The resource is in a state that does not support the current 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. | You have not subscribed to the specified 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 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). | The subscription instance has expired. You must renew the instance before you can proceed. |
| 403 | ChargeTypeViolation | The operation is not permitted due to charge type of the instance. | The operation is not supported while the instance is using 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 specified 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 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. | Your account has unpaid orders for the instance. |
| 403 | OperationDenied.InstanceCreating | The specified instance is creating. | The specified instance already exists. |
| 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. | The specified instance and disk are not 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. | 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 | OperationDenied.ImageNotValid | %s | The current image does not support this operation. |
| 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. | The current operation requires opening KMS |
| 403 | InvalidParameter.DataEncryptedKeyCreateFailed | Create kms data encrypted key fail. If you need further assistance, you can contact the KMS Technical Support. | - |
| 403 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | The specified KMSKeyId parameter does not exist. |
| 403 | InvalidParameter.KMSKeyId.CMKUnauthorized | This operation for kmsKeyId is forbidden by KMS. If you need further assistance, you can contact the KMS Technical Support. | - |
| 403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | The customer master key (CMK) is not enabled when KMSKeyId is specified for an encrypted disk. You can call the DescribeKey operation of KMS to query 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. |
| 403 | InvalidKMSKeyId.NotSymmetric | The specified parameter KmsKeyId must be symmetric. | - |
| 403 | InvalidEncrypted.NotMatchKmsKeyId | The specified parameter Encrypted must be true when kmsKeyId is not null. | - |
| 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 | InvalidEncrypted.DefaultEncryptionUnsupported | The specified parameter Encrypted must be true when default encryption is enabled. | After the cloud disk is encrypted by default, the newly purchased cloud disk must be an encrypted cloud disk. |
| 404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | The specified instance does not exist. |
| 404 | InvalidInstanceId.NotFound | The specified instance does not exist. | The specified instance does not exist. Check whether the instance ID is correct. |
| 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. | The maximum size of the system disk is exceeded. |
| 404 | InvalidSystemDiskSize.LessThanImageSize | The specified parameter SystemDisk.Size is less than the image size. | The specified 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 does not exist. |
| 500 | OperationDenied | Internal Error. | An internal error has occurred. |
| 500 | InternalError | The request processing has failed due to some unknown error. | An internal error has occurred. Try again later. |
| 500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | An internal error has occurred. Try again later. |
| 500 | OperationDenied | The specified InstanceType or Zone is not available or not authorized. | The specified instance type or zone is unavailable or you are not authorized to use the specified instance type or access the specified zone. |
For a list of error codes, visit the Service error codes.
Change history
| Change time | Summary of changes | Operation |
|---|---|---|
| 2024-06-27 | The Error code has changed | View Change Details |
| 2024-05-08 | The Error code has changed | View Change Details |
| 2024-01-15 | The Error code has changed | View Change Details |
| 2021-12-06 | The Error code has changed | View Change Details |