Attaches a pay-as-you-go data disk or a system disk to an instance. The instance and the disk must reside in the same zone.

Description

When you call this operation, take note of the following items:

  • The disk must be in the Unattached (Available) state.
  • When the disk is attached as a data disk, take note of the following items:
    • The instance must be in the Running (Running) or Stopped (Stopped) state.
    • If the disk is separately purchased, the billing method of the disk must be pay-as-you-go.
    • If the disk is a system disk detached from an instance, no limit applies to the billing method of the disk.
  • When the disk is attached as a system disk, take note of the following items:
    • The instance must be the original instance from which the system disk is detached.
    • The instance must be in the Stopped (Stopped) state.
    • The logon credentials must be configured.
  • When you query the instance information and the responses contain {"OperationLocks": {"LockReason" : "security"}}, the instance is locked for security reasons and all operations cannot take effect on the instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes AttachDisk

The operation that you want to perform. Set the value to AttachDisk.

DiskId String Yes d-bp1j4l5axzdy6ftk****

The ID of the disk to be attached. The disk specified by the DiskId parameter and the instance specified by the InstanceId parameter must reside in the same zone.

Note For more information about the limits on attaching a data disk and a system disk, see the "Description" section.
InstanceId String Yes i-bp1dq5lozx5f4pmd****

The ID of the instance to which to attach the disk.

Device String No testDeviceName

The name of the disk.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
DeleteWithInstance Boolean No false

Specifies whether to release the disk together with the instance. Valid values:

  • true: The disk is released together with the instance.
  • false: The disk is not released together with the instance. It is retained as a pay-as-you-go data disk.

Default value: false.

When you specify this parameter, take note of the following items:

  • If OperationLocks for an instance contains "LockReason" : "security", the instance is locked for security reasons. Even if DeleteWithInstance of attached disks is set to false, the DeleteWithInstance parameter is ignored and disks are released together with the instance.
  • This parameter is unavailable for disks for which the multi-attach feature is enabled.
Bootable Boolean No false

Specifies whether to attach the disk as a system disk.

Default value: false.

Note If the Bootable parameter is set to true, the instance must be in the No System Disk state.
Password String No EcsV587!

The password set when you attach the system disk. The password is applicable only to the administrator and root users. The password must be 8 to 30 characters in length. It must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. The following special characters can be used:


()`~!@#$%^&*-_+=|{}[]:;'<>,.?/
                                

For Windows instances, the password cannot start with a forward slash (/).

Note If the Password parameter is specified, we recommend that you send requests over HTTPS to avoid password leaks.
KeyPairName String No KeyPairTestName

The name of the SSH key pair that you bind to the Linux instance when you attach the system disk.

  • Windows instances do not support logons based on SSH key pairs. The Password parameter takes effect even if the KeyPairName parameter is specified.
  • For Linux instances, the password-based logon method is disabled by default.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=AttachDisk
&DiskId=d-bp1j4l5axzdy6ftk****
&InstanceId=i-bp1dq5lozx5f4pmd****
&DeleteWithInstance=false
&<Common request parameters>

Sample success responses

XML format

<AttachDiskResponse>
      <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
</AttachDiskResponse>

JSON format

{
    "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

Error codes

HTTP status code Error code Error message Description
400 InvalidDevice.Malformed The specified device is not valid. The error message returned because the specified Device parameter does not exist.
400 IncorrectInstanceStatus The current status of the resource does not support this operation. The error message returned because the operation is not supported while the resource is in the current state.
400 InvalidParameter The input parameter is mandatory for processing this request is empty. The error message returned because a required parameter is not specified.
400 InvalidRegionId.MalFormed The specified RegionId is not valid The error message returned because the specified RegionId parameter is invalid.
400 InvalidOperation.InstanceTypeNotSupport The instance type of the specified instance does not support hot attach disk. The error message returned because the instance to which the disk is attached does not support the hot swapping of disks.
400 DiskCategory.OperationNotSupported The operation is not supported to the specified disk due to its disk category The error message returned because the specified disk category does not support the operation.
400 InvalidOperation.InstanceTypeNotSupport The specified disk which has kms key should only attach to ioOptimized instance. The error message returned because the specified instance is not supported. You can set Key Management Service (KMS) keys only for I/O optimized instances.
400 InvalidParameter.AllEmpty %s The error message returned because the required parameters are not specified.
403 InstanceDiskLimitExceeded The amount of the disk on instance in question reach its limits. The error message returned because the maximum number of disks that can be attached to the specified instance has been reached.
403 InvalidDevice.InUse The specified device has been occupied. The error message returned because the specified device already has a disk attached.
403 DiskNotPortable The specified disk is not a portable disk. The error message returned because the specified disk is not removable.
403 InstanceLockedForSecurity The instance is locked due to security. The error message returned because the operation is not supported while the resource is locked for security reasons.
403 ResourcesNotInSameZone The specified instance and disk are not in the same zone. The error message returned because the specified instance and disk are not in the same zone.
403 InstanceExpiredOrInArrears The specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode). The error message returned because the subscription instance has expired. Renew the instance and try again.
403 DiskInArrears The specified operation is denied as your disk owing fee. The error message returned because you have overdue payments for the disk.
403 DiskError IncorrectDiskStatus. The error message returned because the state of the specified disk is invalid.
403 DiskId.ValueNotSupported The specified parameter diskid is not supported. The error message returned because the category of the specified Elastic Block Storage (EBS) device does not support this operation.
403 DiskId.StatusNotSupported The specified disk status is not supported. The error message returned because this operation is not supported while the disk is in the current state.
403 IncorrectDiskStatus The operation is not supported in this status. The error message returned because the operation is not supported while the disk is in the current state. Make sure that the disk is available and you have no overdue payments for it.
403 UserNotInTheWhiteList The user is not in disk white list. The error message returned because you are not authorized to manage the disk. Try again when you are authorized.
403 InvalidParameter.KMSKeyId.CMKNotEnabled The CMK needs to be enabled. The error message returned because the customer master key (CMK) is not enabled when a KMS key ID is specified for a 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. The error message returned because Elastic Compute Service (ECS) is not authorized to access your KMS resources.
403 InvalidInstanceType.NotSupportDiskCategory The instanceType of the specified instance does not support this disk category. The error message returned because the instance type specified by the InstanceType parameter does not support the disk category of the instance. Try another instance type. For information about the disk categories supported by instance types, see the instance family documentation.
403 InvalidInstanceType.NvmeRequired The instanceType of the specified instance requires nvme protocol. The error message returned because the instance type of the specified instance does not use the NVMe protocol.
403 InvalidInstanceType.NvmeUnsupported The instanceType of the specified instance does not support nvme protocol. The error message returned because the instance type of the specified instance does not support the NVMe protocol.
403 InvalidInstanceType.NotSupportMultiAttachDisk The instanceType of the specified instance does not support multi attach disk. The error message returned because disks for which the multi-attach feature is enabled cannot be attached to instances of the specified instance type.
403 DiskAttachedNumberExceeded The attaching times of the specified disk exceeded. The error message returned because the maximum number of instances to which the specified disk can be attached has been reached.
403 InvalidOperation.CanNotAttachMultiAttachDiskAsSystemDisk Multi attach disk can not be attached as system disk. The error message returned because disks for which the multi-attach feature is enabled cannot be attached as system disks.
403 DeleteWithInstance.Conflict Multi attach disk cannot be set to DeleteWithInstance attribute. The error message returned because the DeleteWithInstance attribute is invalid for disks for which the multi-attach feature is enabled.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified InstanceId parameter does not exist. Check whether the instance ID is correct.
404 InvalidDiskId.NotFound The specified disk does not exist. The error message returned because the specified disk does not exist. Check whether the disk ID is correct.
404 InvalidDisk.InUse The specified disk has been occupied. The error message returned because the specified disk is in use.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later.
500 InternalError The request processing has failed due to some unknown error, exception or failure. The error message returned because an internal error has occurred. Try again later.

For a list of error codes, visit the API Error Center.