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. You can use this operation to deploy ECS instances across regions or replicate ECS instances across regions.

Operation description

You can use the copied image in the destination region to create ECS instances (RunInstances) or replace system disks of instances (ReplaceSystemDisk).

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

The custom image must be in the Available (Available) state.
If the image is a custom image under your account, you can copy it across regions. If the image is shared with you by another user, you can copy it only within the same region.
During the image copy process, you cannot directly delete (DeleteImage) the image being copied. However, you can cancel the copy task (CancelCopyImage) to delete the image being copied.
A maximum of five image copy tasks can run concurrently in the same region. Additional tasks are queued and run in sequence after any of the preceding tasks are completed.
You can use the ResourceGroupId parameter to specify the resource group to which the copied image belongs. If you do not set 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/*

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. The name must start with a letter and cannot start with `aliyun` or `acs:`. The name cannot contain `http://` or `https://`. The name 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 DescribeRegions to query the most recent region list.	cn-hangzhou
DestinationRegionId	string	No	The ID of the destination region to which the image is copied.	cn-shanghai
Encrypted	boolean	No	Specifies whether to encrypt the copied image. true: encrypts the copied image. false: does not encrypt the copied image. Not specified: determined by the backend. For more information, see the supplementary description below. Default value: not specified.	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 publicly available.	hide
ResourceGroupId	string	No	The resource group ID of the copied image. If you do not set this parameter, the copied image belongs to the default resource group. Note If you are a Resource Access Management (RAM) user and invoke this operation with the `ResourceGroupId` parameter left empty, take note of the following: if the RAM user does not have permissions on the default resource group, the error message `Forbidden: User not authorized to operate on the specified resource` is returned. Set the `ResourceGroupId` parameter to a resource group ID that the RAM user has permissions on, or grant the RAM user permissions on the default resource group by using the corresponding Alibaba Cloud account before you invoke this operation again. The `ResourceGroupId` parameter determines which resource group the replicated image belongs to.	rg-bp67acfmxazb4p****
Tag	array<object>	No	The tags.
	object	No	The tags.
Value	string	No	The tag value of the copied image. 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:`. The tag value cannot contain `http://` or `https://`.	TestValue
Key	string	No	The tag key of the copied image. 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 start with `aliyun` or `acs:`. The tag key cannot contain `http://` or `https://`.	TestKey
DryRun	boolean	No	Specifies whether to perform only a dry run. Valid values: true: performs only a dry run. The system checks whether your AccessKey pair is valid, whether Resource Access Management (RAM) user authorization is complete, and whether the required parameters are specified. If the request fails the dry run, an error message is returned. If the request passes the dry run, the error code `DryRunOperation` is returned. false: performs a dry run and sends the request. If the request passes the dry run, a 2XX HTTP status code is returned and the operation is Normal. 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 make sure that the token is unique among different requests. ClientToken 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 status	Encrypted parameter	KMSKeyId parameter	Whether account-level EBS default encryption is configured in the destination region	Destination image result	Description
1	Unencrypted image	False or not specified	Not specified	Not configured	Unencrypted image	No encryption is applied. The image remains unchanged.
2	Unencrypted image	True	Not specified	Any	Fully encrypted image	The user explicitly requests encryption. If account-level EBS default encryption is configured, the configured default key is secret key encryption. Otherwise, the service key is secret key encryption.
3	Unencrypted image	True	Specified	Any	Fully encrypted image	The user explicitly requests encryption. The specified KMSKeyId is secret key encryption.
4	Unencrypted image	Not specified	Not specified	Configured	Fully encrypted image	The key configured in account-level EBS default encryption is secret key encryption.
5	Encrypted image	Not specified	Not specified	Not configured	Encrypted image	The original format is preserved. Unencrypted snapshots remain unencrypted, and encrypted snapshots are encrypted with the service key.
6	Encrypted image	Not specified or True	Not specified	Configured	Fully encrypted image	The key configured in account-level EBS default 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 in account-level EBS default encryption is secret key encryption.
9	Encrypted image	True	Specified	Any	Fully encrypted image	The user explicitly requests encryption. The specified KMSKeyId 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 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.
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 original 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	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.
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	InvalidParameter.DataEncryptedKeyCreateFailed	Create kms data encrypted key fail. If you need further assistance, you can contact the KMS Technical Support.	Failed to create a data key using the KMS master key. Please contact the KMS attendant for further troubleshooting.
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 CMK (Customer Master Key) must be in an active state.	The CMK (Customer Master Key) must be in an active state.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The CMK(Customer Master Key) lacks authorization to add tags to the ECS service.	The CMK(Customer Master Key) lacks authorization to add tags to the ECS service.
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.	The specified KMSKeyId parameter does not exist.
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.	A conflicting task exists in the port list.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.