All Products
Search
Document Center

:CreateImage

最終更新日:Oct 19, 2023

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.

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 responses contain {"OperationLocks": {"LockReason" : "security"}} for an instance when you query instance information, the instance is locked for security reasons and all operations are prohibited on it.

  • To optimize your 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 the InstanceId parameter. 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 the SnapshotId parameter. 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 the data mapping between the disks and the snapshots 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.

  • SnapshotId may not be specified. In this case, an empty data disk with a specific 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. 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 you want to use to create the custom image.

InstanceId

String

No

i-bp1g6zv0ce8oghu7****

The ID of the instance that you want to use to create the custom image.

ImageName

String

No

TestCentOS

The custom image name. 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 digits, letters, 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. It must start with a letter and cannot start with acs: or aliyun. It cannot contain http:// or https://. It can contain digits, letters, colons (:), underscores (_), and hyphens (-).

ImageVersion

String

No

2017011017

The image version.

Note

If you specify InstanceId and the specified instance uses an Alibaba Cloud Marketplace image or a custom image that is derived from an Alibaba Cloud Marketplace image, this parameter must be left empty or set to the ImageVersion value of the instance.

Description

String

No

ImageTestDescription

The image description. 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, use Platform to specify the distribution of the operating system 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.

BootMode

String

No

BIOS

The boot mode of the custom image. Valid values:

  • BIOS

  • UEFI

Note

You must familiarize yourself with 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 that 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, use Architecture 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 token, but you must make sure that the token is unique among different requests. The token 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 ResourceGroupId, 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 disk N in 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 vary based on the value of DiskDeviceMapping.N.SnapshotId.

  • If no corresponding snapshot IDs are specified in the value of DiskDeviceMapping.N.SnapshotId, the DiskDeviceMapping.N.Size parameter 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.

DiskDeviceMapping.N.Device

String

No

/dev/vdb

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 ascending alphabetical order.

DiskDeviceMapping.N.DiskType

String

No

system

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.

Tag.N.key

String

No

null

The key of tag N to add to 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 to add to 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 contain http:// or https://. It cannot start with acs: or aliyun.

Tag.N.Value

String

No

ValueTest

The value of tag N to add to 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. It cannot start with acs: or contain http:// or https://.

Tag.N.value

String

No

null

The value of tag N to add to 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 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 images. For more information about image check items and operating system limits for image check, see Overview of image check and Operating system limits for image check.

Response parameters

Parameter

Type

Example

Description

ImageId

String

m-bp146shijn7hujku****

The custom image ID.

RequestId

String

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

The request ID.

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 success 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. It 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 because 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 instance is locked for security reasons.

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 start with 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 snapshots, delete snapshots that are no longer needed.

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 available 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

HibernationConfigured.InstanceOperationForbidden

The operation is not permitted due to limit of the hibernation configured instance.

The error message returned because 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 error message returned because 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 does not exist.

404

InvalidResourceGroup.NotFound

The ResourceGroup provided does not exist in our records.

The error message returned because the specified ResourceGroupId parameter 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, see Service error codes.