All Products
Search
Document Center

Elastic Compute Service:CreateImage

Last Updated:Dec 03, 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 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

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:CreateImagecreate
*Image
acs:ecs:{#regionId}:{#accountId}:image/*
*Instance
acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
*Snapshot
acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}
    none
none

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: Basic Input/Output System (BIOS)
  • UEFI: Unified Extensible Firmware Interface (UEFI)
  • UEFI-Preferred: BIOS and UEFI
Note Before you change the boot mode of an image, we recommend that you get familiar with the boot modes supported by the image to ensure that instances created from the image can start as expected. If you do not know which boot modes are supported by the image, we recommend that you use the image check feature to perform a check. For information about the image check feature, see Overview of image check.
Note For information about the UEFI-Preferred boot mode, see Best practices for ECS instance boot modes.
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****
DiskDeviceMappingarray<object>No

The information about the custom image.

objectNo

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
Tagarray<object>No

The tags.

objectNo

The information about the tag.

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.The 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.
400InvalidBootMode.NotSupportThe specified parameter BootMode is not supported for current image architecture.The current image architecture does not support setting this boot mode.
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 current disk has a snapshot being created, please try again later.
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.
403QuotaExceed.ConcurrentSnapshotQuotaThe 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.
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-10-22The Error code has changedView Change Details
2024-06-12The Error code has changedView Change Details
2024-05-09The Error code has changedView Change Details
2021-06-17The Error code has changedView Change Details