You can call this operation to attach a pay-as-you-go data disk or a system disk to an ECS instance. The disk and the instance must be in the same zone.

Description

When you call this operation, note that:

  • The disk must be in the Available state.
  • If the disk to be attached is a data disk,
    • the target ECS instance must be in the Running or Stopped state.
    • and the disk is separately purchased, the disk must be billed on a pay-as-you-go basis.
    • and the disk is a system disk detached from an ECS instance, the disk can be billed on a pay-as-you-go or a subscription basis.
  • If the disk to be attached is a system disk,
    • the target instance must be the source instance from which the system disk has been detached.
    • the target instance must be in the Stopped state.
    • You must configure the instance logon credentials.
  • If the ECS instance is under security control and its OperationLocks parameter is set to "LockReason" : "security", the instance cannot be started.
  • Even if you set the DeleteWithInstance parameter to false when you attach the disk, if the ECS instance is under security control (the OperationLocks parameter is set to "LockReason" : "security"), the DeleteWithInstance attribute of the disk is to be ignored and the disk is to be released together with 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
InstanceId String Yes i-bp1ecr********5go2go

The ID of the target ECS instance.

DiskId String Yes d-23jbf2v*************

The ID of the disk to be attached. The disk and the instance must be in the same zone. That is, the DiskId parameter and the InstanceId parameter must be set to the same value.

Note Both data disks and system disks can be attached to instances. For more information about their corresponding limits, see the preceding "Description" section in this topic.
Action String No AttachDisk

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

Bootable Boolean No false

Specifies whether to attach the disk as a system disk.

Default value: false.

Note The target ECS instance must have no system disk attached when you set Bootable=true.
DeleteWithInstance Boolean No false

Specifies whether to release the disk with the instance.

  • true: The disk is to be released together with the instance.
  • false: The disk is not to be released together with the instance. The disk is changed into a pay-as-you-go data disk and is retained.

Default value: false.

Password String No EcsV587!

Specifies the password corresponding to the username when you attach a system disk to an instance. The password is valid only for the administrator and root usernames, but not for other usernames. The password must be 8 to 30 characters in length. The password must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. Special characters include

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

Passwords for Windows instances cannot start with a forward slash (/).

Note If the Password parameter is specified, we recommend that you send requests over HTTPS to ensure the security of your password.
KeyPairName String No Instancetest

Specifies the name of the SSH key pair to be bound to the Linux instance when a system disk is to be attached.

  • Windows Server instances: SSH key pairs are not supported by the instance. The Password parameter is still used even if the KeyPairName parameter is specified.
  • Linux instances: logon by password is disabled by default.
Device String No null

The name of the disk.

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

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-23jbf2v*************
&InstanceId=i-bp1ecr********5go2go
&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
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified value of the InstanceId parameter does not exist.
404 InvalidDiskId.NotFound The specified disk does not exist. The error message returned because the specified value of the DiskId parameter does not exist.
400 InvalidDevice.Malformed The specified device is not valid. The error message returned because the specified value of the Device parameter does not exist.
403 InstanceDiskLimitExceeded The amount of the disk on instance in question reach its limits. The error message returned because the specified instance has been attached with the allowed maximum number of disks.
403 InvalidDevice.InUse The specified device has been occupied. The error message returned because the specified device already has a disk attached.
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. Ensure that the disk is available and has no overdue payments.
403 DiskNotPortable The specified disk is not a portable disk. The error message returned because the specified disk is not detachable when the Portable parameter is set to false.
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 the 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 first.
403 DiskInArrears The specified operation is denied as your disk owing fee. The error message returned because the specified disk has overdue payments.
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 instance is in the current state.
403 DiskError IncorrectDiskStatus. The error message returned because the specified disk status is invalid.
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. If the problem persists, submit a ticket.
400 InvalidParameter The input parameter is mandatory for processing this request is empty. The error message returned because the required parameter is not specified.
403 DiskId.ValueNotSupported The specified parameter diskid is not supported. The error message returned because the specified value of the DiskId parameter is invalid.
403 DiskId.StatusNotSupported The specified disk status is not supported. The error message returned because the specified disk is in a state that does not support this operation.
404 InvalidDisk.InUse The specified disk has been occupied. The error message returned because the specified disk is already in use.
404 DiskAttachedNumberExceeded The attaching times of the specified disk exceeded. The error message returned because the duration for attaching the disk is exceeded.
403 UserNotInTheWhiteList The user is not in disk white list. The error message returned because you are not authorized to use the specified disk.
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 operation is not supported by the specified disk type.
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 an I/O optimized instance. Only I/O optimized instances support KMS keys.
403 InvalidParameter.KMSKeyId.KMSUnauthorized ECS service have no right to access your KMS. The error message returned because ECS is not authorized to access your KMS resources.
500 InternalError The request processing has failed due to some unknown error, exception or failure. The error message returned because an unknown error has occurred.
400 InvalidParameter.AllEmpty %s The error message returned because the required parameter is not specified.

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