AttachDisk
Attaches a data disk or a system disk to an ECS instance.
Operation description
When you call this operation, take note of the following items:
-
The instance and the disk must reside in the same zone.
-
The disk must be in the Available state.
-
When you attach a data disk:
The destination ECS instance must be in the Running or Stopped state.
If the disk was purchased separately, its billing method must be pay-as-you-go.
If a system disk detached from an ECS instance is attached as a data disk, its billing method is not restricted.
Once an elastic ephemeral disk is detached, it can only be reattached to its original instance.
-
When you attach a system disk:
The destination ECS instance must be the source instance from which the system disk was detached.
The destination ECS instance must be in the Stopped state.
You must configure the logon credentials for the instance.
Elastic ephemeral disks cannot be attached as system disks.
For more information about attaching a system disk, see Detach or attach a system disk.
-
When you query the information of an ECS instance, if the response contains
{"OperationLocks": {"LockReason" : "security"}}, all operations on the instance are prohibited. -
Disks with the multi-attach attribute enabled can only be attached to instances that support the NVMe protocol. For more information, see Enterprise SSDs support NVMe and Enable the multi-attach feature.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:AttachDisk |
update |
*Disk
*Instance
|
|
None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| InstanceId |
string |
Yes |
The ID of the ECS instance to which you want to attach the disk. |
i-bp1dq5lozx5f4pmd**** |
| DiskId |
string |
Yes |
The ID of the disk that you want to attach. The disk (DiskId) and the instance (InstanceId) must reside in the same zone. Note
You can attach both data disks and system disks. For the related constraints, see the operation description section above. |
d-bp1j4l5axzdy6ftk**** |
| Device |
string |
No |
The device name of the disk. Note
This parameter will be deprecated. To improve compatibility, use other parameters to identify the disk. |
testDeviceName |
| DeleteWithInstance |
boolean |
No |
Specifies whether to release the disk when the instance is released. Valid values:
Default value: false. When you configure this parameter, take note of the following items:
|
false |
| Bootable |
boolean |
No |
Specifies whether to attach the disk as a system disk. Valid values:
Default value: false. Note
If you set Bootable to true, the destination ECS instance must not have a system disk attached. |
false |
| Password |
string |
No |
The logon password for the instance, which is configured when you attach a system disk. This parameter takes effect only for the administrator and root usernames. The password must be 8 to 30 characters in length and must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. The following special characters are supported:
For Windows instances, the password cannot start with a forward slash (/). Note
If you specify the Password parameter, use HTTPS to send the request to prevent password leaks. |
EcsV587! |
| KeyPairName |
string |
No |
The name of the SSH key pair to bind to a Linux ECS instance when you attach a system disk.
|
KeyPairTestName |
| Force |
boolean |
No |
Specifies whether to forcibly attach the disk. Valid values:
Default value: false. Note
Currently, only regional Enterprise SSDs (ESSDs) (cloud_regional_disk_auto) support setting this parameter to true. |
false |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
Examples
Success response
JSON format
{
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidDevice.Malformed | The specified parameter Device is not valid. Please check the device name and try again. | |
| 400 | 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. |
| 400 | InvalidParameter | The input parameter is mandatory for processing this request is empty. | A required parameter is not specified. |
| 400 | InvalidRegionId.MalFormed | The specified RegionId is not valid. | |
| 400 | InvalidOperation.InstanceTypeNotSupport | The instance type of the specified instance does not support hot attach disk. | The instance to which the disk is attached does not support the hot swapping of disks. |
| 400 | DiskCategory.OperationNotSupported | The disk category of the specified disk does not support the current operation. Please check the operations supported by the disk category and try again. | |
| 400 | InvalidDisk.DiskNotBootable | The specified disk is not a bootable disk. It cannot be attached as a system disk. | |
| 400 | InvalidInstance.NotOriginInstance | The specified disk can not attached to other instance as system disk. | |
| 400 | InvalidParameterForce.DiskCategoryNotSupported | The specified disk category does not support force attach operation. | The specified disk category does not support force attach operation. |
| 400 | InvalidParameterForce.PrepaidDiskNotSupported | The prepaid disk does not support force attach operation. | The prepaid disk does not support force attach operation. |
| 400 | InvalidParameterForce.MultiAttachDiskNotSupported | The multi attach disk does not support force attach operation. | The multi attach disk does not support force attach operation. |
| 400 | InvalidParameterForce.RegionNotSupported | The specified region does not support force attach operation. | The specified region does not support force attach operation. |
| 400 | OperationConflict.DisksAttachingParallellyExceed | The number of disks being attached in parallel exceeds the limit. Please wait for the ongoing attach operations to complete and try again. | |
| 400 | InvalidInstanceType.NotSupported | The specified instanceType is not supported by the image architecture. | The specified image schema does not support this instance type. |
| 400 | InvalidOperation.EncryptedDiskUnsupported | The specified encrypted disk is not supported for this operation. | |
| 400 | InvalidOperation.ForceAttachConflict | The device still has mount residue on the source instance. Please ensure no residual mount points exist in the source instance and try again. | |
| 400 | InvalidKeyPairName.NotFound | The specified KeyPairName does not exist. Please verify the KeyPairName and the current region and try again. | |
| 500 | InternalError | The request processing has failed due to an internal error and you may retry later or contact support with the request ID. | |
| 403 | InstanceDiskLimitExceeded | The number of disks attached to the instance has exceeded the limit. | |
| 403 | InvalidDevice.InUse | The specified Device is already in use. Please specify another device name and try again. | |
| 403 | DiskNotPortable | The specified disk is not a portable disk. | |
| 403 | InstanceLockedForSecurity | Operation failed because the instance attached to this disk is locked for security reasons. Please open a ticket to contact our security team if you have any questions. | |
| 403 | ResourcesNotInSameZone | 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). | |
| 403 | DiskInArrears | The specified operation is denied because the disk has overdue payments. Please settle the outstanding balance. | |
| 403 | DiskError | IncorrectDiskStatus. | |
| 403 | DiskId.ValueNotSupported | The category of the specified disk is not supported. Please use a disk of a supported category and try again. | |
| 403 | DiskId.StatusNotSupported | The specified disk status is not supported. | The disk is in a state that does not support the current operation. |
| 403 | IncorrectInstanceStatus.NotSupportESSD | The operation is not supported in this status. Please reboot the instance. | |
| 403 | IncorrectDiskStatus | The operation is not supported in this status. | 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 | UserNotInTheWhiteList | The current account is not in the allowlist for this operation. Please submit a ticket to apply for access. | |
| 403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | |
| 403 | InvalidParameter.KMSKeyId.CMKUnauthorized | The CMK has not authorized the ECS service to perform the KMS TagResource and UntagResource operations. Please verify the authorization and try again. | |
| 403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service does not have permission to access your KMS key. Please verify that the specified KMS key has authorized the ECS service. | |
| 403 | DependencyViolation.WindowsInstance | The instance image is Windows. SSH key pair login is not supported. Please use a password instead of an SSH key pair and try again. | |
| 403 | InvalidInstanceType.NotSupportDiskCategory | The instance type of the specified instance does not support the specified disk category. Please call DescribeAvailableResource to query the supported disk category and try again. | |
| 403 | InvalidInstanceType.NotSupportPL0 | The instance type of the specified instance does not support cloud_essd PL0. Please call DescribeAvailableResource to query the supported disk category and try again. | |
| 403 | InvalidInstanceType.NvmeRequired | The instanceType of the specified instance requires nvme protocol. | The instance type of the specified instance requires the NVMe protocol. |
| 403 | InvalidInstanceType.NvmeUnsupported | The instanceType of the specified instance does not support nvme protocol. | The instance type of the specified instance does not support the NVMe protocol. |
| 403 | InvalidInstanceType.NotSupportMultiAttachDisk | The instance type of the specified instance does not support multi-attach disks. Please attach a disk without multi-attach enabled and try again. | |
| 403 | DiskAttachedNumberExceeded | The attaching times of the specified disk exceeded. | The specified disk has reached the maximum number of instances to which it can be attached. |
| 403 | InvalidOperation.CanNotAttachMultiAttachDiskAsSystemDisk | Multi attach disk can not be attached as system disk. | 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. | Disks for which the multi-attach feature is enabled do not support the DeleteWithInstance attribute. |
| 403 | InvalidParameter.DeleteWithInstance | The DeleteWithInstance for the elastic ephemeral disk must be set to true. | The DeleteWithInstance for the elastic ephemeral disk must be set to true. |
| 403 | InvalidOperation.OtherInstanceUnsupported | The elastic ephemeral disk can only be attached to the instance it was last mounted on. Please check the disk system tag to get the last associated instance. | |
| 403 | InvalidInstance.ZoneConflict | The force attach operation is not supported when both the current and target instances are in the same zone. Please attach the disk without the Force parameter or choose a target instance in another zone and try again. | |
| 403 | InvalidParameter.AllEmpty | The current operation requires either a password or a keyPairName to must be provided. Please ensure that at least one of them is not empty. | The current operation requires either a password or a keyPairName to must be provided. Please ensure that at least one of them is not empty. |
| 403 | InvalidOperation.DiskQueueNumberNotEnough | The number of disk queues on the instance is not enough. | The number of disk queues on the instance is not enough. |
| 403 | InvalidOperation.DiskAttachModeUnsupported | The instance type does not support the disk attach mode. | The instance type does not support the disk mount mode. |
| 403 | OperationDenied.HpnZoneMismatch | Instance and disk must be in the same HPN zone for restricted HPN zones. | Instance and disk must be in the same HPN zone for restricted HPN zones. |
| 403 | OperationDenied.UnsupportedEncryptedDisk | The instance type does not support attaching encrypted disks. | The instance type does not support attaching encrypted disks. |
| 404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. Please verify the InstanceId and the current region and try again. | |
| 404 | InvalidDiskId.NotFound | The specified disk does not exist. Please verify the DiskId and the current region and try again. | |
| 404 | InvalidDisk.InUse | The specified disk has been occupied. | |
| 404 | DiskAttachedNumberExceeded | The attaching times of the specified disk exceeded. | |
| 404 | InvalidKMSKeyId.NotFound | The specified KMSKeyId does not exist. Please verify that the key ID is correct and that the key resides in the current region. | |
| 503 | LimitedOperation.ServiceUnavailable | The service is currently unavailable. Please try again later. | The service is currently unavailable. Please try again later. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.