Copy a custom image across regions by calling CopyImage - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Copies a custom image from one region to another. Copying images enables cross-region deployment and replication of ECS instances.

Operation description

You can use the copied image to create an ECS instance by calling the RunInstances operation, or replace the system cloud disk of an instance by calling the ReplaceSystemDisk operation in the destination region.

When you call this operation, take note of the following items:

The custom image must be in the Available state.
If the image is a custom image under your account, you can copy it across regions. If the image is shared by another account, you can only copy it within the same region.
During the image copy process, you cannot directly delete the image that is being copied by calling the DeleteImage operation. However, you can delete the image by canceling the copy task by calling the CancelCopyImage operation.
A maximum of five image copy tasks can run concurrently in the same region. Other tasks must wait in queue until one of the running tasks is completed.
You can use the ResourceGroupId parameter to specify the resource group to which the copied image belongs. If you do not specify the ResourceGroupId parameter, the copied image belongs to the default resource group.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:CopyImage

update

*Image

acs:ecs:{#regionId}:{#accountId}:image/*

*Image

acs:ecs:{#regionId}:{#accountId}:image/{#ImageId}

None

Request parameters

Parameter	Type	Required	Description	Example
DestinationImageName	string	No	The name of the copied image. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character, and cannot start with aliyun or acs:. It cannot contain http:// or https://. It can contain digits, periods (.), colons (:), underscores (_), and hyphens (-).	YourImageName
DestinationDescription	string	No	The description of the copied image. The description must be 2 to 256 characters in length, and cannot start with http:// or https://.	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.	cn-shanghai
Encrypted	boolean	No	Specifies whether to encrypt the copied image. Valid values: true: Encrypts the image. false: Does not encrypt the image. Not specified: The encryption status depends on the backend logic. For more information, see the supplementary description below. Default value: none.	false
KMSKeyId	string	No	The ID of the key used to encrypt the image.	e522b26d-abf6-4e0d-b5da-04b7******3c
EncryptAlgorithm	string	No	Note This parameter is not available.	hide
ResourceGroupId	string	No	The resource group ID of the image after replication. If you do not specify this parameter, the image after replication belongs to the default resource group. Note If you invoke this operation as a Resource Access Management (RAM) user and leave ResourceGroupId empty, note that if the Resource Access Management (RAM) user does not have permissions on the default resource group, the operation returns the `Forbidden: User not authorized to operate on the specified resource` error. Update the Settings of ResourceGroupId to the ID of a resource group on which the Resource Access Management (RAM) user has permissions, or use the corresponding Alibaba Cloud account to grant the Resource Access Management (RAM) user permissions on the default resource group, and then invoke this operation again.	rg-bp67acfmxazb4p****
Tag	array<object>	No	The list of tags.
	object	No	The list of tags.
Key	string	No	The key of tag N of the copied image. Valid values of N: 1 to 20. If you specify this parameter, it cannot be an empty string. The tag key can be up to 128 characters in length. It cannot start with aliyun or acs:, and cannot contain http:// or https://.	TestKey
Value	string	No	The value of tag N of the copied image. Valid values of N: 1 to 20. If you specify this parameter, it can be an empty string. The tag value can be up to 128 characters in length. It cannot start with acs:, and cannot contain http:// or https://.	TestValue
DryRun	boolean	No	Specifies whether to only perform a dry run for this request. Valid values: true: performs a dry run. The system checks whether your AccessKey pair is valid, whether the Resource Access Management (RAM) user has authorization, and whether the required parameters are specified. If the request fails the dry run, the corresponding error message is returned. If the request passes the dry run, the DryRunOperation error code is returned. false: sends a Normal request. If the request passes the dry run, a 2XX HTTP status code is returned and the operation is performed. Default value: false.	false
ClientToken	string	No	The client token that is used to ensure the idempotence 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 ClientToken parameter can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-426655440000

Scenario	Source image state	Encrypted parameter	KMSKeyId parameter	Is account-level EBS encryption configured in the destination region	Destination image result	Result description
1	Unencrypted image	False or not specified	Not specified	Not configured	Unencrypted image	The image is not encrypted and remains unchanged.
2	Unencrypted image	True	Not specified	Any	Fully encrypted image	The user explicitly requests encryption. If account-level EBS encryption is configured, the configured default key is secret key encryption. Otherwise, the service key is used.
3	Unencrypted image	True	Specified	Any	Fully encrypted image	The user explicitly requests encryption. The KMSKeyId specified by the user is secret key encryption.
4	Unencrypted image	Not specified	Not specified	Configured	Fully encrypted image	The key configured for account-level EBS encryption is secret key encryption.
5	Encrypted image	Not specified	Not specified	Not configured	Encrypted image	The original format is retained. Unencrypted snapshots remain unencrypted, and encrypted snapshots are encrypted by using the service key.
6	Encrypted image	Not specified or True	Not specified	Configured	Fully encrypted image	The key configured for account-level EBS encryption is secret key encryption.
7	Encrypted image	True	Not specified	Not configured	Fully encrypted image	The service key is secret key encryption.
8	Encrypted image	True	Not specified	Configured	Fully encrypted image	The key configured for account-level EBS encryption is secret key encryption.
9	Encrypted image	True	Specified	Any	Fully encrypted image	The user explicitly requests encryption. The KMSKeyId specified by the user is secret key encryption.

Response elements

Element	Type	Description	Example
	object
ImageId	string	The ID of the copied image.	m-bp1h46wfpjsjastd****
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

Examples

Success response

JSON format

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

Error codes

HTTP status code	Error code	Error message	Description
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	SourceRegion.NotFound	The source region not found.
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 specified image name is already in use in the target region. Please try a different one.	The specified image name is already in use in the target region. Please try another one.
400	InvalidParameter.EncryptedIllegal	The Encrypted parameter must be set to true when KMSKeyId is specified. Please adjust the parameters and try again.
400	InvalidEncrypted.NotMatchEncryptAlgorithm	The Encrypted parameter must be set to true when EncryptAlgorithm is specified. Please adjust the parameters and try again.
400	InvalidEncryptAlgorithm	The specified EncryptAlgorithm is not valid. Ensure the value is a supported encryption algorithm such as AES-256.
400	InvalidEncrypted.NotMatchKmsKeyId	The Encrypted parameter must be set to true when KMSKeyId is specified. Please adjust the parameters and try again.
400	OperationDenied.CommunityImage	Community image does not support copy.	Community image does not support copy.
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	InvalidParameter.KmsNotEnabled	The specified operation need enable KMS.	The current operation requires opening KMS
400	OperationDenied.ImageCopyConflict	The same image cannot be copied concurrently. Please wait until the last copy is completed before performing the next operation.	The same image cannot be copied concurrently. Please wait until the last copy is completed before performing the next operation.
400	Account.Arrearage	Your account has an outstanding payment.	Your account has overdue payments.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The specified tag key already exists. Tag keys must be unique.
401	InvalidAliUid.IsNull	The aliUid must not be null.
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	An internal error has occurred. Try again later.
403	Forbbiden	User not authorized to operate on the specified resource.	You are not authorized to operate the specified resource.
403	InvalidOperation.CopyingDataFromThisRegionUnsupported	Data transfer from the current region to other regions is not supported.	Data transfer from the current region to other regions is not supported.
403	InvalidOperation.CopyingDataToThisRegionUnsupported	Only Some Regions %s can copy data to this region.	Only some regions %s can copy data to the current region.
403	QuotaExceed.Image	The number of images exceeds the limit (%s).	The number of images exceeds the limit.
403	QuotaExceed.Snapshot	The snapshot quota exceeds.
403	OperationDenied.ImageCopying	The image is currently being copied. Please try again later.	The image is being copied, please try again later.
403	RegionNotSupportCopy	The region not support copy.
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.
403	OperationDeined.EncryptedSnapshot	The image contains encrypted snapshots, which do not support copying.	The specified image contains encrypted snapshots and cannot be copied.
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.	The specified operation cannot be performed because the source image of the image is from Alibaba Cloud Marketplace and has not been published in the destination region.
403	OperationDenied.NotAuthorized	The operation is denied because corresponding marketplace image is not authorized to current user.
403	OperationDenied.EncryptSnapshotAcrossRegion	The image do not contain encrypted snapshots, which do not support copying to encrypted ones.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	The ECS service is not authorized to access your KMS key. Please grant the ECS service permission to use the key and try again.
403	InvalidRegion.NotSupport	The specified region does not support customer master keys. Please choose another region or use a default KMS key and try again.
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 parameter EncryptAlgorithm is not supported. Please remove EncryptAlgorithm and try again.
403	OperationDenied.KmsServiceUnauthorized	The ECS service is not authorized to access your KMS key. Please grant the ECS service permission to use the key and try again.
403	OperationDenied.NonCompliantDestinationRegion	The copy operation to the destination region is not in compliance with regulations.	The target region does not meet the security compliance requirements.
403	InvalidEncrypted.NotMatchDiskDefaultEncryption	The 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.
403	SizeExceed.Image	The image exceeds the maximum size. You can use the CopySnapshot API to copy your snapshots of the image and then create a new image from them.	The size of the mirror has exceeded the operational maximum. You can use the CopySnapshot API to copy the snapshot of this image to the target region, and then use the copied snapshot to create a new image.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The specified KMS key must be in an enabled state. Please enable the key in the KMS console and try again.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The specified KMS key is not authorized for the ECS service. Please grant the ECS service permission to use the key in the KMS console and try again.
403	InvalidOperation.VhdImageUnsupported	The specified vhd image is not supported for this operation. Please switch to a raw image and retry.	vhd format images do not support this operation. switch to raw format images and try again.
403	InvalidOperation.CloudBoxImageCopyUnsupported	Copying CloudBox images is not supported.	CloudBox images do not support replication.
403	OperationDenied.KMSKeyUnauthorized	The operation is denied due to missing KMS key authorization. Please check the KMS key permissions and ensure the key is properly authorized for this operation.
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. Please verify that the key ID is correct and that the key resides in the current region.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The specified resource group does not exist.
409	InvalidOperation.Conflict	Request was denied due to conflict with a previous request, please try again later.	This operation is not allowed due to task conflicts.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.