Creates a snapshot for a cloud disk.
Operation description
Local snapshots have been replaced by the snapshot instant access feature. The metric description is as follows:
If you used local snapshots before December 14, 2020, Normal use of the
Categoryparameter is allowed.If you did not use local snapshots before December 14, 2020, no additional configuration is required. Snapshots created for enterprise SSD series disks (enterprise SSD, ESSD AutoPL, ESSD Entry, and regional enterprise SSD) are active by default after creation, and both the manual snapshot and automatic snapshot features are supported. The
InstantAccess,InstantAccessRetentionDays, andDisableInstantAccessparameters related to the instant access feature no longer take effect in API operations. TheDescribeSnapshotsandDescribeSnapshotGroupsAPI operations add theAvailableresponse parameter to describe the active status of snapshots.
Before you begin:
-
The snapshot feature is activated. For more information, see Activate the snapshot feature.
-
The cloud disk must be in the In Use or Available state. Take note of the following items based on the disk state:
If the cloud disk is in the In Use state, the instance must be in the Running or Stopped state.
If the cloud disk is in the Available state, make sure that the cloud disk was previously attached to an ECS instance. You cannot create snapshots for cloud disks that have never been attached to an ECS instance.
When a cloud disk is used to create a dynamic extended volume or a RAID array, we recommend that you use a snapshot-consistent group and enable application-consistent snapshots to back up data. A snapshot-consistent group ensures the chronological consistency of data written to cloud disks and guarantees crash consistency in scenarios where a business system spans multiple cloud disks. For more information, see Create a snapshot-consistent group and Create an application-consistent snapshot.
When you create a snapshot, take note of the following items:
-
Avoid creating snapshots during peak business hours. When a snapshot is being created, the I/O performance of the disk decreases by less than 10%, and the read and write performance may experience brief instantaneous slowdowns.
-
If the snapshot creation is not complete, the snapshot cannot be used to create a custom image (CreateImage).
-
During snapshot creation, no backup of incremental data generated by operations on the disk is saved to the snapshot.
-
If the disk is attached to an ECS instance, do not change the instance status during snapshot creation, such as stopping or restarting the ECS instance. Otherwise, it results in a failed snapshot creation.
-
You cannot perform scale-out on a disk while a snapshot is being created for it. Wait until the snapshot is created before you execute scale-out operations.
-
You can create snapshots for cloud disks in the Expired (
Expired) state. If a cloud disk reaches its expiration and release time while a snapshot is being created, the snapshot in the Creating (Creating) state is deleted when the cloud disk is released. -
After a snapshot is created, the system bills you based on the snapshot size in each region. For more information, see Snapshot billing.
-
You cannot create snapshots for a specified cloud disk in the following scenarios:
-
The number of manual snapshots retained for the cloud disk reaches the upper limit. For more information, see Snapshot limits.
-
Snapshot creation has concurrency limits. Exceeding the limits causes the creation to fail. For more information, see Snapshot limits.
-
If the response to a query for ECS instance information contains
{"OperationLocks": {"LockReason" : "security"}}, all operations are prohibited.
-
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:CreateSnapshot |
create |
*Disk
*Snapshot
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| DiskId |
string |
Yes |
The ID of the cloud disk. You can call the DescribeDisks operation and filter by InstanceId to query the cloud disks attached to the instance. The cloud disk used to create a snapshot must be in the In Use or Available state. An available cloud disk must have been previously attached to an ECS instance. |
d-bp1s5fnvk4gn2tws0**** |
| SnapshotName |
string |
No |
The name of the snapshot. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and can contain Unicode letters (including English and Chinese characters) and ASCII digits (0-9). It can contain colons (:), underscores (_), periods (.), and hyphens (-). Note
It cannot start with http:// or https://. To prevent name conflicts with automatic snapshots, it cannot start with |
testSnapshotName |
| Description |
string |
No |
The description of the snapshot. The description must be 2 to 256 characters in length and cannot start with Default value: empty. |
testDescription |
| RetentionDays |
integer |
No |
Settings for the retention period of the snapshot. Unit: days. Valid values: 1 to 65536. The snapshot is subject to automatic release when the retention period expires. Default value: empty, which indicates that the snapshot is not subject to automatic release. |
30 |
| Category |
string |
No |
The snapshot type. Valid values:
Note
This parameter is about to be deprecated. Standard snapshots for enterprise SSD disks (excluding standard SSD) have been upgraded to active by default. No additional configuration is required, and no extra costs are incurred. |
Standard |
| ClientToken |
string |
No |
The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must make sure that the value is unique among different requests. The ClientToken parameter can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see Ensure idempotence. |
123e4567-e89b-12d3-a456-426655440000 |
| ResourceGroupId |
string |
No |
The ID of the resource group to which the snapshot belongs. |
rg-bp67acfmxazb4p**** |
| InstantAccess |
boolean |
No |
Specifies whether to enable the snapshot instant access feature. Valid values:
Default value: false. Note
This parameter is deprecated. Standard snapshots for enterprise SSD disks (excluding standard SSD) have been upgraded to active by default. No additional configuration is required, and no extra costs are incurred. |
false |
| InstantAccessRetentionDays |
integer |
No |
Settings for the retention period of the snapshot instant access feature. The snapshot is subject to automatic release when the retention period expires. This parameter takes effect only when Default value: the value of the Note
This parameter is deprecated. Standard snapshots for enterprise SSD disks (excluding standard SSD) have been upgraded to active by default. No additional configuration is required, and no extra costs are incurred. |
1 |
| Tag |
array<object> |
No |
The list of tags. |
|
|
object |
No |
The list of tags. |
||
| Key |
string |
No |
The key of tag N of the snapshot. Valid values of N: 1 to 20. If this parameter is specified, it cannot be an empty string. The tag key can be up to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://. |
TestKey |
| Value |
string |
No |
The value of tag N of the snapshot. Valid values of N: 1 to 20. If this parameter is specified, it can be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://. |
TestValue |
| key |
string |
No |
The key of the tag. Note
To improve compatibility, we recommend that you use the Tag.N.Key parameter. |
null |
| value |
string |
No |
The value of the tag. Note
To improve compatibility, we recommend that you use the Tag.N.Value parameter. |
null |
| StorageLocationArn |
string |
No |
Note
This parameter is not available. |
null |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
| SnapshotId |
string |
The ID of the snapshot. |
s-bp17441ohwka0yuh**** |
Examples
Success response
JSON format
{
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
"SnapshotId": "s-bp17441ohwka0yuh****"
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. Please verify that the key ID is correct and that the key resides in the current region. | |
| 400 | InvalidSnapshotName.Malformed | The specified SnapshotName is malformed. | |
| 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 | DiskCategory.OperationNotSupported | The type of the specified disk does not support creating a snapshot. | The operation is not supported by the current disk category. |
| 400 | Duplicate.TagKey | The parameter Tag.N.Key contains duplicate values. Please remove the duplicate tag keys and try again. | |
| 400 | InvalidTagKey.Malformed | The specified Tag.n.Key is not valid. | The specified Tag.N.Key parameter is invalid. |
| 400 | InvalidTagValue.Malformed | The specified Tag.n.Value is not valid. | The specified tag value is invalid. |
| 400 | InvalidRetentionDays.Malformed | The specified RetentionDays is not valid. | The specified RetentionDays parameter is invalid. |
| 400 | CreateSnapshot.Failed | The process of creating snapshot is failed. | Failed to create the snapshot. |
| 400 | InvalidOperation.StorageLocationMismatch | The specified storageLocation does not match the storage location of the last snapshot for the disk. Ensure the storageLocation is consistent with previous snapshots. | |
| 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 | Throttling | Request was denied due to user flow control. | The request is throttled. |
| 403 | IncorrectDiskStatus.CreatingSnapshot | A previous snapshot creation is in process. | |
| 403 | InstanceLockedForSecurity | The disk attached instance is locked due to security. | |
| 403 | IncorrectDiskStatus.NeverAttached | The specified disk has never been attached to any instance. | |
| 403 | QuotaExceed.Snapshot | The snapshot quota exceeds. | |
| 403 | IncorrectDiskStatus.NeverUsed | The specified disk has never been used after creating. | |
| 403 | CreateSnapshot.Failed | The process of creating snapshot is failed. | |
| 403 | DiskInArrears | The specified operation is denied as your disk has expired. | |
| 403 | DiskId.ValueNotSupported | The specified parameter diskid is not supported. | The specified EBS device category does not support the operation. |
| 403 | IncorrectDiskStatus | The current disk status does not support this operation. | |
| 403 | InvalidAccountStatus.NotEnoughBalance | Your account does not have enough balance. | |
| 403 | InvalidAccountStatus.SnapshotServiceUnavailable | The snapshot service has not been activated. Please activate it and try again. | |
| 403 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | |
| 403 | IncorrectVolumeStatus | The current volume status does not support this operation. | The current state does not support this operation. |
| 403 | IdempotentParameterMismatch | The specified clientToken is used. | The specified client token is already in use. |
| 403 | IncorrectDiskStatus.Invalid | The specified disk status is invalid. Restart the instance and try again. | |
| 403 | IncorrectDiskType.NotSupport | The specified device type is not supported. | The specified disk type does not support the operation. |
| 403 | IncorrectDiskStatus.Transferring | The specified device is transferring. You can retry after the process is finished. | |
| 403 | InvalidParameter.KMSKeyId.CMKUnauthorized | ECS tags must be added to the CMK. | ECS tags must be added to the CMK. |
| 403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | |
| 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 | IdempotentProcessing | The previous idempotent request(s) is still processing. | A previous idempotent request is being processed. Try again later. |
| 403 | InvalidSnapshotCategory.Malformed | The specified Category is not valid. | The specified Category parameter is invalid. |
| 403 | InvalidAction.Unauthorized | The specified action is not valid. | The specified operation is invalid. |
| 403 | InvalidRegion.NotSupportSnapshotInstantAccessRegion | The snapshot InstantAccess is not supported for this region. | |
| 403 | InvalidCategoryAndInstantAccess.Malformed | The snapshot Category and InstantAccess can't be used together. | |
| 403 | DISK_HAS_CREATING_SNAPSHOT | The operation cannot be performed while a snapshot is being created for the disk. | |
| 403 | HibernationConfigured.InstanceOperationForbidden | The 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. |
| 403 | QuotaExceed.SnapshotQuota | The quota is insufficient. Please contact your channel partner to increase the quota. | |
| 403 | InvalidInstantAccessRetentionDays.Malformed | The specified InstantAccessRetentionDays is not valid. | The format of the specified InstantAccessRetentionDays parameter is invalid. |
| 403 | CloudBoxNotSupportSnapshotWithInstantAccess | The specified disk in CloudBox does not support to create a snapshot with InstantAccess. | Disks in CloudBox do not support creating snapshots with the instant access feature. |
| 403 | InvalidOperation.UnfinishedEncryptedSnapshotCopy | This disk has unfinished encrypted copy snapshots in the target region. | The cloud disk has unfinished encrypted snapshot copy tasks. |
| 403 | QuotaExceed.ConcurrentSnapshotQuota | The number of snapshots being created for the disk %s has exceeded the concurrent quota (%s). Please wait for the previous snapshots to complete before trying again. | The number of snapshots being created for this disk has exceeded the concurrent quota. Please wait for the previous snapshots to complete before trying again. |
| 403 | InvalidClientToken.Malformed | The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length. | The specified clientToken is improperly formatted. It must contain only ASCII characters and must not exceed 64 characters in length. |
| 403 | InvalidParameter.UnauthorizedStorageLocationArn | The operation has failed due to lack of permission for the specified "StorageLocationArn". Please use a resource with appropriate permission for the operation. | The current operation failed because the specified StorageLocationArn has insufficient permissions. Contact the administrator of the resource to obtain the operation permissions. |
| 403 | InvalidStorageLocationArn.Malformed | The specified parameter StorageLocationArn is malformed. | |
| 403 | InvalidStatus.ResourceGroup | You cannot perform an operation on a resource group that is being created or deleted. | Operation not allowed while resource group is being created or deleted. |
| 403 | OperationDenied.QuotaExceed | The quota of tags on resource is beyond permitted range. | The maximum number of tags on resource is exceeded. |
| 403 | Forbidden.InDebt | The operation is not allowed because your account has an outstanding balance. Please settle the overdue payment and try again. | |
| 403 | InvalidOperation.RegionUnsupported | Creating snapshots is not supported in the specified region. Please use a region that supports the snapshot feature. | the specified region does not support snapshot creation. Use a region that supports the snapshot function. |
| 403 | OperationDenied.KMSKeyUnauthorized | The operation is denied due to missing KMS key authorization. Please check the KMS key permissions and ensure the key is properly authorized for this operation. | |
| 404 | InvalidDiskId.NotFound | The specified DiskId does not exist. Please verify the disk ID and the current region. | The specified DiskId does not exist. Verify the disk ID and current region. |
| 404 | InvalidDescription.Malformed | The specified parameter Description is not valid. Please ensure that the description is 2 to 256 characters long and does not start with "http://" or "https://" and try again. | The specified Description parameter is invalid. Please ensure that the description is between 2 and 256 characters long, uses either English or Chinese characters, and does not begin with "http://" or "https://", then try again. |
| 404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | The specified instanceId is invalid. |
| 404 | InvalidVolumeId.NotFound | The specified volume does not exist. | |
| 404 | InvalidResourceGroup.NotFound | The ResourceGroup provided does not exist in our records. | The specified resource group does not exist. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.