All Products
Search
Document Center

Elastic Compute Service:CreateImage

Last Updated:May 14, 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

Usage notes

Take note of the following items:

  • You can use the created custom image only if the image is in the Available (Available) state.
  • If the response contains {"OperationLocks": {"LockReason" : "security"}} when you query the information of an instance, the instance is locked for security reasons. No operations are allowed on the instance.
  • To optimize the image, we recommend that you specify DetectionStrategy when you create the image. For more information, see Overview of image check.

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 of these 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 ID of the instance by using InstanceId. The instance must be in the Running (Running) or Stopped (Stopped) state. After you call the CreateImage operation, a snapshot is created for each disk of the instance. When you create a custom image from a running instance, cache data may not be written to disks. In this case, the data of the custom image may be slightly different from the data of the instance. We recommend that you stop instances by calling the StopInstances operation before you create custom images from the instances.
  • 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 by using SnapshotId. The specified system disk snapshot must be created after July 15, 2013.
  • Method 3: Create a custom image from multiple disk snapshots. You must specify data mappings between the snapshots and the disks to be created by using the parameters that start with DiskDeviceMapping.

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

  • You can specify only one snapshot to use to create the system disk in the custom image. The device name of the system disk must be /dev/xvda.
  • You can specify up to 16 snapshots to use to create data disks in the custom image. The device names of the data disks are unique and range from /dev/xvdb to /dev/xvdz in alphabetical order.
  • You can leave SnapshotId empty. In this case, an empty data disk with the specified size is created.
  • The specified disk snapshot must be created 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 you want to use to create the custom image.

s-bp17441ohwkdca0****
InstanceIdstringNo

The instance ID.

i-bp1g6zv0ce8oghu7****
ImageNamestringNo

The name 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 http:// or https://. The name can contain letters, digits, colons (:), underscores (_), and hyphens (-).

TestCentOS
ImageFamilystringNo

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

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 operating system distribution for the system disk in the custom image. If you specify a data disk snapshot to create the system disk of the custom image, use Platform to specify the operating system distribution for the 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
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 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 does not have the permissions to manage the default resource group and do not specify ResourceGroupId, the Forbbiden: 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 has the permissions to manage or grant the RAM user the permissions to manage the default resource group before you call the CreateImage operation again.
rg-bp67acfmxazb4p****
DiskDeviceMappingobject []No

The information about the custom image.

SnapshotIdstringNo

The ID of snapshot N to use 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 vary based on the value of DiskDeviceMapping.N.SnapshotId.

  • If no corresponding snapshot IDs are specified in the value of DiskDeviceMapping.N.SnapshotId, DiskDeviceMapping.N.Size has the following valid values and default values:

    • For basic disks, the valid values range from 5 to 2000, and the default value is 5.
    • For other disks, the valid values range from 20 to 32768, and the default value is 20.
  • If a corresponding snapshot ID is specified in the value of DiskDeviceMapping.N.SnapshotId, 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 alphabetical order.
  • For basic disks, the valid values range from /dev/xvda to /dev/xvdz in alphabetical order.
/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. You can specify only one snapshot to use to create the system disk in the custom image.
  • data: data disk. You can specify up to 16 snapshots to use to create data disks in the custom image.
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 in which to check the custom image. If you do not specify this parameter, the image is not checked. Only the standard check mode is supported.

Note This parameter is supported for most Linux and Windows operating system versions. For information about image check items and operating system limits for image check, see Overview of image check and Operating system limits for image check.
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.
400OperationDeniedShared snapshots do not support creating images.Shared snapshots do not support creating custom images.
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
2024-05-09The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
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