Creates an image template. Image templates can be used to build images.
Operation description
Operation description
You can use image templates to customize image content and build images cross-region and across accounts. Before you create an image template, take note of the following items:
You can create only custom image templates.
Only public images, custom images, shared images, or image families can be used as source images for building.
When you build an image by using an image template, multiple intermediate instances are created to assist in building the image. The intermediate instances are pay-as-you-go billing method ECS instances, and fees are incurred. For more information, see Pay-as-you-go.
Take note of the following items about the build template content BuildContent:
The
FROMcommand is deprecated. Regardless of whether theFROMcommand is set in theBuildContentparameter, the system selects the source image based on the source image typeBaseImageTypeand source imageBaseImage.The content size of an image template cannot exceed 16 KB. For details about supported commands, see Commands supported by Image Builder.
For more information, see Overview of Image Builder.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:CreateImagePipeline |
create |
*ImagePipeline
|
None |
|
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| Tag |
array<object> |
No |
The tags. |
|
|
object |
No |
The tags. |
||
| Key |
string |
No |
The tag key. 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 |
TestKey |
| Value |
string |
No |
The tag value. 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 |
TestValue |
| RegionId |
string |
Yes |
The region ID. You can call DescribeRegions to query the most recent region list. |
cn-hangzhou |
| ResourceGroupId |
string |
No |
The ID of the enterprise resource group. |
rg-bp67acfmxazb4p**** |
| AddAccount |
array |
No |
The Alibaba Cloud account ID to which to share the built image through image sharing. Valid values of N: 1 to 20. |
1234567890 |
|
integer |
No |
The Alibaba Cloud account ID to which to share the built image through image sharing. Valid values of N: 1 to 20. |
1234567890 |
|
| ToRegionId |
array |
No |
The regions to which to distribute the built image. Valid values of N: 1 to 20. If you do not specify this parameter, the image is created only in the current region. |
cn-hangzhou |
|
string |
No |
The regions to which to distribute the built image. Valid values of N: 1 to 20. If you do not specify this parameter, the image is created only in the current region. |
cn-hangzhou |
|
| RepairItem |
array |
No |
||
|
string |
No |
|||
| BaseImageType |
string |
Yes |
The type of the source image. Valid values:
|
IMAGE |
| BaseImage |
string |
No |
The source image.
|
m-bp67acfmxazb4p**** |
| Name |
string |
No |
The template name. The name must be 2 to 128 characters in length and must start with a letter or a Chinese character. The name cannot start with Note
If you do not specify |
testImagePipeline |
| Description |
string |
No |
The description. The description must be 2 to 256 characters in length and cannot start with |
This is description. |
ImageName
deprecated
|
string |
No |
The prefix of the name of the built image. Important
This parameter is deprecated. Use ImageOptions.ImageName instead.
|
testImageName |
| VSwitchId |
string |
No |
The ID of the vSwitch in the VPC. If you do not specify this parameter, a new VPC and vSwitch are created by default. Make sure that the VPC resource quota in your account is sufficient. For more information, see Limits. |
vsw-bp67acfmxazb4p**** |
| InstanceType |
string |
No |
The instance type. You can call DescribeInstanceTypes to query different instance types. If you do not specify this parameter, the instance type that has the minimum number of vCPUs and the smallest memory size is automatically selected. The selection is subject to the inventory of instance types. For example, the ecs.g6.large instance type is selected by default. If the inventory of the ecs.g6.large instance type is insufficient, the ecs.g6.xlarge instance type is selected. |
ecs.g6.large |
| SystemDiskSize |
integer |
No |
The system disk size of the intermediate instance. Unit: GiB. Valid values: 20 to 500. Default value: 40. |
40 |
| InternetMaxBandwidthOut |
integer |
No |
The outbound public bandwidth of the intermediate instance. Unit: Mbit/s. Valid values: 0 to 100. Default value: 0. |
0 |
| DeleteInstanceOnFailure |
boolean |
No |
Specifies whether to release the intermediate instance if the image fails to be built. Valid values:
Default value: true. Note
If the intermediate instance fails to start, the instance is not retained by default. |
true |
| BuildContent |
string |
No |
The content of the image build template. The content size cannot exceed 16 KB. For more information about supported commands, see Commands supported by Image Builder. |
COMPONENT ic-bp12dvdzvr9k9***** COMPONENT acs:ecs:cn-hangzhou:18689161186*****:imagecomponent/ComponentName/1.*.* |
| 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 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 |
| RepairMode |
string |
No |
The repair option in the image template. Valid values:
Note
As detection and repair capabilities continue to improve, the repair items may increase. For more information about the repair items, see Overview of image detection. |
Standard |
ImageFamily
deprecated
|
string |
No |
The image family of the built image. Important
This parameter is deprecated. Use ImageOptions.ImageFamily instead.
|
family |
| TestContent |
string |
No |
The content of the image test template. The content size cannot exceed 16 KB. For more information about supported commands, see Commands supported by Image Builder. |
COMPONENT ic-bp12dvdzvr9k9***** COMPONENT acs:ecs:cn-hangzhou:18689161186*****:imagecomponent/ComponentName/1.*.* |
| ImportImageOptions |
object |
No |
The properties and settings for importing an image. This parameter is required when |
|
| Architecture |
string |
No |
The system architecture of the system disk when a data disk snapshot is used as the system disk. Valid values:
Default value: x86_64. |
x86_64 |
| OSType |
string |
No |
The operating system type. Valid values:
Default value: linux. |
linux |
| Platform |
string |
No |
The operating system version. Valid values:
Default value: Others Linux if the operating system type is Linux. Otherwise, the default value is Other Windows. |
Aliyun |
| BootMode |
string |
No |
The boot mode of the image. Valid values:
Default value: BIOS. If Important
To prevent instances from failing to start due to an unsupported boot mode, make sure that you understand the boot modes supported by the image before you set this parameter. For more information about image boot modes, see Image boot modes. |
BIOS |
| LicenseType |
string |
No |
The license type used to activate the operating system after the image is imported. Valid values:
Default value: Auto. |
Auto |
| DiskDeviceMappings |
array<object> |
No |
The list of custom image information.
|
|
|
object |
No |
|||
| OSSBucket |
string |
No |
The OSS bucket in which the image file is stored. |
ecsimageos |
| OSSObject |
string |
No |
The file name (key) of the image file stored in the OSS bucket after the image is uploaded. |
CentOS_5.4_32.raw |
| Format |
string |
No |
The image format. Valid values:
Default value: none. Alibaba Cloud automatically detects the image format, and the detected format prevails. |
RAW |
| DiskImageSize |
integer |
No |
The size of the custom image after the image is imported. The size consists of the system disk and data disks. Make sure that the system disk size is greater than or equal to the size of the imported image file. Valid values:
After you upload the source image file to OSS, you can view the size of the image file in the OSS bucket. |
40 |
| Features |
object |
No |
The image feature properties. |
|
| NvmeSupport |
string |
No |
Specifies whether the imported original image supports NVMe. Valid values:
Default value: unsupported. |
supported |
| ImdsSupport |
string |
No |
||
| RetainImportedImage |
boolean |
No |
Note
This parameter is in invitational preview. |
false |
| RetentionStrategy |
string |
No |
||
| ImageName |
string |
No |
||
| Description |
string |
No |
||
| RoleName |
string |
No |
||
| ImportImageTags |
array<object> |
No |
||
|
object |
No |
|||
| Key |
string |
No |
||
| Value |
string |
No |
||
NvmeSupport
deprecated
|
string |
No |
Specifies whether the built image supports NVMe. Important
This parameter is deprecated. Use ImageOptions.ImageFeatures.NvmeSupport instead.
|
auto |
| AdvancedOptions |
object |
No |
The advanced configuration. |
|
| RetainCloudAssistant |
boolean |
No |
Specifies whether to retain Cloud Assistant. During the build process, the system automatically installs Cloud Assistant on the intermediate instance to run commands. You can choose whether to retain Cloud Assistant in the built image. Valid values:
Default value: false. Note
This setting does not affect Cloud Assistant that is already included in your image. |
true |
| ImageNameSuffix |
string |
No |
Specifies whether to disable the automatic suffix for the built image name. Valid values:
|
disable |
| ImageOptions |
object |
No |
The properties of the built image. |
|
| ImageName |
string |
No |
The prefix of the name of the built image. The name must be 2 to 64 characters in length and must start with a letter or a Chinese character. The name cannot start with The final complete image name is automatically generated by the system by concatenating the name prefix and the build task ID ( |
testImageName |
| ImageFamily |
string |
No |
The image family of the built image. The name must be 2 to 128 characters in length and must start with a letter or a Chinese character. The name cannot start with aliyun or acs:. The name cannot contain http:// or https://. The name can contain digits, colons (:), underscores (_), and hyphens (-). |
family |
| Description |
string |
No |
The description. The description must be 2 to 256 characters in length and cannot start with |
This is description. |
| ImageFeatures |
object |
No |
The image feature properties of the built image. |
|
| NvmeSupport |
string |
No |
Specifies whether the built image supports NVMe. Valid values:
|
auto |
| ImageTags |
array<object> |
No |
The tags of the built image. |
|
|
object |
No |
|||
| Key |
string |
No |
The tag key. 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 |
TestKey |
| Value |
string |
No |
The tag value. 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 |
TestValue |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| ImagePipelineId |
string |
The ID of the image template. |
ip-2ze5tsl5bp6nf2b3**** |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
Examples
Success response
JSON format
{
"ImagePipelineId": "ip-2ze5tsl5bp6nf2b3****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidSourceInstance.NotFound | The specified source instance is not found. | The specified source instance is not found. |
| 400 | InvalidName.Malformed | %s | |
| 400 | InvalidDescription.Malformed | %s | |
| 400 | InvalidImageName.Malformed | %s | |
| 400 | InvalidBaseImageType.NotSupportedValue | %s | |
| 400 | InvalidSystemDiskSize.NotSupportedValue | %s | |
| 400 | InvalidInternetMaxBandwidthOut.NotSupportedValue | %s | |
| 400 | InvalidAddAccountSize.ExceededMaxNumber | %s | |
| 400 | InvalidToRegionIdSize.ExceededMaxNumber | %s | |
| 400 | InvalidBuildContent.LengthExceeded | %s | |
| 400 | InvalidImageTemplateCommandSize.ExceededMaxNumber | %s | |
| 400 | DuplicatedCommand.FROM | %s | |
| 400 | InvalidCommandOrder.FROM | %s | |
| 400 | InvalidImageTemplateCommand.NotSupported | %s | |
| 400 | InvalidCommandContent.RUN | %s | |
| 400 | InvalidCommandContent.ENV | %s | |
| 400 | InvalidCommandContent.WORKDIR | %s | |
| 400 | InvalidCommandContent.COPY | %s | |
| 400 | InvalidCommandContent.USER | %s | |
| 400 | InvalidCommandContent.FROM | %s | |
| 400 | InvalidCommandContent.CMD | %s | |
| 400 | InvalidCommandContent.ENTRYPOINT | %s | |
| 400 | QuotaExceed.ImagePipeline | %s. | The image template quota of your account in this region is used up. |
| 400 | NoPermission | %s. | This operation is not allowed. Apply for the permissions required to perform the operation. |
| 400 | EmptyCommandContent.LABEL | %s. | If the LABEL command exists in the template, you must specify LABEL. |
| 400 | EmptyCommandContent.ENV | %s. | If the ENV command exists in the template, you must specify ENV. |
| 400 | EmptyCommandContent.ENTRYPOINT | %s. | If the ENTRYPOINT command exists in the template, you must specify ENTRYPOINT. |
| 400 | EmptyCommandContent.CMD | %s. | If the CMD command exists in the template, you must specify CMD. |
| 400 | EmptyCommandContent.COPY | %s. | If the COPY command exists in the template, you must specify COPY. |
| 400 | EmptyCommandContent.WORKDIR | %s. | If the WORKDIR command exists in the template, you must specify WORKDIR. |
| 400 | NotEmptyCommandContent.RESTART | %s. | If the RESTART command exists in the template, you must specify RESTART. |
| 400 | EmptyCommandContent.USER | %s. | If the USER command exists in the template, you must specify USER. |
| 400 | EmptyCommandContent.RUN | %s. | If the RUN command exists in the template, you must specify RUN. |
| 400 | InvalidImage.OsTypeUnsupported | The specified base image does not support image building. | The operating system of the specified base image does not support image building. |
| 400 | InvalidParameter.BuildContent | %s. | The build content is invalid. |
| 400 | InvalidParameter.TestContent | %s. | The test content is invalid. |
| 400 | InvalidImageComponent.NotSupported | %s. | The specified image component is not available. |
| 400 | InvalidParameterCombination | %s. | Invalid combination of parameters. |
| 400 | InvalidParameter.RepairMode | The specified parameter RepairMode is invalid. | The specified repair mode is invalid. |
| 400 | InvalidImageFamily.Malformed | The format of the specified image family is invalid. | The format of the specified image family is invalid. |
| 400 | InvalidImage.ImageOwnerAliasUnsupported | The specified base image does not support distributing. | The specified base image does not support distributing. |
| 400 | InvalidParameter.ImportImageOptionsArchitecture | The specified parameter ImportImageOptions.Architecture is invalid. The correct value should be in [%s]. | The specified parameter ImportImageOptionsArchitecture is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidParameter.ImportImageOptionsOSType | The specified parameter ImportImageOptions.OSType is invalid. The correct value should be in [%s]. | The specified parameter ImportImageOptions.OSType is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidParameter.ImportImageOptionsBootMode | The specified parameter ImportImageOptions.BootMode is invalid. The correct value should be in [%s]. | The specified parameter ImportImageOptions.BootMode is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidImportImageOptionsDiskDeviceMappings.LengthLimitExceeded | The length of the specified parameter ImportImageOptions.DiskDeviceMappings exceeds the limit(17). | The specified parameter ImportImageOptions.DiskDeviceMappings length exceeds the limit, the maximum length is 17. |
| 400 | InvalidParameter.ImportImageOptionsDiskDeviceMappingsOSSObject | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSObject is invalid. OSSObject supports up to 1023 characters, and cannot start with http:// or https://. | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSObject is invalid. OSSObject supports up to 1023 characters, and cannot start with "http://" or "https://". |
| 400 | InvalidParameter.ImportImageOptionsDiskDeviceMappingsOSSBucket | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSBucket is invalid. OSSBucket supports up to 63 characters, only lowercase letters, numbers, and dashes are allowed, and cannot start or end with a dash. | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSBucket is invalid. OSSBucket supports up to 63 characters, only lowercase letters, numbers, and dashes are allowed, and cannot start or end with a dash. |
| 400 | InvalidParameter.ImportImageOptionsPlatform | The specified parameter ImportImageOptions.Platform is invalid. The correct value should be in [%s]. | The specified parameter ImportImageOptions.Platform is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidParameter.ImportImageOptionsLicenseType | The specified parameter ImportImageOptions.LicenseType is invalid. The correct value should be in [%s]. | The specified parameter ImportImageOptions.LicenseType is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidParameter.ImportImageOptionsFeaturesNvmeSupport | The specified parameter ImportImageOptions.Features.NvmeSupport is invalid. The correct value should be in [%s]. | The specified parameter ImportImageOptions.Features.NvmeSupport is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidParameter.NvmeSupport | The specified parameter NvmeSupport is invalid. The correct value should be in [%s]. | The specified parameter NvmeSupport is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidParameter.ImportImageOptionsDiskDeviceMappingsFormat | The specified parameter ImportImageOptions.DiskDeviceMappings.Format is invalid. The correct value should be in [%s]. | The specified parameter ImportImageOptions.DiskDeviceMappings.Format is invalid. The correct value can refer to the error message or the document to fill in. |
| 400 | InvalidOperation.DiskImageSizeExceeded | The disk size exceeds the limit. Please check the specified parameter ImportImageOptions.DiskDeviceMappings.DiskImageSize and ImportImageOptions.DiskDeviceMappings.OSSObject. Ensure that each of them is between 1 and 2048 in size. | The disk size exceeds the limit. Please check the specified parameter ImportImageOptions.DiskDeviceMappings.DiskImageSize and ImportImageOptions.DiskDeviceMappings.OSSObject. Ensure that each of them is between 1 and 2048 in size. |
| 400 | InvalidImageOptions.Description | The specified parameter ImageOptions.Description is invalid. The length should be between 2 to 256 characters, and cannot start with http:// or https://. | The specified parameter ImageOptions.Description is invalid. The length should be between 2 to 256 characters, and cannot start with http:// or https://. |
| 400 | InvalidImageName.Duplicated | The specified image name is already in use in the target region. Please try a different one. | The specified image name is already in use in the target region. Please try another one. |
| 400 | InvalidImage.NotSupportRepair | The specified base image does not support repair. | The specified base image does not support repair. |
| 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. Tag keys cannot be empty or null, support up to 128 characters, cannot start with "aliyun" or "acs:", and cannot contain "http://" or "https://". | The specified Tag.N.Key is not valid. Tag keys cannot be empty or null, support up to 128 characters, cannot start with "aliyun" or "acs:", and cannot contain "http://" or "https://". |
| 400 | InvalidTagValue.Malformed | The specified Tag.N.Value is not valid. Tag values support up to 128 characters, and cannot contain "http://" or "https://". | The specified Tag.N.Value is not valid. Tag values support up to 128 characters, and cannot contain "http://" or "https://". |
| 400 | InvalidAdvancedOptions.ImageNameSuffix | The specified parameter AdvancedOptions.ImageNameSuffix is invalid. The correct value should be in [%s]. | The specified parameter AdvancedOptions.ImageNameSuffix is invalid. The correct enumeration value can be obtained by referring to the error message. |
| 400 | InvalidImportImageOptions.DockerOptionsImageMalformed | The specified parameter ImportImageOptions.DockerOptions.Image is invalid. The length should be between 1 to 512 characters. | The specified parameter ImportImageOptions.DockerOptions.Image is invalid. The length should be between 1 to 512 characters. |
| 400 | InvalidImportImageOptions.DockerOptionsImageSizeMalformed | The specified parameter ImportImageOptions.DockerOptions.ImageSize is invalid. The size should be between 1GB to 2048GB. | The specified parameter ImportImageOptions.DockerOptions.ImageSize is invalid. The size should be between 1GB to 2048GB. |
| 403 | ImagePipeline.NotSupportWindowsInstance | Image pipeline does not support windows instance at this time. | |
| 403 | InvalidOSSObject.NotAuthorized | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is not allowed to be accessed. | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is not allowed to be accessed. |
| 403 | InvalidOperation.NoPermissionCreateServiceLinkedRole | You are not authorized to create Service-linked role. The system will automatically create it when the API is called for the first time. Check your RAM policies, and ensure that you are using the correct credentials. | You are not authorized to create Service-linked role. The system will automatically create it when the API is called for the first time. Check your RAM policies, and ensure that you are using the correct credentials. |
| 403 | InvalidOSSObject.NeedRestore | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is an archived object and needs to be restored first. | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is an archived object and needs to be restored first. |
| 403 | InvalidOperation.NoRightAccessOSS | ECS service is not authorized to access your OSS. Check your RAM roles and policies, and ensure that ecs.aliyuncs.com is authorized to assume AliyunECSImageImportDefaultRole. | ECS service is not authorized to access your OSS. Check your RAM roles and policies, and ensure that "ecs.aliyuncs.com" is authorized to assume "AliyunECSImageImportDefaultRole". |
| 403 | InvalidOperation.OSSObjectIsImporting | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is importing. | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is importing. |
| 404 | InvalidImage.NotFound | %s | |
| 404 | InvalidResourceGroup.NotFound | The ResourceGroup provided does not exist in our records. | The specified resource group does not exist. |
| 404 | ImageComponent.NotFound | %s. | The specified image component ID is not found. |
| 404 | InvalidInstanceType.NotFound | The specified instance type does not exist. | The specified InstanceType parameter does not exist. |
| 404 | InvalidVSwitchId.NotFound | The specified VSwitchId does not exist. | The specified VSwitchId does not exist |
| 404 | InvalidRegionId.NotFound | %s | The specified region ID does not exist. |
| 404 | InvalidImportImageOptionsDiskDeviceMappingsOSSObject.NotFound | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is not found in this region. | The specified ImportImageOptions.DiskDeviceMappings.OSSObject is not found in the current region. |
| 404 | MissingParameter.RepairMode | The specified parameter RepairMode is missing. | The specified parameter RepairMode is missing. |
| 404 | MissingParameter.ImportImageOptions | The specified parameter ImportImageOptions is missing. | The specified parameter ImportImageOptions is missing. |
| 404 | MissingParameter.ImportImageOptionsDiskDeviceMappingsOSSObject | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSObject is missing. | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSObject is missing. |
| 404 | MissingParameter.ImportImageOptionsDiskDeviceMappingsOSSBucket | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSBucket is missing. | The specified parameter ImportImageOptions.DiskDeviceMappings.OSSBucket is missing. |
| 404 | MissingParameter.ImageOptionsDiskDeviceMappings | The specified parameter ImportImageOptions.DiskDeviceMappings is missing. | The specified parameter ImportImageOptions.DiskDeviceMappings is missing. |
| 404 | MissingImportImageOptions.DockerOptions | The specified parameter ImportImageOptions.DockerOptions is missing. | The specified parameter ImportImageOptions.DockerOptions is missing. |
| 404 | InvalidOssBucketName.NotFound | The specified parameter OssDeliveryConfig.BucketName does not exist. | The specified OSS bucket does not exist. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.