Create a snapshot of a cloud disk.
Operation description
The instant access feature for snapshots replaces the legacy local snapshot feature. The parameters are described as follows:
If you used local snapshots before December 14, 2020, you can continue to use the
Categoryparameter.If you did not use local snapshots before December 14, 2020, no additional configuration is required. New snapshots that are created for ESSD cloud disks (ESSDs, ESSD AutoPL disks, ESSD Entry disks, and zone-redundant ESSDs) have the instant access feature enabled by default. This applies to both manual and automatic snapshots. The instant access-related parameters
InstantAccess,InstantAccessRetentionDays, andDisableInstantAccessno longer take effect. TheDescribeSnapshotsandDescribeSnapshotGroupsAPI operations return anAvailableparameter that indicates the snapshot's status.
Prerequisites:
-
The snapshot feature is enabled. For more information, see Enable the snapshot feature.
-
The cloud disk must be in the in-use or available state. Note the following points:
If the cloud disk is in the in-use state, the instance to which the disk is attached must be in the running or stopped state.
If the cloud disk is in the available state, you can create snapshots for it only if it has been previously attached to an ECS instance.
When you use cloud disks to create dynamic scalable volumes or RAID arrays, we recommend that you use snapshot consistency groups and enable application-consistent snapshots to back up data. A snapshot consistency group ensures the crash consistency and write-order consistency of data written across multiple cloud disks. For more information, see Create a snapshot consistency group and Create an application-consistent snapshot.
Keep the following in mind when creating a snapshot:
-
Create snapshots during off-peak hours. During snapshot creation, the I/O performance of the cloud disk decreases by less than 10% and read and write operations may temporarily slow down.
-
You cannot use a snapshot that is being created to create a custom image (CreateImage).
-
The snapshot does not back up incremental data generated on the cloud disk during the creation process.
-
If the cloud disk is attached to an ECS instance, do not change the state of the instance, such as stopping or restarting the instance, during snapshot creation. Otherwise, the snapshot creation will fail.
-
You cannot resize a cloud disk during snapshot creation. You can resize the cloud disk only after the snapshot is complete.
-
You can create a snapshot for a cloud disk that is in the expired (
Expired) state. If the cloud disk is released due to expiration when the snapshot is being created, the snapshot in the creating (Creating) state is also deleted. -
After a snapshot is created, you are charged for the snapshot based on its size. The fees are settled on a per-region basis. For more information, see Snapshots.
-
You cannot create a snapshot for a cloud disk in the following cases:
-
The number of manual snapshots of the cloud disk has reached the upper limit. For more information, see Limits.
-
The limit on the number of snapshots that can be created concurrently has been reached. For more information, see Limits.
-
When you query the information of an ECS instance, if the returned data contains
{"OperationLocks": {"LockReason" : "security"}}, all operations on the instance 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. |
d-bp1s5fnvk4gn2tws0**** |
| SnapshotName |
string |
No |
The snapshot name must be 2 to 128 characters long. It must start with a letter or a Chinese character and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-). Note
The name cannot start with |
testSnapshotName |
| Description |
string |
No |
The snapshot description must be 2 to 256 characters in length and cannot start with This parameter is empty by default. |
testDescription |
| RetentionDays |
integer |
No |
The retention period of the snapshot, in days. Valid values: 1 to 65,536. The snapshot is automatically deleted when the retention period expires. If this parameter is not specified, the snapshot is retained indefinitely. |
30 |
| Category |
string |
No |
The type of the snapshot. Valid values:
Note
This parameter is deprecated. standard snapshots for ESSD cloud disks now include the Instant Access feature by default at no additional cost. |
Standard |
| ClientToken |
string |
No |
A client-generated token to ensure request idempotence. The token must be unique for each request. The ClientToken value must be an ASCII string of up to 64 characters. For more information, see How to 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 Instant Access feature. Valid values:
Default value: false. Note
This parameter is deprecated. standard snapshots for ESSD cloud disks now include the Instant Access feature by default at no additional cost. |
false |
| InstantAccessRetentionDays |
integer |
No |
The retention period for the Instant Access feature, in days. The snapshot is automatically deleted when this retention period expires. This parameter takes effect only when Defaults to the value of Note
This parameter is deprecated. standard snapshots for ESSD cloud disks now include the Instant Access feature by default at no additional cost. |
1 |
| Tag |
array<object> |
No |
The tags to add to the snapshot. You can add up to 20 tags. |
|
|
object |
No |
A tag consisting of a key-value pair. |
||
| key |
string |
No |
The key of the tag. Note
This parameter is not recommended. For better compatibility, use the Key parameter instead. |
null |
| Key |
string |
No |
The key of the tag. Note
This parameter is not recommended. For better compatibility, use the Key parameter instead. |
TestKey |
| Value |
string |
No |
The tag value. It can be an empty string, must be 128 characters or shorter, and cannot contain http:// or https://. |
TestValue |
| value |
string |
No |
The tag value. It can be an empty string, must be 128 characters or shorter, and cannot contain http:// or https://. |
null |
| StorageLocationArn |
string |
No |
Note
This parameter is not available for public use. |
null |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The response body for a successful request. |
||
| SnapshotId |
string |
The snapshot ID. |
s-bp17441ohwka0yuh**** |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
Examples
Success response
JSON format
{
"SnapshotId": "s-bp17441ohwka0yuh****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | |
| 400 | InvalidSnapshotName.Malformed | The specified SnapshotName is wrongly formed. | The format of the specified snapshot name is invalid. |
| 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 Tag.N.Key contain duplicate key. | The specified tag key already exists. Tag keys must be unique. |
| 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. |
| 500 | InternalError | The request processing has failed due to some unknown error. | |
| 403 | Throttling | Request was denied due to user flow control. | |
| 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 | Snapshot service has not been opened yet. | The operation is not supported while the snapshot service is not activated. |
| 403 | IncorrectInstanceStatus | The current status of the resource does not support this operation. | |
| 403 | IncorrectVolumeStatus | The current volume status 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 invalid, restart instance and try again. | The state of the specified disk 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. | The specified disk is being migrated. Wait until the migration is complete and try again. |
| 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 have no right to access your KMS. | ECS is not authorized to access your KMS resources. |
| 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. | The quota is insufficient. Contact your channel partner to request a quota increase. |
| 403 | InvalidInstantAccessRetentionDays.Malformed | The specified InstantAccessRetentionDays is not valid. | |
| 403 | CloudBoxNotSupportSnapshotWithInstantAccess | The specified disk in CloudBox does not support to create a snapshot with InstantAccess. | |
| 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 wrongly formed. | The format of the specified parameter StorageLocationArn is incorrect. |
| 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. |
| 404 | InvalidDiskId.NotFound | The specified DiskId does not exist. | The specified disk does not exist. Check whether the disk ID is correct. |
| 404 | InvalidDescription.Malformed | The specified description is wrongly formed. | |
| 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.