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 theRunning
orStopped
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
Authorization information
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
RegionId | string | Yes | 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 |
SnapshotId | string | No | The ID of the snapshot that is used to create the custom image. | s-bp17441ohwkdca0**** |
InstanceId | string | No | The instance ID. | i-bp1g6zv0ce8oghu7**** |
ImageName | string | No | 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 |
ImageFamily | string | No | 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 |
ImageVersion | string | No | 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 |
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 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:
Default value: Others Linux. | CentOS |
BootMode | string | No | The boot mode of the image. Valid values:
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 |
Architecture | string | No | 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:
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 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 |
ResourceGroupId | string | No | 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**** |
DiskDeviceMapping | object [] | No | The custom images. | |
SnapshotId | string | No | The ID of the snapshot that is used to create the custom image. | s-bp17441ohwkdca0**** |
Size | integer | No | 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.
| 2000 |
Device | string | No | The device name of disk N in the custom image. Valid values:
| /dev/vdb |
DiskType | string | No | 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 |
Tag | object [] | No | The tags. | |
key | string | No | 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 |
Key | string | No | 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 | KeyTest |
Value | string | No | 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 | ValueTest |
value | string | No | 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 |
DetectionStrategy | string | No | 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:
| Standard |
Response parameters
Examples
Sample success responses
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 has already bean used. | - |
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 | OperationDenied | The 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. |
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. | - |
400 | OperationDenied | Not support creating system image from an encrypted snapshot/disk. | An encrypted disk or snapshot cannot be used to create custom images. |
400 | InvalidParameter.AllEmpty | %s | The required parameters are not specified. |
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. | - |
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. |
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 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 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. | The custom image quota has been used up. |
403 | OperationDenied | The specified snapshot is not from system disk. | 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 same token is used to make requests that contain different parameters. |
403 | InvalidAccountStatus.NotEnoughBalance | Your account does not have enough balance. | Your account balance is insufficient. Add funds to your account and try again. |
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. | The maximum number of snapshots has been reached. Delete snapshots that are no longer needed and try again. |
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. | 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. |
403 | InvalidSystemSnapshot.Missing | %s | - |
403 | IncorrectDiskStatus.CreatingSnapshot | A previous snapshot creation is in process. | A previous snapshot creation task is in process. Please try again later. |
403 | InvalidParameter.KMSKeyId.CMKUnauthorized | The CMK needs to be added ECS tag. | - |
403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The 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. |
403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service have no right to access your KMS. | ECS is not authorized to access your KMS resources. |
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. |
404 | InvalidSnapshotId.NotFound | The specified SnapshotId does not exist. | The specified snapshot ID does not exist. |
404 | InvalidInstanceId.NotFound | The specified InstanceId 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. |
500 | InternalError | The process of creating snapshot has failed due to some unknown error. | The snapshot cannot be created. |
500 | InternalError | The 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 time | Summary of changes | Operation | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
2021-06-17 | The Error code has changed | see changesets | ||||||||||
|