All Products
Search
Document Center

Elastic Compute Service:CreateImage

Last Updated:Mar 26, 2024

Creates a custom image. After you call this operation to create a custom image, you can call the RunInstances operation to create Elastic Compute Service (ECS) instances from the created custom image or call the ReplaceSystemDisk operation to replace system disks by using the custom image.

Operation description

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

  • You can use the created custom image only when the image is in the Available state.
  • If the responses contain {"OperationLocks": {"LockReason" : "security"}} when you query instance information, the instance is locked for security reasons. In this case, no operation can be performed on the instance.

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.

  • 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 or 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 must be created on or after 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 must be unique and in alphabetical order from /dev/xvdb to /dev/xvdz.
  • You can leave the SnapshotId parameter empty. In this case, an empty data disk with a specified size is created.
  • The specified disk snapshot must be created on or after July 15, 2013.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID of the custom image that you want to create. You can call the DescribeRegions operation to query the most recent list of regions.

cn-hangzhou
SnapshotIdstringNo

The ID of the snapshot that is used to create the custom image.

s-bp17441ohwkdca0****
InstanceIdstringNo

The instance ID.

i-bp1g6zv0ce8oghu7****
ImageNamestringNo

The image name. The name must be 2 to 128 characters in length and can contain digits, colons (:), underscores (_), and hyphens (-). The name must start with a letter but cannot start with http:// or https://.

TestCentOS
ImageFamilystringNo

The name of the image family. The name must be 2 to 128 characters in length and can contain digits, colons (:), underscores (_), and hyphens (-). The name must start with a letter and cannot start with acs: or aliyun. It cannot contain http:// or https://.

hangzhou-daily-update
ImageVersionstringNo

The image version.

Note If you specify an instance by configuring InstanceId, and the instance uses an Alibaba Cloud Marketplace image or a custom image that is created from an Alibaba Cloud Marketplace image, you must leave this parameter empty or set this parameter to the value of ImageVersion of the instance.
2017011017
DescriptionstringNo

The image description. The description must be 2 to 256 characters in length and cannot start with http:// or https://.

ImageTestDescription
PlatformstringNo

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 Platform 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.

CentOS
BootModestringNo

The boot mode of the image. Valid values:

  • BIOS
  • UEFI
Note You must be familiar with the boot modes supported by the specified image. 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 that use this image can be started as expected.
BIOS
ArchitecturestringNo

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 Architecture to specify the system architecture of the system disk. Valid values:

  • i386
  • x86_64
  • arm64

Default value: x86_64.

x86_64
ClientTokenstringNo

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 value of 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
ResourceGroupIdstringNo

The ID of the resource group to which you want to assign the custom image. If you leave this parameter empty, the image is assigned to the default resource group.

Note If you call the CreateImage operation as a RAM user who is not authorized to manage the default resource group and leave ResourceGroupId empty, the Forbidden: User not authorized to operate on the specified resource error message is returned. Before you call the CreateImage operation again, 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.
rg-bp67acfmxazb4p****
DiskDeviceMappingobject []No

The custom images.

SnapshotIdstringNo

The ID of the snapshot that is used to create the custom image.

s-bp17441ohwkdca0****
SizeintegerNo

The size of disk N in the custom image. Unit: GiB. The valid values and default value of DiskDeviceMapping.N.Size depend on the value of 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 types of disk, 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.

2000
DevicestringNo

The device name of disk N in the custom image. Valid values:

  • For disks other than basic disks, such as standard SSDs, ultra disks, and enhanced SSDs (ESSDs), the valid values range from /dev/vda to /dev/vdz in ascending alphabetical order.
  • For basic disks, the valid values are in alphabetical order from /dev/xvda to /dev/xvdz.
/dev/vdb
DiskTypestringNo

The type of disk N in the custom image. You can specify this parameter to create the system disk of the custom image from a data disk snapshot. If you do not specify this parameter, the disk type is determined by the corresponding snapshot. Valid values:

  • system: system disk
  • data: data disk
system
Tagobject []No

The tags.

keystringNo

The tag key of the custom image.

Note This parameter will be deprecated in the future. We recommend that you use the Tag.N.key parameter to ensure future compatibility.
null
KeystringNo

The key of tag N of the custom 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://.

KeyTest
ValuestringNo

The value of tag N of the custom 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://.

ValueTest
valuestringNo

The tag value of the custom image.

Note This parameter will be deprecated in the future. We recommend that you use the Tag.N.Value parameter to ensure future compatibility.
null
DetectionStrategystringNo

The mode that you want to use 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 Non-Volatile Memory Express (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. Examples: Linux and Windows.
  • OSVersion: the operating system version. Example: Centos 7.9.
  • Architecture: the architecture. Examples: ARM and x86_64.
  • BootMode: the boot mode. Examples: UEFI and Legacy.
  • KernelVersion: the kernel version.
  • CloudAssistant: whether the Cloud Assistant client is installed.
  • SecurityCenterAgent: whether the Security Center agent is installed.
Standard

Response parameters

ParameterTypeDescriptionExample
object
ImageIdstring

The image ID.

m-bp146shijn7hujku****
RequestIdstring

The request ID.

C8B26B44-0189-443E-9816-*******

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError messageDescription
400InvalidImageName.MalformedThe 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://.
400InvalidImageName.DuplicatedThe specified Image name has already bean used.-
400InvalidDescription.MalformedThe 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://.
400InvalidImageVersion.MalformedThe specified ImageVersion is wrongly formed.The specified image version is invalid, or you are not authorized to use the snapshot.
400IncorrectInstanceStatusThe current status of the instance does not support this operation.The instance is in a state that does not support the current operation.
400InstanceLockedForSecurityThe specified operation is denied as your instance is locked for security reasons.-
400InvalidDevice.MalformedThe specified parameter DiskDeviceMapping.n.Device is not valid.The specified DiskDeviceMapping.N.Device parameter is invalid.
400MissingParameterThe 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.
400InvalidSize.ValueNotSupportedThe specified parameter DiskDeviceMapping.n.Size beyond the permitted range.The specified DiskDeviceMapping.N.Size parameter is out of range.
400InvalidDevice.InUseThe specified parameter DiskDeviceMapping.n.Device has been occupied.Device names specified in the DiskDeviceMapping.N.Device value are already in use.
400OperationDeniedThe 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.
400OperationDeniedThe specified parameter DiskDeviceMapping.n.SnapshotId contains two or more system disk snapshots.The specified DiskDeviceMapping.N.SnapshotID value already contains a system disk snapshot ID.
400InvalidDiskCategory.CreateImageThe specified diskCategory is not allowed to create image.Disks of the specified category cannot be used to create custom images.
400InvalidArchitecture.MalformedThe specified Architecture is wrongly formed.The specified Architecture parameter is invalid.
400InvalidPlatform.MalformedThe specified Platform is wrongly formed.-
400OperationDeniedNot support creating system image from an encrypted snapshot/disk.An encrypted disk or snapshot cannot be used to create custom images.
400InvalidParameter.AllEmpty%sThe required parameters are not specified.
400InvalidParameter.DiskTypeThe specified disk type which has kms key can't convert to system disk.-
400Duplicate.TagKeyThe Tag.N.Key contain duplicate key.The specified tag key already exists. Tag keys must be unique.
400InvalidTagKey.MalformedThe specified Tag.n.Key is not valid.The specified Tag.N.Key parameter is invalid.
400InvalidTagValue.MalformedThe specified Tag.n.Value is not valid.The specified tag value is invalid.
400InvalidInstance.NotFoundSystemDiskThe specified instance does not have system disk.-
400InvalidImageFamily.MalformedThe format of the specified image family is invalid.-
400ImageQuotaExceed.ImageFamilyThe specified image family exceeds the maximum number of images for one image family.-
400ImageFamilyQuotaExceedThe number of image families exceeds the limit in the region.-
400InvalidDiskType.ValueNotSupportedThe specified disk type is not supported.The specified disk type is not supported.
400IdempotenceParamNotMatchRequest 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.
403IncorrectDiskStatus.NeverAttachedThe specified disk has never been attached to instance.-
403InvalidSnapshotId.NotReadyThe current status of the DiskDeviceMapping.n.SnapshotId or SnapshotId does not support this operation.The operation is not supported while the specified snapshot is in the current state.
403InvalidSnapshot.TooOldThis 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.
403OperationDeniedThe specified snapshot is not allowed to create image.The specified snapshot cannot be used to create images.
403QuotaExceed.ImageThe Image Quota exceeds.The custom image quota has been used up.
403OperationDeniedThe specified snapshot is not from system disk.The specified snapshot is not a system disk snapshot.
403InvalidParamter.ConflictThe specified same token is trying to make requests with different parameters.The same token is used to make requests that contain different parameters.
403InvalidAccountStatus.NotEnoughBalanceYour account does not have enough balance.Your account balance is insufficient. Add funds to your account and try again.
403InvalidAccountStatus.SnapshotServiceUnavailableSnapshot service has not been opened yet.The operation is not supported while the snapshot service is not activated.
403UserNotInTheWhiteListThe 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.
403IncorrectDiskStatus.InvalidDevice status is invalid, please restart instance and try again.The device is in an invalid state. Restart the instance and try again.
403OperationDenied.InvalidSnapshotCategory%sThis type of snapshot does not support the operation.
403QuotaExceed.SnapshotThe snapshot quota exceeds.The maximum number of snapshots has been reached. Delete snapshots that are no longer needed and try again.
403IncorrectDiskStatus.TransferringThe 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.
403IncorrectDiskStatusThe current disk status does not support this operation.The disk is in a state that does not support the current operation. Make sure that the disk is available and that your account has no overdue payments.
403InvalidSystemSnapshot.Missing%s-
403IncorrectDiskStatus.CreatingSnapshotA previous snapshot creation is in process.A previous snapshot creation task is in process. Please try again later.
403InvalidParameter.KMSKeyId.CMKUnauthorizedThe CMK needs to be added ECS tag.-
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.
403QuotaExceed.Tags%sThe number of specified tags exceeds the upper limit. %s is a variable. An error message is dynamically returned based on call conditions.
403InvalidSnapshotCategory.NotSupportImageCreationThe specified snapshot category does not support create image.-
403TooManySnapshot.UnfinishedThere are too many snapshots being created, please wait for them to be created done.-
403HibernationConfigured.InstanceOperationForbiddenThe 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.
403SnapshotNotReadyThe specified snapshot is not ready.The specified snapshot is being created and cannot be used to create images.
403IncorrectInstanceStatus.NeedRestartThe 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.
404InvalidSnapshotId.NotFoundThe specified SnapshotId does not exist.The specified snapshot ID does not exist.
404InvalidInstanceId.NotFoundThe specified InstanceId does not exist.The specified instance does not exist.
404InvalidResourceGroup.NotFoundThe ResourceGroup provided does not exist in our records.The specified resource group does not exist.
500InternalErrorThe process of creating snapshot has failed due to some unknown error.The snapshot cannot be created.
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
2021-06-17The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 403 change
    delete Error Codes: 400
    delete Error Codes: 404
    delete Error Codes: 500