All Products
Search
Document Center

Elastic Compute Service:CopyImage

Last Updated:Sep 27, 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

Usage notes

After you copy a custom image to the destination region, you can use the image copy (new image) to create ECS instances by calling the RunInstances operation or replace the system disks of instances by calling the ReplaceSystemDisk operation in the destination region.

Take note of the following items:

  • Only custom images that are in the Available state can be copied.
  • 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 ongoing image copy task by calling the CancelCopyImage operation.
  • A region supports only up to five concurrent image copy tasks. Excess image copy tasks are queued for execution.
  • You can configure ResourceGroupId to specify the resource group to which to assign the new image. If you do not configure ResourceGroupId, the new image is assigned 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

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:CopyImageupdate
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
DestinationImageNamestringNo

The name of the new image. The name must be 2 to 128 characters in length. The name must start with a letter and cannot contain http:// or https://. The name cannot start with acs: or aliyun. 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 new image.

  • true
  • false

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 to assign the new image. If you do not specify this parameter, the new image is assigned to the default resource group.

Note If you call the CopyImage operation as a Resource Access Management (RAM) user who does not have the permissions to manage the default resource group and do not specify ResourceGroupId, 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 has the permissions to manage or grant the RAM user the permissions to manage the default resource group before you call the CopyImage operation again.
rg-bp67acfmxazb4p****
Tagarray<object>No

The list of tags.

objectNo

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
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://.
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.
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.
400InvalidParameter.KmsNotEnabledThe specified operation need enable KMS.The current operation requires opening KMS
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.
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.
403OperationDenied.NonCompliantDestinationRegionThe copy operation to the destination region is not in compliance with regulations.The target region does not meet the security compliance requirements.
403InvalidEncrypted.NotMatchDiskDefaultEncryptionThe specified parameter Encrypted not match for your account default encryption settings.The encryption parameter does not match the default encryption configuration for the cloud disk of the current account.
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.
404InvalidResourceGroup.NotFoundThe ResourceGroup provided does not exist in our records.The specified resource group 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
2024-09-05The Error code has changedView Change Details
2024-06-27The Error code has changedView Change Details
2023-12-18The Error code has changedView Change Details
2023-10-09The Error code has changedView Change Details
2023-08-23The Error code has changedView Change Details
2023-07-12The Error code has changedView Change Details
2023-03-03The Error code has changedView Change Details