CreateImage-阿里云帮助中心

Creates a custom image. You can then use the created custom image to create ECS instances by calling RunInstances, or replace the system cloud disk of an instance by calling ReplaceSystemDisk.

Operation description

Precautions

This operation is asynchronous. After a request to create a custom image is sent, an image ID is returned. The image is not created immediately. You must call DescribeImage to query the image information. When the returned status is Available, the image is created and available. For more information, see Custom image overview.
When you query ECS instance information, if the returned data contains {"OperationLocks": {"LockReason" : "security"}}, you cannot create a custom image.
Configure the DetectionStrategy parameter when creating an image to help the system optimize your image. For more information, see Image check overview.

The following section describes three methods for creating a custom image by using this operation. The priority of request parameters is as follows: InstanceId > DiskDeviceMapping > SnapshotId. If your request contains two or more of these parameters, the parameter with the highest priority is used to create the image.

Create a custom image from an instance: Specify the instance ID (InstanceId).
- The instance must be in the Running (Running) or Stopped (Stopped) state.
- After the operation is called, a snapshot is created for each cloud disk of the instance.
Important Running instances may have cached data that is not written to disks. This may cause the data in the created custom image to be inconsistent with the instance data. Therefore, stop the instance (StopInstances) before creating an image.
Create a custom image from a snapshot (The specified snapshot cannot be created on or before July 15, 2013.)
- Create a custom image from a system cloud disk snapshot: Specify only the snapshot ID (SnapshotId) of the instance system cloud disk.
- Create a custom image from a system cloud disk snapshot and data cloud disk snapshots: Specify the data associations of multiple cloud disks (DiskDeviceMapping).
  - Only one system cloud disk snapshot can be specified.
  - Multiple data cloud disk snapshots can be specified, up to 16. If DiskDeviceMapping.N.SnapshotId is not specified, an empty data cloud disk with the default capacity is created.

Note

When an instance is released, the system cloud disk is retained as a pay-as-you-go data cloud disk. Snapshots created from this disk cannot be used to create custom images. Create custom images before the instance is released as needed.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:CreateImage

create

*Image

acs:ecs:{#regionId}:{#accountId}:image/*

Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

Snapshot

acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the image. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
SnapshotId	string	No	The ID of the snapshot used to create the custom image. Note If you create a custom image only from the system cloud disk snapshot of an instance, you can use this parameter or the `DiskDeviceMapping.N.SnapshotId` parameter. If you add data cloud disk snapshots, you can only use the `DiskDeviceMapping.N.SnapshotId` parameter to specify the snapshots.	s-bp17441ohwkdca0****
InstanceId	string	No	The instance ID. This parameter is required when you create a custom image from an instance.	i-bp1g6zv0ce8oghu7****
ImageName	string	No	The image name. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and cannot start with http:// or https://. It can contain digits, colons (:), underscores (_), and hyphens (-).	TestCentOS
ImageFamily	string	No	The name of the image family. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character. It cannot start with aliyun or acs:, and cannot contain http:// or https://. It can contain digits, colons (:), underscores (_), and hyphens (-).	hangzhou-daily-update
ImageVersion	string	No	The image version. Note If you specify the instance ID (`InstanceId`) and the image of the instance is an Alibaba Cloud Marketplace image or a custom image created from an Alibaba Cloud Marketplace image, this parameter must be the same as the `ImageVersion` of the current instance image or left empty.	2017011017
Description	string	No	The image description. The description must be 2 to 256 characters in length and cannot start with http:// or https://.	ImageTestDescription
Platform	string	No	The operating system. After you specify a data cloud disk snapshot as the system cloud disk of the image, you must use Platform to determine the operating system distribution of the system cloud 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
BootMode	string	No	The boot mode of the image. Valid values: BIOS: BIOS boot mode. UEFI: UEFI boot mode. UEFI-Preferred: Dual boot mode. Important To prevent the instance from failing to start due to an unsupported boot mode, make sure that you understand the boot modes supported by the destination image before you configure this parameter. For more information about image boot modes, see Image boot modes. Valid values: BIOS : BIOS UEFI : UEFI UEFI-Preferred : UEFI-Preferred	BIOS
Architecture	string	No	The system architecture. After you specify a data cloud disk snapshot as the system cloud disk of the image, you must use Architecture to determine the system architecture of the system cloud disk. Valid values: i386. x86_64. arm64. Default value: x86_64.	x86_64
ClientToken	string	No	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.	123e4567-e89b-12d3-a456-426655440000
ResourceGroupId	string	No	The ID of the resource group to which the custom image belongs. If you do not configure this parameter, the created image belongs to the default resource group. Note If you use a Resource Access Management (RAM) user to invoke this operation and `ResourceGroupId` is left empty, note that if the Resource Access Management (RAM) user does not have permissions on the default resource group, the `Forbidden: User not authorized to operate on the specified resource` error message is returned. Update the Settings to the ID of a resource group on which the Resource Access Management (RAM) user has permissions, or use the corresponding Alibaba Cloud account to grant the Resource Access Management (RAM) user permissions on the default resource group before you invoke this operation again.	rg-bp67acfmxazb4p****
DiskDeviceMapping	array<object>	No	The information about the cloud disks and snapshots used to create the custom image. If you want to create a custom image from a system cloud disk snapshot and data cloud disk snapshots, use this parameter to specify the snapshots.
	object	No	The cloud disks and snapshots used to create the custom image.
Device	string	No	The device name of the cloud disk in the custom image. Valid values: The device name of the system cloud disk must be /dev/xvda. The device names of data cloud disks range from /dev/xvdb to /dev/xvdz and must be unique.	/dev/xvdb
DiskType	string	No	The cloud disk type in the new image. You can use this parameter to specify a data cloud disk snapshot as the system cloud disk of the image. If you do not specify this parameter, the default value is the cloud disk type corresponding to the snapshot. Valid values: system: system cloud disk. Only one system cloud disk snapshot can be specified. data: data cloud disk. Up to 16 data cloud disk snapshots can be specified.	system
Size	integer	No	The size of the cloud disk. Unit: GiB. The valid values and default value of DiskDeviceMapping.N.Size depend on DiskDeviceMapping.N.SnapshotId: If SnapshotId is not specified, the valid values and default value of Size are as follows: Basic cloud disk: 5 to 2000 GiB. Default value: 5. Other cloud disks: 20 to 32768 GiB. Default value: 20. If SnapshotId is specified, the value of Size must be greater than or equal to the size of the snapshot specified by SnapshotId. The default value is the size of the snapshot.	2000
SnapshotId	string	No	The snapshot ID.	s-bp17441ohwkdca0****
Tag	array<object>	No	The tags.
	object	No	The tags.
Key	string	No	The tag key of the image. Valid values of N: 1 to 20. If you specify this parameter, it cannot be an empty string. The tag key can be up to 128 characters in length. It cannot start with `aliyun` or `acs:` and cannot contain `http://` or `https://`.	KeyTest
Value	string	No	The tag value of the image. Valid values of N: 1 to 20. If you specify this parameter, it can be an empty string. The tag value can be up to 128 characters in length. It cannot start with `acs:` and cannot contain `http://` or `https://`.	ValueTest
key	string	No	The tag key of the image. Note To improve compatibility, use the Tag.N.Key parameter.	null
value	string	No	The tag value of the image. Note To improve compatibility, use the Tag.N.Value parameter.	null
DetectionStrategy	string	No	The image check strategy. If you do not configure this parameter, no check is triggered. Only the standard (Standard) check mode is supported. Note Most Linux and Windows versions are supported. For more information about image check items and operating system limits, see Image check overview and Operating system limits for image checks.	Standard
Features	object	No	The image feature attributes.
ImdsSupport	string	No	The metadata access mode of the image. Valid values: v1: When you create an ECS instance from this image, you cannot set the metadata access mode to Reinforced mode. v2: When you create an ECS instance from this image, you can set the metadata access mode to Reinforced mode. Default value: If you create an image from a snapshot, the default value is v1. If you create an image from an instance, the default value is the ImdsSupport attribute value of the image used when the instance was created.	v2
DryRun	boolean	No
SecureBootOptions	object	No	The Secure Boot parameters.
SecureBootSupport	string	No	Specifies whether the image supports Secure Boot. Valid values: supported: The image supports Secure Boot. unsupported: The image does not support Secure Boot. Note Secure Boot only supports the UEFI or UEFI-Preferred boot mode.

Response elements

Element	Type	Description	Example
	object
ImageId	string	The image ID.	m-bp146shijn7hujku****
RequestId	string	The request ID.	C8B26B44-0189-443E-9816-*******

Examples

Success response

JSON format

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

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidImageName.Malformed	The 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://.
400	InvalidImageName.Duplicated	The specified image name is already in use.	The specified image name is already in use.
400	InvalidDescription.Malformed	The 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://.
400	InvalidImageVersion.Malformed	The specified ImageVersion is wrongly formed.	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 instance is in a state that does not support the current operation.
400	InstanceLockedForSecurity	The specified operation is denied as your instance is locked for security reasons.
400	InvalidDevice.Malformed	The specified parameter DiskDeviceMapping.n.Device is not valid.	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 SnapshotId, InstanceId, and DiskDeviceMapping parameters are required.
400	InvalidSize.ValueNotSupported	The specified parameter DiskDeviceMapping.n.Size beyond the permitted range.	The specified DiskDeviceMapping.N.Size parameter is out of range.
400	InvalidDevice.InUse	The specified parameter DiskDeviceMapping.n.Device has been occupied.	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 specified DiskDeviceMapping.N.SnapshotID parameter does not contain a system disk snapshot ID.
400	InvalidDiskCategory.CreateImage	The specified diskCategory is not allowed to create image.	Disks of the specified category cannot be used to create custom images.
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	The specified Architecture parameter is invalid.
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.	The operating system distribution of the specified image is invalid.
400	InvalidParameter.AllEmpty	%s
400	InvalidParameter.DiskType	The specified disk type which has kms key can't convert to system disk.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The specified tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	The specified Tag.N.Key parameter is invalid.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	The specified tag value is invalid.
400	InvalidInstance.NotFoundSystemDisk	The specified instance does not have system disk.
400	InvalidImageFamily.Malformed	The format of the specified image family is invalid.	The format of the specified image family is invalid.
400	ImageQuotaExceed.ImageFamily	The specified image family exceeds the maximum number of images for one image family.
400	ImageFamilyQuotaExceed	The number of image families exceeds the limit in the region.
400	InvalidDiskType.ValueNotSupported	The specified disk type is not supported.	The specified disk type is not supported.
400	IdempotenceParamNotMatch	Request 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.
400	InvalidBootMode.NotSupport	The specified parameter BootMode is not supported for current image architecture.	The current image architecture does not support setting this boot mode.
400	InvalidParameter.FeaturesImdsSupport	The specified parameter Features.ImdsSupport is not supported.	The specified parameter Features.ImdsSupport is not supported.
400	InvalidOperation.DiskCategoryUnsupported	The current category of the disk does not support this operation.	The disk type does not support the current operation.
400	AccountForbidden.CreateOrder	Order cannot be created due to abnormal account.	The current account is not allowed to create orders.
400	InvalidBootMode.Malformed	The specified parameter BootMode is invalid. Valid options are BIOS, UEFI, and UEFI-Preferred.	The specified parameter BootMode is invalid. Valid options are BIOS, UEFI, and UEFI-Preferred.
400	InvalidDetectionStrategy.Malformed	The specified value for parameter DetectionStrategy is not supported. Please refer to the documentation for accepted values.	The specified DetectionStrategy parameter value is not supported. Refer to the documentation for acceptable values.
400	InvalidParameter.SecureBootSupport	The specified parameter SecureBootOptions.SecureBootSupport is not valid.	The specified parameter SecureBootOptions.SecureBootSupport is not valid.
500	InternalError	The process of creating snapshot has failed due to some unknown error.	The snapshot cannot be created.
403	IncorrectDiskStatus.NeverAttached	The specified disk has never been attached to instance.
403	InvalidSnapshotId.NotReady	The 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.
403	InvalidSnapshot.TooOld	This 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.
403	OperationDenied	The specified snapshot is not allowed to create image.	The specified snapshot cannot be used to create images.
403	QuotaExceed.Image	The Image Quota exceeds.
403	InvalidParamter.Conflict	The specified same token is trying to make requests with different parameters.	The same token is used to make requests that contain different parameters.
403	InvalidAccountStatus.NotEnoughBalance	Your account does not have enough balance.
403	InvalidAccountStatus.SnapshotServiceUnavailable	Snapshot service has not been opened yet.	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.	You are not authorized to create an image based on 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 device is in an invalid state. Restart the instance and try again.
403	OperationDenied.InvalidSnapshotCategory	%s	This type of snapshot does not support the operation.
403	QuotaExceed.Snapshot	The snapshot quota exceeds.
403	IncorrectDiskStatus.Transferring	The 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.
403	IncorrectDiskStatus	The current disk status does not support this operation.
403	InvalidSystemSnapshot.Missing	%s
403	IncorrectDiskStatus.CreatingSnapshot	A previous snapshot creation is in process.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The CMK needs to be added ECS tag.	An ECS tag must be added to the CMK.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK needs to be enabled.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	The ECS service is not authorized to access your KMS key. Please grant the ECS service permission to use the key and try again.
403	QuotaExceed.Tags	%s	The number of specified tags exceeds the upper limit. %s is a variable. An error message is dynamically returned based on call conditions.
403	InvalidSnapshotCategory.NotSupportImageCreation	The specified snapshot category does not support create image.
403	TooManySnapshot.Unfinished	There are too many snapshots being created, please wait for them to be created done.
403	HibernationConfigured.InstanceOperationForbidden	The 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.
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.	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.
403	QuotaExceed.ConcurrentSnapshotQuota	The 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.
403	InvalidOperation.SnapshotStorageLocationUnsupported	Snapshots with storage location in CloudBox do not support the current operation.	The snapshot of the storage location in the CloudBox does not support the current operation.
403	AccountEnterpriseStatusInvalid	Your enterprise registration is marked as revoked/deregistered in the National Enterprise Credit Information Publicity System. Account transaction features (purchase/renewal/recharge) are disabled. Please update real-name certification via Account Center. Restrictions will auto-remove after verification.	The registration status of your enterprise has been canceled (or revoked) in the national enterprise credit information publicity system, and your account will not be able to carry out transaction operations such as new purchase, renewal and recharge of products. Please change the real name authentication through the account center as soon as possible. After the change is completed, Aliyun will automatically lift the purchase restriction.
403	InvalidOperation.DefaultFreeSnapshotNotSupport	The specified default free snapshot cannot be used for this operation. Please select another snapshot and try again.
403	InvalidBootMode.SecureBootUnsupported	Secure Boot requires UEFI or UEFI-Preferred boot mode. Please check the BootMode and try again.	Secure Boot requires UEFI or UEFI-Preferred boot mode. Please check the startup mode and try again.
404	InvalidSnapshotId.NotFound	The specified SnapshotId does not exist.
404	InvalidInstanceId.NotFound	The specified instance %s does not exist.	The specified instance does not exist.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The specified resource group does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.