CloneDisks - Elastic Compute Service - Alibaba Cloud Documentation Center

Disk cloning allows you to quickly create a new disk with the same data as the source disk in the same zone. The new disk supports custom capacity, type, and encryption attributes. After the new disk is attached to an instance, you can quickly replicate business data or horizontally scale your services.

Operation description

Note

The disk cloning feature itself is free of charge, but the new disk generated by cloning is billed based on block storage billing rules. Billable items vary by disk type and include disk capacity fees, provisioned performance fees, and performance burst fees. Except for performance burst fees, which are billed after a burst occurs, all other fees start to accrue after the disk is created, regardless of whether the disk is attached to an instance.

How to use

This is an asynchronous operation. After a successful call, use the taskGroupId and call the DescribeTasks operation to obtain the execution result.

Features

Cloning supports only ESSD series disks (cloud_essd, cloud_auto, cloud_essd_entry, cloud_regional_disk_auto) as the source, and the new disk can only be an ESSD series disk type.
- Non-regional disks can only be cloned to non-regional disk types. Regional disks can only be cloned to regional disk types.
- Local disks and elastic ephemeral disks cannot be cloned or used as clone sources.
You can specify the new disk type and performance level (PL) during cloning.
You can specify the new disk capacity during cloning, but the new disk capacity must be greater than or equal to the source disk capacity.
You can configure provisioned performance and performance burst for the new disk, provided that the destination disk type supports provisioned performance and performance burst.
You can specify encryption for the new disk and change the encryption key. If the source disk is encrypted, you cannot clone it into an unencrypted disk, but you can change the encryption key.
You can use a subscription disk as the source disk. Even if the subscription disk has expired, it can still be used as the source disk.
The new disk created by cloning does not support reinitialization.
Cloning does not support storage sets or dedicated block storage clusters, but disks in them can be used as the source disk. The cloned disk will not be in the storage set or dedicated block storage cluster.
Source disk status restrictions:
- The source disk status is "In Use" and the corresponding instance status is "Running" or "Stopped".
- The source disk status is "Available" and the disk has been previously attached.
- A disk undergoing a specification change cannot be used as the source disk.
- A disk undergoing expansion cannot be used as the source disk.
Disk cloning is not supported for instance hibernation scenarios. If a disk is on a hibernated instance, it cannot be used as the source disk.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:CloneDisks

create

*Disk

acs:ecs:{#regionId}:{#accountId}:disk/{#SourceDiskId}

*Disk

acs:ecs:{#regionId}:{#accountId}:disk/*

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
DryRun	string	No	Specifies whether to perform only a dry run, without performing the actual request. Valid values: true: sends a check request without querying the filing status. The system checks whether your AccessKey pair is valid, whether RAM user authorization is granted, and whether the required parameters are specified. If the check fails, the corresponding error is returned. If the check passes, the DryRunOperation error code is returned. false (default): sends a normal request. After the check passes, a 2XX HTTP status code is returned and the filing status is queried.	true
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but make sure that the token is unique among different requests. The ClientToken value 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
Tag	array<object>	No	The list of tags for the disk.
	object	No	The list of tags for the disk.
Key	string	No	The tag key of the disk. Valid values of N: 1 to 20. The tag key cannot be an empty string. The tag key can be up to 128 characters in length and cannot start with aliyun or acs:. The tag key cannot contain http:// or https://.	TestKey
Value	string	No	The tag value of the disk. Valid values of N: 1 to 20. The tag value can be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://.	TestValue
ResourceGroupId	string	No	The ID of the resource group to which the disk belongs.	rg-bp199lyny9b3****
SourceDiskId	string	Yes	The ID of the source disk.	d-bp1d6tsvznfghy7y****
DiskName	string	No	The name of the disk. The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-). The name must start with a letter. Default value: empty.	MyDiskName
DiskCategory	string	Yes	The category of the new disk. Valid values: cloud_essd: standard SSD. cloud_auto: ESSD AutoPL disk. cloud_essd_entry: ESSD Entry disk. cloud_regional_disk_auto: regional Standard SSD (ESSD). Note Disk category restrictions for disk cloning: Non-regional disks can only be cloned to non-regional disk types. Regional disks can only be cloned to regional disk types.	cloud_essd
PerformanceLevel	string	No	The performance level (PL) of the enterprise SSD to create. Settings for this parameter vary based on the standard SSD type. Valid values: PL0: a single disk can deliver up to 10,000 random read/write IOPS. PL1: a single disk can deliver up to 50,000 random read/write IOPS. PL2: a single disk can deliver up to 100,000 random read/write IOPS. PL3: a single disk can deliver up to 1,000,000 random read/write IOPS. Note If DiskCategory is set to cloud_essd, PerformanceLevel is required. For more information about how to select an ESSD performance level, see ESSDs.	PL1
Size	integer	Yes	The capacity of the new disk. Unit: GiB. You must specify a value for this parameter. Valid values: cloud_essd: the valid value range varies based on the performance level. PL0: 1 to 65,536. PL1: 20 to 65,536. PL2: 461 to 65,536. PL3: 1,261 to 65,536. cloud_auto: 1 to 65,536. cloud_essd_entry: 10 to 32,768. cloud_regional_disk_auto: 10 to 65,536.	60
MultiAttach	string	Yes	Specifies whether to enable the multi-attach attribute for the new disk. Settings for this parameter. Valid values: Disabled: disables the multi-attach attribute. Enabled: enables the multi-attach attribute. Only standard SSDs support the value `Enabled`.	Disabled
ProvisionedIops	integer	No	The provisioned read/write IOPS of the ESSD AutoPL disk. Valid values: Capacity (GiB) <= 3: provisioned performance is not supported. Capacity (GiB) >= 4: [0, min{(1,000 IOPS/GiB × Capacity - Baseline IOPS), 50,000}] Baseline performance = max{min{1,800 + 50 × Capacity, 50,000}, 3,000}. Note This parameter is supported only when DiskCategory is set to cloud_auto. For more information, see ESSD AutoPL disks.	10
BurstingEnabled	boolean	No	Specifies whether to enable the performance burst feature for the new disk. Valid values: true: enables the performance burst feature. false: does not enable the performance burst feature. Note This parameter is supported only when DiskCategory is set to cloud_auto. For more information, see ESSD AutoPL disks.	true
Encrypted	boolean	No	Specifies whether the new disk is encrypted. Valid values: true: The new disk is encrypted. false: The new disk is not encrypted. Default value: false.	false
KmsKeyId	string	No	The key ID of the KMS key used by the new disk.	key-szz67b2f696f4wh9yeg5d
Arn	array<object>	No	Note This parameter is not publicly available.
	object	No	Note This parameter is not publicly available.
RoleType	string	No	Note This parameter is not publicly available.	null
Rolearn	string	No	Note This parameter is not publicly available.	null
AssumeRoleFor	string	No	Note This parameter is not publicly available.	null

Response elements

Element	Type	Description	Example
	object	Schema of Response
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****
TaskGroupId	string	The task group ID of the disk cloning operation. You can call DescribeTasks to query the task execution result.	g-2ze2op2grqpclwu7****

Examples

Success response

JSON format

{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "TaskGroupId": "g-2ze2op2grqpclwu7****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidDiskCategory.SourceDiskCategoryNotSupport	The specified target disk category %s is not support clone from origin disk category %s.
400	InvalidDisk.NeverAttached	The specified disk %s has been never attached to any instance.
400	InvalidStatus.SourceDiskStatusViolation	The specified disk %s status error, want Available or In_use, but %s.
400	InvalidDiskCategory.ValueNotSupported	The specified parameter "DiskCategory" is not valid.	The specified cloud disk type DiskCategory is invalid.
400	InvalidDiskName.ValueNotSupported	The specified parameter "DiskName" is not valid.
400	InvalidPerformanceLevel.ValueNotSupported	The specified parameter "PerformanceLevel" is not valid.
400	InvalidMultiAttach.ValueNotSupported	The specified parameter "MultiAttach" is not valid.
400	InvalidBurstingEnabled.DiskCategoryNotSupported	The specified disk category does not support bursting enabled.
400	InvalidProvisionedIops.DiskCategoryNotSupported	The specified disk category does not support provisioned IOPS.
400	InvalidProvisionedIops.LimitExceed	The provisioned IOPS exceeds the permitted range limit for the specified disk category
400	InvalidSize.MustGreaterThanSourceDisk	The specified size %s(GB) must greater than source disk size %s(GB).
400	DryRunOperation	Request validation has been passed with DryRun flag set.	Your request is determined as valid when the DryRun parameter is set.
400	InvalidSourceDisk.Lazyloading	The specified source disk %s is lazyloading.
400	InvalidOperation.DiskCloneExceedsConcurrencyLimit	The source disk %s has reached the maximum number (1) of concurrent clone operations. In-progress cloned disks: %s. Please wait a moment and try again later.
400	InvalidParameter.Arns	The specified Arns is not valid.	The Arns parameter is invalid. Please check and pass it again.
401	InvalidOperation.UserNotInWhiteList	The specified user %s is not in the CloneDisks whitelist.
404	InvalidRegionId.NotFound	The specified region does not exist.	The specified RegionId parameter does not exist. Check whether the service is available in the specified region.
404	InvalidSourceDiskId.NotFound	The specified source disk does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.