CreateImage - Elastic Compute Service - Alibaba Cloud Documentation Center

Creates a custom image. The created custom image can be used to create Elastic Compute Service (ECS) instances (RunInstances) and replace system disks (ReplaceSystemDisk).

Description

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

The created custom image can be used only when it is in the Available (Available) state.
If the response contains {"OperationLocks": {"LockReason" : "security"}} when you query the information of the instance, the instance is locked for security reasons and all operations are prohibited on it.

You can call the CreateImage operation to create a custom image by using one of the following methods. The following request parameters are sorted by priority: InstanceId > DiskDeviceMapping > SnapshotId. If your request contains two or more parameters, the custom image is created based on the parameter that has a higher priority by default.

Method 1: Create a custom image from an instance. You need to only specify the instance ID (InstanceId). The instance must be in the Running (Running) or Stopped (Stopped) state. After the CreateImage operation is called, a snapshot is created for each disk of the instance. When you create a custom image from a running instance, some cache data may not be written to the disks. As a result, the data of the created custom image may be slightly inconsistent with that of the instance. We recommend that you create custom images from instances after you stop the instances (StopInstances).
Method 2: Create a custom image from the system disk snapshot of an instance. You need to only specify the ID of the system disk snapshot (SnapshotId). The specified snapshot cannot be created on or before July 15, 2013.
Method 3: Create a custom image from multiple disk snapshots. You must specify the data mapping between the disks and the snapshots (DiskDeviceMapping).

When you use Method 3 to create a custom image, take note of the following items:

You can specify only one system disk snapshot. The device name of the system disk must be /dev/xvda.
You can specify multiple data disk snapshots. The device names of the data disks are unique and in alphabetical order from /dev/xvdb to /dev/xvdz.
SnapshotId may not be specified. In this case, an empty data disk with a specified size is created.
The specified snapshot cannot be created on or before July 15, 2013.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	CreateImage	The operation that you want to perform. Set the value to CreateImage.
RegionId	String	Yes	cn-hangzhou	The ID of the region in which to create the custom image. You can call the DescribeRegions operation to query the most recent region list.
SnapshotId	String	No	s-bp17441ohwkdca0****	The ID of the snapshot that is used to create the custom image.
InstanceId	String	No	i-bp1g6zv0ce8oghu7****	The ID of the instance.
ImageName	String	No	TestCentOS	The name of the custom image. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with http:// or https://. It can contain letters, digits, colons (:), underscores (_), and hyphens (-).
ImageFamily	String	No	hangzhou-daily-update	The name of the image family of the custom image. The name must be 2 to 128 characters in length. The name must start with a letter and cannot start with acs: or aliyun. It cannot contain http:// or https://. It can contain letters, digits, colons (:), underscores (_), and hyphens (-).
ImageVersion	String	No	2017011017	The version of the custom image. Note If you specify an instance by setting `InstanceId` and the instance uses an Alibaba Cloud Marketplace image or a custom image derived from an Alibaba Cloud Marketplace image, this parameter must be left empty or set to the value of the ImageVersion parameter of the instance.
Description	String	No	ImageTestDescription	The description of the custom image. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
Platform	String	No	CentOS	The distribution of the operating system for the system disk in the custom image. If you specify a data disk snapshot to create the system disk of the custom image, you must use the Platform parameter to specify the distribution of the operating system for the system disk. Valid values: CentOS Ubuntu SUSE OpenSUSE RedHat Debian CoreOS Aliyun Windows Server 2012 Windows 7 Customized Linux Others Linux Default value: Others Linux.
BootMode	String	No	BIOS	The boot mode of the custom image. Valid values: BIOS UEFI Note You must know which boot modes the specified image supports. When you use this parameter to change the boot mode of the image, specify a boot mode supported by the image to ensure that instances which use this image can start normally.
Architecture	String	No	x86_64	The system architecture of the system disk. If you specify a data disk snapshot to create the system disk of the custom image, you must use the Architecture parameter to specify the system architecture of the system disk. Valid values: i386 x86_64 arm64 Default value: x86_64.
ClientToken	String	No	123e4567-e89b-12d3-a456-426655440000	The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.
ResourceGroupId	String	No	rg-bp67acfmxazb4p****	The ID of the resource group to which to assign the custom image. If you do not specify this parameter, the image is assigned to the default resource group. Note If you call the CreateImage 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.
DiskDeviceMapping.N.SnapshotId	String	No	s-bp17441ohwkdca0****	The ID of the snapshot that is used to create the custom image.
DiskDeviceMapping.N.Size	Integer	No	2000	The size of disk N in the custom image. Unit: GiB. The valid values and default value of DiskDeviceMapping.N.Size depend on DiskDeviceMapping.N.SnapshotId. If no corresponding snapshot IDs are specified in the DiskDeviceMapping.N.SnapshotId value, the following valid values and default values are available for DiskDeviceMapping.N.Size: For basic disks, the valid values are 5 to 2000, and the default value is 5. For other disk categories, the valid values are 20 to 32768, and the default value is 20. If a corresponding snapshot ID is specified in the DiskDeviceMapping.N.SnapshotId value, the value of DiskDeviceMapping.N.Size must be greater than or equal to the size of the specified snapshot. The default value of DiskDeviceMapping.N.Size is the size of the specified snapshot.
DiskDeviceMapping.N.Device	String	No	/dev/vdb	The device name of disk N in the custom image. Valid values: For disk categories other than basic disks, such as standard SSDs, ultra disks, and enhanced SSDs (ESSDs), the valid values are in alphabetical order from /dev/vda to /dev/vdz. For basic disks, the valid values are in alphabetical order from /dev/xvda to /dev/xvdz.
DiskDeviceMapping.N.DiskType	String	No	system	The type of disk N in the custom image. You can set this parameter to create the system disk of the custom image from a data disk snapshot. If you do not set this parameter, the disk type is determined by the corresponding snapshot. Valid values: system: system disk data: data disk
Tag.N.key	String	No	null	The key of tag N of the custom image. Note This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure future compatibility.
Tag.N.Key	String	No	KeyTest	The key of tag N of the custom image. Valid values of N: 1 to 20. The tag key cannot be an empty string. It can be up to 128 characters in length and cannot contain `http://` or `https://`. It cannot start with `aliyun` or `acs:`.
Tag.N.Value	String	No	ValueTest	The value of tag N of the custom image. Valid values of N: 1 to 20. The tag value can be an empty string. It can be up to 128 characters in length and cannot start with `acs:`. It cannot contain `http://` or `https://`.
Tag.N.value	String	No	null	The value of tag N of the custom image. Note This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure future compatibility.
DetectionStrategy	String	No	Standard	The mode in which to check the source image. If you do not specify this parameter, the source image is not checked. Only Linux images can be checked. Set the value to Standard, which indicates standard check mode. The following items are checked in standard check mode: Virtio: whether the virtio driver is installed. Fstab: whether mounting configurations in the fstab file are correct. Grub: whether GRand Unified Bootloader (GRUB) configurations are correct. SystemImage: whether the image is valid. Do not import images that are in the ISO format or empty. CloudInit: whether cloud-init is installed. NVMe: whether the NVMe driver is installed. Selinux: whether SElinux is enabled. OnlineResizeFS: whether the root partition can be automatically resized. Dhcp: whether Dynamic Host Configuration Protocol (DHCP) is enabled for network interface controllers (NICs). RtcTimeMode: the RTC time mode. Platform: the platform. Example: Linux or Windows. OSVersion: the operating system version. Example: Centos 7.9. Architecture: the architecture. Example: ARM or x86_64. BootMode: the boot mode. Example: UEFI or Legacy. KernelVersion: the kernel version. CloudAssistant: whether the Cloud Assistant client is installed. SecurityCenterAgent: whether the Security Center agent is installed.

Response parameters


Parameter	Type	Example	Description
ImageId	String	m-bp146shijn7hujku****	The ID of the custom image.
RequestId	String	C8B26B44-0189-443E-9816-*******	The ID of the request.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=CreateImage
&RegionId=cn-hangzhou
&DiskDeviceMapping.1.Size=2000
&DiskDeviceMapping.1.SnapshotId=s-bp17441ohwkdca0****
&DiskDeviceMapping.1.DiskType=system
&SnapshotId=s-bp17441ohwkdca0****
&InstanceId=i-bp1g6zv0ce8oghu7****
&ImageName=TestCentOS
&ImageVersion=2017011017
&Description=ImageTestDescription
&Platform=CentOS
&Architecture=x86_64
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&Tag.1.Key=KeyTest
&Tag.1.Value=ValueTest
&<Common request parameters>

Sample responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateImageResponse>
    <RequestId>C8B26B44-0189-443E-9816-*******</RequestId>
    <ImageId>m-bp146shijn7hujku****</ImageId>
</CreateImageResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidImageName.Malformed	The specified Image name is wrongly formed.	The error message returned because the specified image name is invalid. The name must be 2 to 128 characters in length. The name must start with a letter and cannot start with acs: or aliyun. It cannot contain http:// or https://. It can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-).
400	InvalidImageName.Duplicated	The specified Image name has already bean used.	The error message returned because the specified image name already exists.
400	InvalidDescription.Malformed	The specified description is wrongly formed.	The error message returned because the specified Description parameter 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 error message returned because 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 error message returned because this operation is not supported while the instance is in the current state.
400	InstanceLockedForSecurity	The specified operation is denied as your instance is locked for security reasons.	The error message returned because the operation is not supported while the instance is locked.
400	InvalidDevice.Malformed	The specified parameter DiskDeviceMapping.n.Device is not valid.	The error message returned because 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 error message returned because SnapshotId, InstanceId or parameters that contain DiskDeviceMapping are not specified.
400	InvalidSize.ValueNotSupported	The specified parameter DiskDeviceMapping.n.Size beyond the permitted range.	The error message returned because the specified DiskDeviceMapping.N.Size parameter is not within the permitted range.
400	InvalidDevice.InUse	The specified parameter DiskDeviceMapping.n.Device has been occupied.	The error message returned because 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 error message returned because the specified DiskDeviceMapping.N.SnapshotID parameter does not contain a system disk snapshot ID.
400	OperationDenied	The specified parameter DiskDeviceMapping.n.SnapshotId contains two or more system disk snapshots.	The error message returned because the specified DiskDeviceMapping.N.SnapshotID parameter already contains a system disk snapshot ID.
400	InvalidDiskCategory.CreateImage	The specified diskCategory is not allowed to create image.	The error message returned because the operation is not supported by the specified disk category.
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	The error message returned because the specified Architecture parameter is invalid.
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.	The error message returned because the specified Platform parameter is invalid.
400	OperationDenied	Not support creating system image from an encrypted snapshot/disk.	The error message returned because an encrypted disk or snapshot cannot be used to create custom images.
400	InvalidParameter.AllEmpty	%s	The error message returned because the required parameters are not specified.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The error message returned because the specified tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	The error message returned because the specified Tag.N.Key parameter is invalid.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	The error message returned because the specified Tag.N.Value parameter is invalid.
400	InvalidDiskType.ValueNotSupported	The specified disk type is not supported.	The error message returned because the specified disk type is invalid.
400	IdempotenceParamNotMatch	Request uses a client token in a previous request but is not identical to that request.	The error message returned because this request and the previous request contain the same client token but different parameters.
403	InvalidSnapshotId.NotReady	The current status of the DiskDeviceMapping.n.SnapshotId or SnapshotId does not support this operation.	The error message returned because the operation is not supported while the specified snapshot is in the current state.
403	InvalidSnapshot.TooOld	This operation is denied because the specified snapshot by DiskDeviceMapping.n.SnapshotId or SnapshotId is created before 2013-07-15.	The error message returned because this operation is denied. 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 error message returned because the specified snapshot cannot be used to create images.
403	QuotaExceed.Image	The Image Quota exceeds.	The error message returned because the quota for custom images has been used up.
403	OperationDenied	The specified snapshot is not from system disk.	The error message returned because the specified snapshot is not a system disk snapshot.
403	InvalidParamter.Conflict	The specified same token is trying to make requests with different parameters.	The error message returned because the same token is used to make requests that contain different parameters.
403	InvalidAccountStatus.NotEnoughBalance	Your account does not have enough balance.	The error message returned because your account balance is insufficient. Add funds to your account and try again.
403	InvalidAccountStatus.SnapshotServiceUnavailable	Snapshot service has not been opened yet.	The error message returned because 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.	The error message returned because you are not authorized to create an image from 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 error message returned because the device is in an invalid state. Restart the instance and try again.
403	OperationDenied.InvalidSnapshotCategory	%s	The error message returned because the operation is not supported by the snapshot type.
403	QuotaExceed.Snapshot	The snapshot quota exceeds.	The error message returned because the maximum number of snapshots has been reached. To store new snapshots, delete snapshots that you no longer need.
403	IncorrectDiskStatus.Transferring	The specified device is transferring, you can retry after the process is finished.	The error message returned because the specified disk is being migrated. Wait until the disk is migrated and try again.
403	IncorrectDiskStatus	The current disk status does not support this operation.	The error message returned because the operation is not supported while the disk is in the current state. Make sure that the disk is usable and you have no overdue payments for it.
403	IncorrectDiskStatus.CreatingSnapshot	A previous snapshot creation is in process.	The error message returned because another snapshot is being created for the disk. Wait until the snapshot is created and try again.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK needs to be enabled.	The error message returned because the customer master key (CMK) is not enabled when a Key Management Service (KMS) key ID is specified for a disk. You can call the DescribeKey operation of KMS to query the information about the specified CMK.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service have no right to access your KMS.	The error message returned because ECS is not authorized to access your KMS resources.
403	QuotaExceed.Tags	%s	The error message returned because the number of specified tags exceeds the upper limit. %s is a variable. An error message is dynamically returned based on call conditions.
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.	The error message returned because the instance is not restarted. If you attach disks to an instance that is in the Stopped state, you must restart the instance before you can create custom images from the instance.
404	InvalidSnapshotId.NotFound	The specified SnapshotId does not exist.	The error message returned because the specified SnapshotId parameter does not exist.
404	InvalidInstanceId.NotFound	The specified InstanceId does not exist.	The error message returned because the specified InstanceId parameter is invalid.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The error message returned because the specified resource group does not exist.
500	InternalError	The process of creating snapshot has failed due to some unknown error.	The error message returned because the snapshot cannot be created.
500	InternalError	The request processing has failed due to some unknown error, exception or failure.	The error message returned because an internal error has occurred. Try again later.

For a list of error codes, visit the API Error Center.