Copies a custom image from one region to another. You can deploy or copy instances across regions by copying images.
Description
After you copy a custom image to the destination region, you can use the image copy to create Elastic Compute Service (ECS) instances by calling the RunInstances operation or replace the system disks of instances by calling the ReplaceSystemDisk operation in the destination region.
When you call this operation, take note of the following items:
- Only custom images that are in the
Available
state can be copied. - You can only copy images within your own Alibaba Cloud account. Images cannot be copied from one account to another.
- When an image is being copied, you cannot delete the image copy by calling the DeleteImage operation, but you can cancel the running copy task by calling the CancelCopyImage operation.
- A single region can have only one image copy task running at a time. Other image copy tasks queue up for the current task to complete before they run in sequence.
- You can set the
ResourceGroupId
parameter to specify the resource group to which the image copy belongs. If you do not set theResourceGroupId
parameter, the image copy belongs to the default resource group.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | CopyImage |
The operation that you want to perform. Set the value to CopyImage. |
DestinationImageName | String | No | YourImageName |
The name of the image copy. The name must be 2 to 128 characters in length. It must
start with a letter and cannot start with |
DestinationDescription | String | No | This is a description example. |
The description of the image copy. The description must be 2 to 256 characters in
length and cannot start with |
ImageId | String | Yes | m-bp1h46wfpjsjastc**** |
The ID of the source custom image. |
RegionId | String | Yes | cn-hangzhou |
The region ID of the source custom image. You can call the DescribeRegions operation to query the most recent region list. |
DestinationRegionId | String | No | cn-shanghai |
The ID of the destination region to which to copy the source custom image. |
Encrypted | Boolean | No | false |
Specifies whether to encrypt the image copy. Default value: false. |
KMSKeyId | String | No | e522b26d-abf6-4e0d-b5da-04b7******3c |
The ID of the key used to encrypt the image copy. |
ResourceGroupId | String | No | rg-bp67acfmxazb4p**** |
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 use a RAM user that is not authorized to manage the default resource group
to call the CopyImage operation and do not specify the
ResourceGroupId parameter, the Forbbiden: 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 CopyImage operation again.
|
Tag.N.Key | String | No | TestKey |
The key of tag N of the image copy. Valid values of N: 1 to 20. The tag key cannot
be an empty string. It can be up to 128 characters in length and cannot start with
|
Tag.N.Value | String | No | TestValue |
The value of tag N of the image copy. Valid values of N: 1 to 20. The tag value can
be an empty string. It can be up to 128 characters in length and cannot start with
|
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
ImageId | String | m-bp1h46wfpjsjastd**** |
The ID of the image copy. |
RequestId | String | 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
The ID of the request. |
Examples
Sample requests
https://ecs.aliyuncs.com/?Action=CopyImage
&ImageId=m-bp1h46wfpjsjastc****
&RegionId=cn-hangzhou
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<CopyImageResponse>
<RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
<ImageId>m-bp1h46wfpjsjastd****</ImageId>
</CopyImageResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "C8B26B44-0189-443E-9816-D951F59623A9",
"ImageId" : "m-bp1h46wfpjsjastd****"
}
Error codes
HttpCode | Error code | Error message | Description |
---|---|---|---|
400 | InvalidImageName.Malformed | The specified Image name is wrongly formed. | The error message returned because 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 cannot contain http:// or https://. It can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-). |
400 | InvalidImageName.Malformed | The specified destination Image name is wrongly formed. | The error message returned because the specified destination 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 error message returned because the specified 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 error message returned because the specified 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 error message returned because the specified source region does not exist. |
400 | DestinationRegion.NotFound | The destination region not found | The error message returned because the specified destination region does not exist. |
400 | IncorrectImageStatus | The image not available. | The error message returned because the specified image is unavailable. |
400 | InvalidSnapshotId.NotFound | The specified SnapshotId does not exist. | The error message returned because the specified snapshot does not exist. |
400 | InvalidImageName.Duplicated | The destination image is exist. | The error message returned because the specified image name already exists. |
400 | InvalidParameter.EncryptedIllegal | The specified parameter Encrypted must be true when kmsKeyId is not empty. | The error message returned because the encryption feature is not enabled after a Key Management Service (KMS) key ID is specified. |
401 | InvalidAliUid.IsNull | The aliUid must not be null | The error message returned because the required aliUid parameter is not specified. |
500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket. |
403 | Forbbiden | User not authorized to operate on the specified resource. | The error message returned because you are not authorized to perform operations on the specified resource. |
403 | QuotaExceed.Image | The Image Quota exceeds. | The error message returned because the custom image quota has been used up. |
403 | QuotaExceed.Snapshot | The snapshot quota exceeds. | The error message returned because the maximum number of snapshots has been reached. To store new snapshots, delete snapshots that are no longer needed. |
403 | OperationDenied.ImageCopying | The Image are coping. | The error message returned because the source image is being copied. Try again later. |
403 | RegionNotSupportCopy | The region not support copy. | The error message returned because the specified source 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 error message returned because the operation is rejected when the specified snapshot was created before July 15, 2013. |
403 | OperationDenied | The specified snapshot is not allowed to create image. | The error message returned because the specified snapshot cannot be used to create images. |
403 | IncorrectDestinationRegion | The destination region is not equal the target region. | The error message returned because the source region is the same as the destination region. |
403 | SizeExceed.Image | The image exceeds the maximum size. Please open a ticket to add the account to the white list. | The error message returned because the size of the image exceeds the upper limit. |
403 | OperationDeined.EncryptedSnapshot | The image contains encrypted snapshots, which do not support copying. | The error message returned because the specified image contains encrypted snapshots and cannot be copied. |
403 | InternalError | The request processing has failed due to some unknown error. | The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket. |
403 | OperationDenied.SameRegionOnly | The image shared from others can not be copied to another region directly. | The error message returned because 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. | The error message returned because the image type is not supported in the destination region and the operation is rejected. |
403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | The error message returned because the customer master key (CMK) is not enabled when a KMS key ID is specified for a 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. | The error message returned because ECS is not authorized to access KMS resources. |
403 | InvalidRegion.NotSupport | The specified region does not support byok. | The error message returned because the bring your own key (BYOK) feature is not supported in the region. |
403 | UserNotInTheWhiteList | The user is not in byok white list. | The error message returned because you are not in the BYOK whitelist. Try again when you are in the whitelist. |
404 | InvalidImageId.NotFound | The specified ImageId does not exist. | The error message returned because the specified image does not exist within this account. Check whether the image ID is correct. |
404 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | The error message returned because the specified KMSKeyId parameter does not exist. |
For a list of error codes, visit the API Error Center.