Creates a snapshot for a disk.
Operation description
The local snapshot feature has been replaced by the snapshot instant access feature. The metric descriptions are as follows:
If you used local snapshots before December 14, 2020, you can continue to use the
Categoryparameter as Normal.If you did not use local snapshots before December 14, 2020, no additional configuration is required. Snapshots created for ESSD-series disks (ESSD, ESSD AutoPL, ESSD Entry, and regional ESSD) are instantly active by default and support both manual snapshots and automatic snapshots. The InstantAccess, InstantAccessRetentionDays, and DisableInstantAccess parameters related to the snapshot instant access feature are no longer effective. The DescribeSnapshots and DescribeSnapshotGroups API operations will include a new response element Available to indicate the active status of a snapshot.
Before you begin:
-
Activate the snapshot feature. For more information, see Activate the snapshot feature.
-
The disk must be in the In Use or Unattached state. The following precautions apply to each state:
If the disk is in the In Use state, the instance must be in the Running or Stopped state.
If the disk is in the Unattached state, the disk must have been previously attached to an ECS instance. Snapshots cannot be created for disks that have never been attached to an ECS instance.
If the disk is used to create a dynamic volume or a RAID array, use a snapshot-consistent group and enable application-consistent snapshots to back up data. A snapshot-consistent group ensures write-order consistency across multiple disks in a business system and guarantees crash consistency. For more information, see Create a snapshot-consistent group and Create an application-consistent snapshot.
When creating a snapshot, note the following:
-
Avoid creating snapshots during peak business hours. Creating a snapshot reduces disk I/O performance by less than 10% and may cause a brief slowdown in read and write performance.
-
If a snapshot is not yet complete, it cannot be used to create a custom image (CreateImage).
-
Incremental data generated by disk operations during snapshot creation is not included in the backup of the snapshot.
-
If the disk is attached to an ECS instance, do not change the instance status (such as stopping or restarting the ECS instance) during snapshot creation. Otherwise, the snapshot creation will be failed.
-
A disk for which a snapshot is being created cannot be scaled out. Wait until the snapshot is complete before you execute the scale-out operation.
-
You can create a snapshot for a disk in the Expired (
Expired) state. If the disk reaches its expiration time while a snapshot is being created, the disk is released and the snapshot in the Creating (Creating) state is deleted at the same time. -
After a snapshot is created, fees are charged separately for each region based on the snapshot size. For more information, see Snapshot billing.
-
You cannot create a snapshot for a specified disk in the following scenarios:
-
The number of manual snapshots retained for the disk has reached the upper limit. For more information, see Snapshot limits.
-
Snapshot creation is subject to concurrency limits. Exceeding the limit causes the creation to fail. For more information, see Snapshot limits.
-
When querying ECS instance information, if the returned data 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 disk ID. |
d-bp1s5fnvk4gn2tws0**** |
| SnapshotName |
string |
No |
The snapshot name. The name must be 2 to 128 characters in length, must start with an uppercase or lowercase letter or a Chinese character, and can contain Unicode characters in the letter category (including English and Chinese characters) and ASCII digits (0–9). The name can contain colons (:), underscores (_), periods (.), or hyphens (-). Note
The name cannot start with http:// or https://. To avoid conflicts with automatic snapshot names, the name cannot start with |
testSnapshotName |
| Description |
string |
No |
The snapshot description. 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, in days. Valid values: 1 to 65536. The snapshot undergoes automatic release when the retention period expires. Default value: empty, which indicates that the snapshot does not undergo automatic release. |
30 |
| Category |
string |
No |
The snapshot type. Valid values:
Note
This parameter is being deprecated. Standard snapshots for ESSD disks have been upgraded to instant access by default. No additional configuration is required and no additional fees are incurred. |
Standard |
| ClientToken |
string |
No |
The client token that is used to ensure the idempotency of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotency. |
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 ESSD disks have been upgraded to instant access by default. No additional configuration is required and no additional fees are incurred. |
false |
| InstantAccessRetentionDays |
integer |
No |
Settings for the retention period of the snapshot instant access feature. The snapshot undergoes automatic release when the retention period expires. This parameter takes effect only when Default value: the same as the value of the Note
This parameter is deprecated. Standard snapshots for ESSD disks have been upgraded to instant access by default. No additional configuration is required and no additional fees are incurred. |
1 |
| Tag |
array<object> |
No |
The list of tags. |
|
|
object |
No |
The list of tags. |
||
| Key |
string |
No |
The tag key of the snapshot. 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:, and cannot contain http:// or https://. |
TestKey |
| Value |
string |
No |
The tag value of the snapshot. 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 |
| key |
string |
No |
The tag key of the snapshot. Note
For better compatibility, use the Tag.N.Key parameter instead. |
null |
| value |
string |
No |
The tag value of the snapshot. Note
For better compatibility, use the Tag.N.Value parameter instead. |
null |
| StorageLocationArn |
string |
No |
Note
This parameter is not available for use. |
null |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
| SnapshotId |
string |
The snapshot ID. |
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 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. |
| 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 | 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. | The current 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 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 specified InstantAccessRetentionDays parameter format 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. | |
| 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 malformed. | |
| 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.