All Products
Search
Document Center

Elastic Compute Service:CopyImage

Last Updated:Mar 26, 2024

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 the ResourceGroupId parameter, the image copy belongs to the default resource group.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
DestinationImageNamestringNo

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 acs: or aliyun. The name cannot contain http:// or https://. The name can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-).

YourImageName
DestinationDescriptionstringNo

The description of the image copy. The description must be 2 to 256 characters in length and cannot start with http:// or https://.

This is a description example.
ImageIdstringYes

The ID of the source custom image.

m-bp1h46wfpjsjastc****
RegionIdstringYes

The region ID of the source custom image. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
DestinationRegionIdstringNo

The ID of the destination region to which the source custom image is copied.

cn-shanghai
EncryptedbooleanNo

Specifies whether to encrypt the image copy.

Default value: false.

false
KMSKeyIdstringNo

The ID of the key used to encrypt the image copy.

e522b26d-abf6-4e0d-b5da-04b7******3c
EncryptAlgorithmstringNo
Note This parameter is unavailable.
hide
ResourceGroupIdstringNo

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****
Tagobject []No

The list of tags.

KeystringNo

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 http:// or https://. The tag key cannot start with aliyun or acs:.

TestKey
ValuestringNo

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 acs:. It cannot contain http:// or https://.

TestValue

Response parameters

ParameterTypeDescriptionExample
object
ImageIdstring

The ID of the image copy.

m-bp1h46wfpjsjastd****
RequestIdstring

The request ID.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

Examples

Sample success responses

JSONformat

{
  "ImageId": "m-bp1h46wfpjsjastd****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidImageName.MalformedThe 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://.
400InvalidImageName.MalformedThe specified destination Image name is wrongly formed.The specified image name is invalid. For more information, see the description of the DestinationImageName parameter.
400InvalidDescription.MalformedThe 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://.
400InvalidDescription.MalformedThe 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://.
400SourceRegion.NotFoundThe source region not found.The specified source region does not exist.
400DestinationRegion.NotFoundThe destination region not found.The destination region was not found.
400IncorrectImageStatusThe image not available.The specified image is unavailable.
400InvalidSnapshotId.NotFoundThe specified SnapshotId does not exist.The specified snapshot ID does not exist.
400InvalidImageName.DuplicatedThe destination image is exist.The specified image name already exists.
400InvalidParameter.EncryptedIllegalThe 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.
400InvalidEncrypted.NotMatchEncryptAlgorithmThe specified parameter Encrypted must be true when EncryptAlgorithm is not empty.-
400InvalidEncryptAlgorithmThe specified parameter EncryptAlgorithm is not valid.-
400InvalidEncrypted.NotMatchKmsKeyIdThe specified parameter Encrypted must be true when KmsKeyId is not empty.-
400OperationDenied.CommunityImageCommunity image does not support copy.Community image does not support copy.
401InvalidAliUid.IsNullThe aliUid must not be null.-
403ForbbidenUser not authorized to operate on the specified resource.You are not authorized to operate the specified resource.
403QuotaExceed.ImageThe Image Quota exceeds.The custom image quota has been used up.
403QuotaExceed.SnapshotThe snapshot quota exceeds.The maximum number of snapshots has been reached. Delete snapshots that are no longer needed and try again.
403OperationDenied.ImageCopyingThe Image are coping.The image is being copied. Try again later.
403RegionNotSupportCopyThe region not support copy.The specified source region or destination region does not support image copying.
403InvalidSnapshot.TooOldThis 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.
403OperationDeniedThe specified snapshot is not allowed to create image.The specified snapshot cannot be used to create images.
403IncorrectDestinationRegionThe 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.
403SizeExceed.ImageThe image exceeds the maximum size. Please open a ticket to add the account to the white list.-
403OperationDeined.EncryptedSnapshotThe image contains encrypted snapshots, which do not support copying.The specified image contains encrypted snapshots and cannot be copied.
403InternalErrorThe request processing has failed due to some unknown error.An internal error has occurred. Try again later.
403OperationDenied.SameRegionOnlyThe 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.
403OperationDenied.NotPublishedThe operation is denied because corresponding marketplace image is not published in destination region.-
403OperationDenied.NotAuthorizedThe operation is denied because corresponding marketplace image is not authorized to current user.-
403OperationDeined.EncryptedSnapshotThe 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.
403OperationDenied.EncryptSnapshotAcrossRegionThe image do not contain encrypted snapshots, which do not support copying to encrypted ones.-
403InvalidParameter.KMSKeyId.CMKNotEnabledThe 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.
403InvalidParameter.KMSKeyId.KMSUnauthorizedECS service have no right to access your KMS.ECS is not authorized to access your KMS resources.
403InvalidRegion.NotSupportThe specified region does not support byok.The bring your own key (BYOK) feature is not supported in the region.
403UserNotInTheWhiteListThe 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.
403InvalidRegionId.NotSupportEncryptAlgorithmThe current region does not support creating encrypted disks with EncryptAlgorithm.-
403OperationDenied.KmsServiceUnauthorizedThe 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.
404InvalidImageId.NotFoundThe specified ImageId does not exist.The specified image does not exist in this account. Check whether the image ID is correct.
404InvalidParameter.KMSKeyId.NotFoundThe specified KMSKeyId does not exist.The specified KMSKeyId parameter does not exist.
500InternalErrorThe 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 timeSummary of changesOperation
2023-12-18The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 403 change
    delete Error Codes: 400
    delete Error Codes: 401
    delete Error Codes: 404
    delete Error Codes: 500
2023-10-09The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    delete Error Codes: 401
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
2023-08-23The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 404 change
    delete Error Codes: 400
    delete Error Codes: 401
    delete Error Codes: 403
    delete Error Codes: 500
2023-07-12The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    Error Codes 403 change
    delete Error Codes: 401
    delete Error Codes: 404
    delete Error Codes: 500
2023-03-03The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    Error Codes 401 change
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500