All Products
Search

This Product

    Elastic Compute Service:ReplaceSystemDisk

    Document Center

    Elastic Compute Service:ReplaceSystemDisk

    Last Updated:Dec 17, 2024

    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 Stopped state.

      **

      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 OperationLocks in 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.Size to 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 OperationLocks parameter is empty, the system disk is replaced.

    Debugging

    You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

    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 Resources is 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.
    OperationAccess levelResource typeCondition keyAssociated operation
    ecs:ReplaceSystemDiskupdate
    *Disk
    acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}
    *Image
    acs:ecs:{#regionId}:{#accountId}:image/{#imageId}
    *Instance
    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    InstanceIdstringYes

    The instance ID.

    		i-bp67acfmxazb4ph****
    ImageIdstringNo

    The ID of the image to be used to replace the system disk.

    If the DiskId parameter is not specified, this parameter is required.

    		m-bp67acfmxazb4ph****
    SystemDisk.SizeintegerNo

    The capacity of the new system disk. Unit: GiB. Valid values for different disk categories:

    • Basic disk: Max{20, Size of the image specified by ImageId} to 500.

    • Enterprise SSD (ESSD):

      • PL0: Max{1, Size of the image specified by ImageId} to 2048.
      • PL1: Max{20, Size of the image specified by ImageId} to 2048.
      • PL2: Max{461, Size of the image specified by ImageId} to 2048.
      • PL3: 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: 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
    ClientTokenstringNo

    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
    UseAdditionalServicebooleanNo

    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
    PasswordstringNo

    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!
    PasswordInheritbooleanNo

    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
    KeyPairNamestringNo

    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
    DiskIdstringNo
    Note This parameter is deprecated. To improve compatibility, we recommend that you use ImageId.
    		d-bp67acfmxazb4ph****
    PlatformstringNo
    Note This parameter is deprecated.
    		CentOS
    ArchitecturestringNo
    Note This parameter is deprecated.
    		i386
    SecurityEnhancementStrategystringNo

    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
    EncryptedbooleanNo

    Specifies whether to encrypt the disk. Valid values:

    • true: encrypts the disk.
    • false: does not encrypt the disk.

    Default value: false

    		false
    KMSKeyIdstringNo

    The ID of the KMS key to use for the system disk.

    		e522b26d-abf6-4e0d-b5da-04b7******3c
    EncryptAlgorithmstringNo
    Note This parameter is not available for public use.
    		hide
    Arnarray<object>No

    This parameter is not available for public use.

    objectNo
    RoleTypestringNo
    Note This parameter is not available for public use.
    		null
    RolearnstringNo
    Note This parameter is not available for public use.
    		null
    AssumeRoleForlongNo
    Note This parameter is unavailable.
    		0

    Response parameters

    ParameterTypeDescriptionExample
    object
    DiskIdstring

    The ID of the new system disk.

    		d-bp67acfmxazb4ph****
    RequestIdstring

    The request ID.

    		473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

    Examples

    Sample success responses

    JSONformat

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

    Error codes

    HTTP status codeError codeError messageDescription
    400LoginAsNonRoot.ImageNotSupportThe specified image does not support login as non-root.The image does not support the logons of non-root users.
    400InvalidSystemDiskSize.ValueNotSupportedThe specified parameter SystemDisk.Size is invalid.The specified SystemDisk.Size parameter is invalid.
    400InvalidParameter.ConflictThe specified image does not support the specified instance type.The specified image cannot be used for instances of the specified instance type.
    400InvalidSystemDiskSize.ImageNotSupportResizeThe specified image does not support resize.The specified image does not support resizing.
    400InvalidSystemDiskSizeThe specified parameter SystemDisk.Size is invalid.The specified SystemDisk.Size parameter is invalid.
    400InvalidPassword.MalformedThe specified parameter "Password" is not valid.-
    400InvalidPasswordParam.MismatchThe input password should be null when passwdInherit is true.The Password parameter must be left empty when the PasswdInherit parameter is used.
    400OperationDeniedThe 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.
    400InvalidDiskCategory.ValueNotSupportedThe specified parameter "DiskCategory" is not valid.-
    400InvalidParameter.Conflict%sThe specified parameter is invalid. Check whether parameter conflicts exist. %s is a variable. An error message is dynamically returned based on call conditions.
    400InvalidSystemDiskSize.ValueNotSupported%sThe specified system disk size is invalid.
    400OperationDenied%sThe operation is denied.
    400InvalidKeyPairName.NotFoundThe specified KeyPairName does not exist.The specified KeyPairName parameter does not exist.
    400DependencyViolation.IoOptimizeThe specified parameter InstanceId is not valid.The I/O optimization configuration of the instance is invalid.
    400MissingParameter.ArchitectureArchitecture should not be null.The Architecture parameter is required.
    400InvalidArchitecture.MalformedArchitecture is not valid.The specified Architecture parameter is invalid.
    400MissingParameter.PlatformPlatform should not be null.The Platform parameter is required.
    400InvalidPlatform.MalformedPlatform is not valid.The specified Platform parameter is invalid.
    400InvalidParameter.AllEmpty%sThe required parameters are not specified.
    400InvalidDiskId.NotFoundThe specified disk do not exist.-
    400InvalidDatadisk.DiskStatusViolationThe operation is not permitted due to status of the Datadisk.-
    400InvalidDatadisk.DiskCategoryViolationThe operation is not permitted due to category of the Datadisk.-
    400InvalidDatadisk.ChargeTypeViolationThe operation is not permitted due to charge type of the Datadisk.-
    400InvalidSystemDiskSize.ValueNotSupportedThe specified SystemDiskSize is not valid.The specified SystemDisk.Size parameter is invalid.
    400MissingParameterThe input parameter "ImageId" that is mandatory for processing this request is not supplied.-
    400InvalidInstance.NotFoundSystemDiskThe 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.
    400InvalidParameter.DiskTypeThe specified disk type which has kms key can't convert to system disk.-
    400DISK_IN_DEDICATED_BLOCK_STORAGE_CLUSTERThe disk in dedicated block storage cluster is not allowed to do this operation.-
    400IncorrectDiskStatus.ReplicationStatusNotFoundDisk replication status not found.-
    400IncorrectDiskStatus.InReplicationDisk already in replication.-
    400InvalidInstanceType.NotSupportedThe specified instanceType is not supported by the image architecture.-
    400InvalidRegionId.NotSupportReplaceEncryptedSystemDiskThe specified region not support replace encrypted system disk.-
    400InvalidStorageClusterId.CapacityNotEnoughThe 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.
    400QuotaExceed.DiskCapacityThe 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.
    403LoginAsNonRoot.RegionNotSupportThe specified region does not support login as non-root.-
    403InvalidSystemDiskStatus.IsTransferingThe 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.
    403IncorrectDiskStatusThe 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.
    403IncorrectInstanceStatusThe current status of the resource does not support this operation.The resource is in a state that does not support the current operation.
    403InstanceLockedForSecurityThe instance is locked due to security.The operation is not supported while the instance is locked for security reasons.
    403ImageNotSubscribedThe specified image has not be subscribed.You have not subscribed to the specified image in Alibaba Cloud Marketplace.
    403ImageRemovedInMarketThe 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.
    403InstanceExpiredOrInArrearsThe 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.
    403ChargeTypeViolationThe 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.
    403DiskCreatingSnapshotThe operation is denied due to a snapshot of the specified disk is not completed yet.A snapshot is being created for the specified disk.
    403IoOptimized.NotSupportedThe specified image is not support IoOptimized Instance.The specified image does not support I/O optimized instances.
    403ImageNotSupportInstanceTypeThe specified image don not support the InstanceType instance.The specified image does not support the instance type.
    403QuotaExceed.BuyImageThe 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.
    403INST_HAS_UNPAID_ORDERThe instance has unpaid order.Your account has unpaid orders for the instance.
    403OperationDenied.InstanceCreatingThe specified instance is creating.The specified instance already exists.
    403DependencyViolation.WindowsInstanceThe instance creating is windows, cannot use ssh key pair to login.-
    403InvalidParameter.NotMatch%sA specified parameter is invalid. Check whether parameter conflicts exist.
    403ResourcesNotInSameZoneThe specified instance and disk are not in the same zone.The specified instance and disk are not in the same zone.
    403ImageNotSupportInstanceTypeThe specified instanceType is not supported by instance with marketplace image.The specified Alibaba Cloud Marketplace image does not support the instance type.
    403OperationDenied.UnpaidOrderThe 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.
    403InvalidHostname.MismatchImageThe hostname of the current instance can not be applied to the image you choose.-
    403OperationDenied.ImageNotValid%sThe current image does not support this operation.
    403HibernationConfigured.InstanceOperationForbiddenThe 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.
    403InvalidOperation.MultiAttachDiskMulti attach disk does not support this operation.Disks for which the multi-attach feature is enabled do not support the operation.
    403InvalidRegionId.NotSupportEncryptAlgorithmThe current region does not support creating encrypted disks with EncryptAlgorithm.-
    403InvalidRegionId.NotExistsThe region not exists.-
    403InvalidEncryptAlgorithmThe specified parameter EncryptAlgorithm is not valid.-
    403InvalidEncrypted.NotMatchKmsKeyIdThe specified parameter Encrypted must be true when KmsKeyId is not empty.-
    403InvalidEncrypted.NotMatchEncryptAlgorithmThe specified parameter Encrypted must be true when EncryptAlgorithm is not empty.-
    403InvalidParameter.KmsNotEnabledThe specified operation need enable KMS.The current operation requires opening KMS
    403InvalidParameter.DataEncryptedKeyCreateFailedCreate 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.
    403InvalidParameter.KMSKeyId.NotFoundThe specified KMSKeyId does not exist.The specified KMSKeyId parameter does not exist.
    403InvalidParameter.KMSKeyId.CMKUnauthorizedThis operation for kmsKeyId is forbidden by KMS. If you need further assistance, you can contact the KMS Technical Support.-
    403InvalidParameter.KMSKeyId.CMKNotEnabledThe 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.
    403InvalidParameter.KMSKeyId.KMSUnauthorizedECS service have no right to access your KMS.ECS is not authorized to access your KMS resources.
    403InvalidKMSKeyId.NotSymmetricThe specified parameter KmsKeyId must be symmetric.-
    403InvalidEncrypted.NotMatchKmsKeyIdThe specified parameter Encrypted must be true when kmsKeyId is not null.-
    403InvalidDiskId.NotSupportReplaceEncryptedSystemDiskThe specified diskId not support replace encrypted system disk.-
    403NotSupportSnapshotEncrypted.DiskCategoryThe 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.
    403InvalidEncrypted.DefaultEncryptionUnsupportedThe 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.
    404InvalidInstanceId.NotFoundThe specified InstanceId does not exist.The specified instance does not exist.
    404InvalidInstanceId.NotFoundThe specified instance does not exist.The specified instance does not exist. Check whether the instance ID is correct.
    404InvalidImageId.NotFoundThe specified ImageId does not exist.The specified image does not exist in this account. Check whether the image ID is correct.
    404InvalidSystemDiskSize.MoreThanMaxSizeThe specified SystemDisk.Size parameter exceeds the maximum size.The maximum size of the system disk is exceeded.
    404InvalidSystemDiskSize.LessThanImageSizeThe specified parameter SystemDisk.Size is less than the image size.The specified system disk size is smaller than the image size.
    404InvalidSystemDiskSize.LessThanMinSizeThe specified parameter SystemDisk.Size is less than the min size.The specified system disk size is smaller than the minimum allowable size.
    404NoSuchResourceThe specified resource is not found.The specified resource does not exist.
    500OperationDeniedInternal Error.An internal error has occurred.
    500InternalErrorThe request processing has failed due to some unknown error.An internal error has occurred. Try again later.
    500InternalErrorThe request processing has failed due to some unknown error, exception or failure.An internal error has occurred. Try again later.
    500OperationDeniedThe 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 timeSummary of changesOperation
    2024-12-04API Description Update. The API operation is not deprecated.. The Error code has changedView Change Details
    2024-06-27The Error code has changedView Change Details
    2024-05-08The Error code has changedView Change Details
    2024-01-15The Error code has changedView Change Details
    2021-12-06The Error code has changedView Change Details