Copies a custom image from one region to another. You can deploy or copy Elastic Compute Service (ECS) instances across regions by copying custom images.
Operation description
After you copy a custom image (source image) to the destination region, you can use the image copy to create ECS instances by calling the RunInstances operation or replace the system disks of the ECS instances by calling the ReplaceSystemDisk operation in the destination region.
When you call this operation, take note of the following items:
- You can copy only custom images that are in the
Available
state. - Custom images that you want to copy must belong to your Alibaba Cloud account or be shared to you by others, and cannot be copied across accounts.
- When an image is being copied, the image copy cannot be deleted by calling the DeleteImage operation. However, you can cancel the copying task that is running by calling the CancelCopyImage operation.
- A region can have only one image copying task running at a time. Other image copying tasks queue up for the current task to complete before the tasks can run in sequence.
- You can configure the
ResourceGroupId
parameter to specify the resource group to which the image copy belongs. If you do not configure theResourceGroupId
parameter, the image copy belongs to the default resource group.
Debugging
Authorization information
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
DestinationImageName | string | No | The name of the image copy. The name must be 2 to 128 characters in length. The name must start with a letter and cannot start with | YourImageName |
DestinationDescription | string | No | The description of the image copy. The description must be 2 to 256 characters in length and cannot start with | This is a description example. |
ImageId | string | Yes | The ID of the source custom image. | m-bp1h46wfpjsjastc**** |
RegionId | string | Yes | The region ID of the source custom image. You can call the DescribeRegions operation to query the most recent region list. | cn-hangzhou |
DestinationRegionId | string | No | The ID of the destination region to which the source custom image is copied. | cn-shanghai |
Encrypted | boolean | No | Specifies whether to encrypt the image copy. Default value: false. | false |
KMSKeyId | string | No | The ID of the key used to encrypt the image copy. | e522b26d-abf6-4e0d-b5da-04b7******3c |
EncryptAlgorithm | string | No | Note
This parameter is unavailable.
| hide |
ResourceGroupId | string | No | The ID of the resource group to which the image copy belongs. If you do not specify this parameter, the image copy belongs to the default resource group. Note
If you call the CopyImage operation as a Resource Access Management (RAM) user who is not authorized to manage the default resource group and do not specify the ResourceGroupId parameter, the Forbidden: User not authorized to operate on the specified resource error message is returned. You must specify the ID of a resource group that the RAM user is authorized to manage or authorize the RAM user to manage the default resource group before you call the CreateImage operation again.
| rg-bp67acfmxazb4p**** |
Tag | object [] | No | The list of tags. | |
Key | string | No | The key of tag N of the image copy. 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 contain | TestKey |
Value | string | No | The value of tag N of the image copy. 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 start with | TestValue |
Response parameters
Examples
Sample success responses
JSON
format
{
"ImageId": "m-bp1h46wfpjsjastd****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}
Error codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | InvalidImageName.Malformed | The specified Image name is wrongly formed. | The specified image name is invalid. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with acs: or aliyun. It can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-). It cannot contain http:// or https://. |
400 | InvalidImageName.Malformed | The specified destination Image name is wrongly formed. | The specified image name is invalid. For more information, see the description of the DestinationImageName parameter. |
400 | InvalidDescription.Malformed | The specified destination description is wrongly formed. | The resource description is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://. |
400 | InvalidDescription.Malformed | The specified description is wrongly formed. | The resource description is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://. |
400 | SourceRegion.NotFound | The source region not found. | The specified source region does not exist. |
400 | DestinationRegion.NotFound | The destination region not found. | The destination region was not found. |
400 | IncorrectImageStatus | The image not available. | The specified image is unavailable. |
400 | InvalidSnapshotId.NotFound | The specified SnapshotId does not exist. | The specified snapshot ID does not exist. |
400 | InvalidImageName.Duplicated | The destination image is exist. | The specified image name already exists. |
400 | InvalidParameter.EncryptedIllegal | The specified parameter Encrypted must be true when kmsKeyId is not empty. | The encryption feature is not enabled after a Key Management Service (KMS) key ID is specified. |
400 | InvalidEncrypted.NotMatchEncryptAlgorithm | The specified parameter Encrypted must be true when EncryptAlgorithm is not empty. | - |
400 | InvalidEncryptAlgorithm | The specified parameter EncryptAlgorithm is not valid. | - |
400 | InvalidEncrypted.NotMatchKmsKeyId | The specified parameter Encrypted must be true when KmsKeyId is not empty. | - |
400 | OperationDenied.CommunityImage | Community image does not support copy. | Community image does not support copy. |
401 | InvalidAliUid.IsNull | The aliUid must not be null. | - |
403 | Forbbiden | User not authorized to operate on the specified resource. | You are not authorized to operate the specified resource. |
403 | QuotaExceed.Image | The Image Quota exceeds. | The custom image quota has been used up. |
403 | QuotaExceed.Snapshot | The snapshot quota exceeds. | The maximum number of snapshots has been reached. Delete snapshots that are no longer needed and try again. |
403 | OperationDenied.ImageCopying | The Image are coping. | The image is being copied. Try again later. |
403 | RegionNotSupportCopy | The region not support copy. | The specified source region or destination region does not support image copying. |
403 | InvalidSnapshot.TooOld | This operation is denied because the specified snapshot is created before 2013-07-15. | The operation is denied because the specified snapshot was created before July 15, 2013. |
403 | OperationDenied | The specified snapshot is not allowed to create image. | The specified snapshot cannot be used to create images. |
403 | IncorrectDestinationRegion | The destination region is not equal the target region. | The source region must be different from the destination region when you copy an image across regions. |
403 | SizeExceed.Image | The image exceeds the maximum size. Please open a ticket to add the account to the white list. | - |
403 | OperationDeined.EncryptedSnapshot | The image contains encrypted snapshots, which do not support copying. | The specified image contains encrypted snapshots and cannot be copied. |
403 | InternalError | The request processing has failed due to some unknown error. | An internal error has occurred. Try again later. |
403 | OperationDenied.SameRegionOnly | The image shared from others can not be copied to another region directly. | You cannot copy images shared by other Alibaba Cloud accounts to another region. |
403 | OperationDenied.NotPublished | The operation is denied because corresponding marketplace image is not published in destination region. | - |
403 | OperationDenied.NotAuthorized | The operation is denied because corresponding marketplace image is not authorized to current user. | - |
403 | OperationDeined.EncryptedSnapshot | The image contains encrypted snapshots, which do not support copying to non-encrypted ones. | The image contains encrypted snapshots and cannot be copied to non-encrypted snapshots. |
403 | OperationDenied.EncryptSnapshotAcrossRegion | The image do not contain encrypted snapshots, which do not support copying to encrypted ones. | - |
403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | The customer master key (CMK) is not enabled when KMSKeyId is specified for an encrypted disk. You can call the DescribeKey operation of KMS to query information about the specified CMK. |
403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service have no right to access your KMS. | ECS is not authorized to access your KMS resources. |
403 | InvalidRegion.NotSupport | The specified region does not support byok. | The bring your own key (BYOK) feature is not supported in the region. |
403 | UserNotInTheWhiteList | The user is not in byok white list. | You are not authorized to use the bring your own key (BYOK) feature. Try again when you are authorized. |
403 | InvalidRegionId.NotSupportEncryptAlgorithm | The current region does not support creating encrypted disks with EncryptAlgorithm. | - |
403 | OperationDenied.KmsServiceUnauthorized | The account is not authorized to kms service, please authorize it. | You are not authorized to access KMS. Apply for the permissions required to access KMS. |
404 | InvalidImageId.NotFound | The specified ImageId does not exist. | The specified image does not exist in this account. Check whether the image ID is correct. |
404 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | The specified KMSKeyId parameter does not exist. |
500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | An internal error has occurred. Try again later. |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2023-12-18 | The Error code has changed | see changesets | ||||||||||||
| ||||||||||||||
2023-10-09 | The Error code has changed | see changesets | ||||||||||||
| ||||||||||||||
2023-08-23 | The Error code has changed | see changesets | ||||||||||||
| ||||||||||||||
2023-07-12 | The Error code has changed | see changesets | ||||||||||||
| ||||||||||||||
2023-03-03 | The Error code has changed | see changesets | ||||||||||||
|