Call the CreateImage API to create a custom image - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Create a custom image. You can then use the image to create ECS instances (RunInstances) or replace the system disk of an instance (ReplaceSystemDisk).

Operation description

Usage notes

This operation is asynchronous. A successful request returns an image ID, but the image is not created immediately. You can call DescribeImage to query the image status. The image is ready for use when its status changes to Available. For more information, see Overview of custom images.
If the response to a query for ECS instance information contains {"OperationLocks": {"LockReason" : "security"}}, you cannot create a custom image from the instance.
We recommend configuring the image check parameter DetectionStrategy when you create an image. This helps the system optimize your image. For more information, see Overview of image check.

This operation provides three methods to create a custom image. The request parameters are prioritized as follows: InstanceId > DiskDeviceMapping > SnapshotId. If your request includes two or more of these parameters, the operation creates the image based on the parameter with the highest priority.

Create a custom image from an instance: Specify the instance ID (InstanceId).
- The instance must be in the Running or Stopped state.
- A successful call creates a new snapshot for each cloud disk of the instance.
Important Data cached in memory on a running instance may not be written to disk. This can cause data inconsistencies between the custom image and the instance. We recommend stopping the instance by calling StopInstances before creating an image.
Create a custom image from a snapshot (snapshots created on or before July 15, 2013, cannot be used).
- Create a custom image from a system disk snapshot: Specify only the snapshot ID of the instance's system disk (SnapshotId).
- Create a custom image from a system disk snapshot and data disk snapshots: Map the snapshots to disks by using the DiskDeviceMapping parameter.
  - You can specify only one system disk snapshot.
  - You can specify up to 16 data disk snapshots. If you do not specify DiskDeviceMapping.N.SnapshotId, the system creates an empty data disk with the default capacity.

Note

When you release an instance, the system retains its system disk and converts it to a pay-as-you-go data disk. You cannot use snapshots of this disk to create custom images. If you need a custom image, create it before you release the instance.

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:CreateImage

create

*Image

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

Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

Snapshot

acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The ID of the region where the image will be created. You can call the DescribeRegions operation to get the latest list of Alibaba Cloud regions.	cn-hangzhou
SnapshotId	string	No	The ID of the snapshot used to create the custom image. Note If you create a custom image from only a system disk snapshot, you can use either this parameter or the `DiskDeviceMapping.N.SnapshotId` parameter. If you want to include data disk snapshots, you must use the `DiskDeviceMapping.N.SnapshotId` parameter to specify the snapshots.	s-bp17441ohwkdca0****
InstanceId	string	No	The ID of the instance. This parameter is required when you create a custom image from an instance.	i-bp1g6zv0ce8oghu7****
ImageName	string	No	The name of the image. The name must be 2 to 128 characters long. It must start with a letter or a Chinese character and must not start with http:// or https://. The name can contain digits, colons (:), underscores (_), and hyphens (-).	TestCentOS
ImageFamily	string	No	The name of the image family. The name must be 2 to 128 characters long and start with a letter or a Chinese character. It cannot start with aliyun or acs:, nor contain http:// or https://. The name can contain digits, colons (:), underscores (_), and hyphens (-).	hangzhou-daily-update
ImageVersion	string	No	The version of the image. Note If you specify an instance ID (`InstanceId`) and the instance was created from an Alibaba Cloud Marketplace image (or a custom image based on a Marketplace image), this parameter must match the `ImageVersion` of the instance's image or be left empty.	2017011017
Description	string	No	The image description. It must be 2 to 256 characters long and cannot start with http:// or https://.	ImageTestDescription
Platform	string	No	The operating system distribution. You must specify this parameter to identify the operating system distribution when you use a data disk snapshot to create the image's system disk. Valid values: Aliyun Anolis CentOS Ubuntu CoreOS SUSE Debian OpenSUSE FreeBSD RedHat Kylin UOS Fedora Fedora CoreOS CentOS Stream AlmaLinux Rocky Linux Gentoo Customized Linux Others Linux Windows Server 2022 Windows Server 2019 Windows Server 2016 Windows Server 2012 Windows Server 2008 Windows Server 2003 Default value: Others Linux.	CentOS
BootMode	string	No	The boot mode of the image. Valid values: BIOS: BIOS boot mode. UEFI: UEFI boot mode. UEFI-Preferred: The image supports both BIOS and UEFI boot modes. The UEFI boot mode is preferred. This is the default value. Important If you specify a boot mode that the image does not support, instances created from the image may fail to start. Before you specify this parameter, ensure you know the boot modes that the image supports. For more information, see Boot modes. Valid values: BIOS : BIOS UEFI : UEFI UEFI-Preferred : UEFI-Preferred	BIOS
Architecture	string	No	The system disk architecture. If you create the image's system disk from a data disk snapshot, you must specify this parameter to identify the system disk architecture. Valid values: i386 x86_64 arm64 Default value: x86_64.	x86_64
ClientToken	string	No	A client-generated token to ensure the request is idempotent. You must ensure that the token is unique across different requests. The `ClientToken` value can contain only ASCII characters and cannot exceed 64 characters. For more information, see How to ensure idempotency.	123e4567-e89b-12d3-a456-426655440000
ResourceGroupId	string	No	The ID of the resource group to which to add the custom image. If you do not specify this parameter, the image is added to the default resource group. Note As a RAM user, you must have the required permissions to call this operation. If you leave `ResourceGroupId` empty, the `Forbidden: User not authorized to operate on the specified resource` error is returned if you lack permissions on the default resource group. To resolve this issue, specify the ID of a resource group for which you have permissions, or ask an administrator to grant you permissions on the default resource group.	rg-bp67acfmxazb4p****
DiskDeviceMapping	array<object>	No	The mappings between disks and snapshots used to create the custom image. If you need to create a custom image from a system disk snapshot and data disk snapshots, specify this parameter.
	object	No	The cloud disk and snapshot used to create the custom image.
SnapshotId	string	No	The ID of the snapshot.	s-bp17441ohwkdca0****
Size	integer	No	The size of the cloud disk, in GiB. The valid values and default value of `DiskDeviceMapping.N.Size` vary based on whether `DiskDeviceMapping.N.SnapshotId` is specified. If `DiskDeviceMapping.N.SnapshotId` is not specified, the value of this parameter depends on the disk type: For basic disks, the value range is 5 to 2,000 and the default value is 5. For other disk types, the value range is 20 to 32,768 and the default value is 20. If `DiskDeviceMapping.N.SnapshotId` is specified, the value of `DiskDeviceMapping.N.Size` must be greater than or equal to the snapshot's size. The default value is the snapshot's size.	2000
Device	string	No	The device name of the disk in the custom image. Valid values: The device name of the system disk must be /dev/xvda. The device names of data disks are assigned in sequence from /dev/xvdb to /dev/xvdz and cannot be repeated.	/dev/xvdb
DiskType	string	No	The type of the disk in the image. You can specify this parameter to use a data disk snapshot as the system disk of the image. If you do not specify this parameter, the disk type is determined by the type of the source snapshot. Valid values: system: system disk. You can specify only one system disk snapshot. data: data disk. You can specify a maximum of 16 data disk snapshots.	system
Tag	array<object>	No	The tags to add to the image.
	object	No	The tags.
key	string	No	The key of tag N to add to the image. Note For compatibility, we recommend that you use the `Tag.N.Key` parameter.	null
Key	string	No	The key of tag N to add to the image. Note For compatibility, we recommend that you use the `Tag.N.Key` parameter.	KeyTest
Value	string	No	The value of tag N to add to the image. Valid values of N: 1 to 20. The tag value can be an empty string, up to 128 characters long, and cannot start with `acs:` or contain `http://` or `https://`.	ValueTest
value	string	No	The value of tag N to add to the image. Valid values of N: 1 to 20. The tag value can be an empty string, up to 128 characters long, and cannot start with `acs:` or contain `http://` or `https://`.	null
DetectionStrategy	string	No	The image check policy. If you do not specify this parameter, no check is performed. Only the Standard mode is supported. Note This feature is supported for most Linux and Windows versions. For more information about the check items and the operating systems that support this feature, see Overview of image check and Operating systems that support image check.	Standard
Features	object	No	The image attributes.
ImdsSupport	string	No	The instance metadata access mode. Valid values: v1: The normal mode. When you create an ECS instance from an image that has the metadata access mode set to this value, you cannot configure the instance metadata access mode as Enforced. v2: The enforced mode. When you create an ECS instance from an image that has the metadata access mode set to this value, you can configure the instance metadata access mode as Enforced. Default value: v1 if you create the image from a snapshot. If you create the image from an instance, the value is inherited from the source instance's image.	v2
DryRun	boolean	No	Specifies whether to perform a dry run to check the request. Valid values: true: performs a dry run but does not create the image. The system checks whether your AccessKey pair is valid, whether RAM users are granted permissions, and whether the required parameters are specified. If the request fails the dry run, an error code is returned. If the request passes the dry run, the `DryRunOperation` error code is returned. false: Sends the request to perform the operation. If the request is valid, a 2xx HTTP status code is returned and the image is created. Default value: false.

Response elements

Element	Type	Description	Example
	object	The returned data.
ImageId	string	The ID of the image.	m-bp146shijn7hujku****
RequestId	string	The ID of the request.	C8B26B44-0189-443E-9816-*******

Examples

Success response

JSON format

{
  "ImageId": "m-bp146shijn7hujku****",
  "RequestId": "C8B26B44-0189-443E-9816-*******"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidImageName.Malformed	The 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://.
400	InvalidImageName.Duplicated	The specified image name is already in use.	The specified image name is already in use.
400	InvalidDescription.Malformed	The 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://.
400	InvalidImageVersion.Malformed	The specified ImageVersion is wrongly formed.	The specified image version is invalid, or you are not authorized to use the snapshot.
400	IncorrectInstanceStatus	The current status of the instance does not support this operation.	The instance is in a state that does not support the current operation.
400	InstanceLockedForSecurity	The specified operation is denied as your instance is locked for security reasons.
400	InvalidDevice.Malformed	The specified parameter DiskDeviceMapping.n.Device is not valid.	The specified DiskDeviceMapping.N.Device parameter is invalid.
400	MissingParameter	The input parameter SnapshotId or InstanceId or DiskDeviceMapping that is mandatory for processing this request is not supplied.	The SnapshotId, InstanceId, and DiskDeviceMapping parameters are required.
400	InvalidSize.ValueNotSupported	The specified parameter DiskDeviceMapping.n.Size beyond the permitted range.	The specified DiskDeviceMapping.N.Size parameter is out of range.
400	InvalidDevice.InUse	The specified parameter DiskDeviceMapping.n.Device has been occupied.	Device names specified in the DiskDeviceMapping.N.Device value are already in use.
400	OperationDenied	The specified parameter DiskDeviceMapping.n.SnapshotId does not contain system disk snapshot.	The specified DiskDeviceMapping.N.SnapshotID parameter does not contain a system disk snapshot ID.
400	InvalidDiskCategory.CreateImage	The specified diskCategory is not allowed to create image.	Disks of the specified category cannot be used to create custom images.
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	The specified Architecture parameter is invalid.
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.
400	InvalidParameter.AllEmpty	%s
400	InvalidParameter.DiskType	The specified disk type which has kms key can't convert to system disk.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The specified tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	The specified Tag.N.Key parameter is invalid.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	The specified tag value is invalid.
400	InvalidInstance.NotFoundSystemDisk	The specified instance does not have system disk.
400	InvalidImageFamily.Malformed	The format of the specified image family is invalid.	The format of the specified image family is invalid.
400	ImageQuotaExceed.ImageFamily	The specified image family exceeds the maximum number of images for one image family.
400	ImageFamilyQuotaExceed	The number of image families exceeds the limit in the region.
400	InvalidDiskType.ValueNotSupported	The specified disk type is not supported.	The specified disk type is not supported.
400	IdempotenceParamNotMatch	Request uses a client token in a previous request but is not identical to that request.	This request and the previous request contain the same client token but different other parameters.
400	InvalidBootMode.NotSupport	The specified parameter BootMode is not supported for current image architecture.	The current image architecture does not support setting this boot mode.
400	InvalidParameter.FeaturesImdsSupport	The specified parameter Features.ImdsSupport is not supported.	The specified parameter Features.ImdsSupport is not supported.
400	InvalidOperation.DiskCategoryUnsupported	The current category of the disk does not support this operation.	The disk type does not support the current operation.
400	AccountForbidden.CreateOrder	Order cannot be created due to abnormal account.
400	InvalidBootMode.Malformed	The specified parameter BootMode is invalid. Valid options are BIOS, UEFI, and UEFI-Preferred.	The specified parameter BootMode is invalid. Valid options are BIOS, UEFI, and UEFI-Preferred.
400	InvalidDetectionStrategy.Malformed	The specified value for parameter DetectionStrategy is not supported. Please refer to the documentation for accepted values.	The specified DetectionStrategy parameter value is not supported. Refer to the documentation for acceptable values.
500	InternalError	The process of creating snapshot has failed due to some unknown error.	The snapshot cannot be created.
403	IncorrectDiskStatus.NeverAttached	The specified disk has never been attached to instance.
403	InvalidSnapshotId.NotReady	The current status of the DiskDeviceMapping.n.SnapshotId or SnapshotId does not support this operation.	The current disk has a snapshot being created, please try again later.
403	InvalidSnapshot.TooOld	This operation is denied because the specified snapshot by DiskDeviceMapping.n.SnapshotId or SnapshotId is created before 2013-07-15.	The operation is denied because the snapshot specified by the DiskDeviceMapping.N.SnapshotId or SnapshotId parameter 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	QuotaExceed.Image	The Image Quota exceeds.
403	InvalidParamter.Conflict	The specified same token is trying to make requests with different parameters.	The same token is used to make requests that contain different parameters.
403	InvalidAccountStatus.NotEnoughBalance	Your account does not have enough balance.
403	InvalidAccountStatus.SnapshotServiceUnavailable	Snapshot service has not been opened yet.	The operation is not supported while the snapshot service is not activated.
403	UserNotInTheWhiteList	The user is not in the white list of create image by data disk snapshot.	You are not authorized to create an image based on data disk snapshots. Try again when you are authorized to do so.
403	IncorrectDiskStatus.Invalid	Device status is invalid, please restart instance and try again.	The device is in an invalid state. Restart the instance and try again.
403	OperationDenied.InvalidSnapshotCategory	%s	This type of snapshot does not support the operation.
403	QuotaExceed.Snapshot	The snapshot quota exceeds.
403	IncorrectDiskStatus.Transferring	The specified device is transferring, you can retry after the process is finished.	The specified disk is being migrated. Wait until the migration is complete and try again.
403	IncorrectDiskStatus	The current disk status does not support this operation.
403	InvalidSystemSnapshot.Missing	%s
403	IncorrectDiskStatus.CreatingSnapshot	A previous snapshot creation is in process.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The CMK needs to be added ECS tag.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK needs to be enabled.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service have no right to access your KMS.	ECS is not authorized to access your KMS resources.
403	QuotaExceed.Tags	%s	The number of specified tags exceeds the upper limit. %s is a variable. An error message is dynamically returned based on call conditions.
403	InvalidSnapshotCategory.NotSupportImageCreation	The specified snapshot category does not support create image.
403	TooManySnapshot.Unfinished	There are too many snapshots being created, please wait for them to be created done.
403	HibernationConfigured.InstanceOperationForbidden	The operation is not permitted due to limit of the hibernation configured instance.	The operation cannot be performed due to the limitations of instances for which the instance hibernation feature is enabled.
403	SnapshotNotReady	The specified snapshot is not ready.	The specified snapshot is being created and cannot be used to create images.
403	IncorrectInstanceStatus.NeedRestart	The instance needs to be restarted after adding a disk in a shutdown status.	If you have attached disks to an instance in the Stopped state, you must start the instance before you can create a custom image from the instance.
403	QuotaExceed.ConcurrentSnapshotQuota	The number of snapshots being created for the disk %s has exceeded the concurrent quota (%s). Please wait for the previous snapshots to complete before trying again.	The number of snapshots being created for this disk has exceeded the concurrent quota. Please wait for the previous snapshots to complete before trying again.
403	InvalidOperation.SnapshotStorageLocationUnsupported	Snapshots with storage location in CloudBox do not support the current operation.	The snapshot of the storage location in the CloudBox does not support the current operation.
403	AccountEnterpriseStatusInvalid	Your enterprise registration is marked as revoked/deregistered in the National Enterprise Credit Information Publicity System. Account transaction features (purchase/renewal/recharge) are disabled. Please update real-name certification via Account Center. Restrictions will auto-remove after verification.	The registration status of your enterprise has been canceled (or revoked) in the national enterprise credit information publicity system, and your account will not be able to carry out transaction operations such as new purchase, renewal and recharge of products. Please change the real name authentication through the account center as soon as possible. After the change is completed, Aliyun will automatically lift the purchase restriction.
403	InvalidOperation.DefaultFreeSnapshotNotSupport	The specified snapshot is a default free snapshot and does not support this operation.	The specified snapshot is a default free snapshot and does not support the current operation.
404	InvalidSnapshotId.NotFound	The specified SnapshotId does not exist.
404	InvalidInstanceId.NotFound	The specified instance %s does not exist.	The specified instance does not exist.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The specified resource group does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.