Create an image template to build images.
Operation description
API
You can use an image template to customize image content and build images across regions and accounts. Before you create an image template, consider the following:
You can create only custom image templates.
You can use only public images, custom images, shared images, or image families as the source image.
When you build an image using an image template, the system creates one or more transit instances to assist with the build. You are charged for these pay-as-you-go ECS instances. For more information, see pay-as-you-go.
Consider the following about the build content specified in BuildContent:
The
FROMcommand is deprecated. The system ignores theFROMcommand inBuildContentand instead uses theBaseImageTypeandBaseImageparameters to select the source image.The content of an image template cannot exceed 16 KB. For details about supported commands, see Command reference for Image Builder.
For more information, see Image Builder overview.
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 to add to the image pipeline. |
|
|
object |
No |
A list of tags. |
||
| Key |
string |
No |
The key of tag N, where N is from 1 to 20. The tag key must be 1 to 128 characters in length. It cannot start with |
TestKey |
| Value |
string |
No |
The value of tag N, where N is from 1 to 20. The tag value can be empty or up to 128 characters long. It cannot start with |
TestValue |
| RegionId |
string |
Yes |
The ID of the region. You can call the DescribeRegions operation to query the latest list of Alibaba Cloud regions. |
cn-hangzhou |
| ResourceGroupId |
string |
No |
The ID of the resource group. |
rg-bp67acfmxazb4p**** |
| AddAccount |
array |
No |
The IDs of the Alibaba Cloud accounts to share the destination images with. You can specify up to 20 account IDs. |
1234567890 |
|
integer |
No |
The ID of an Alibaba Cloud account to share the destination images with. |
1234567890 |
|
| ToRegionId |
array |
No |
The IDs of destination regions for image distribution. You can specify up to 20 region IDs. If you do not specify this parameter, the images are created only in the current region. |
cn-hangzhou |
|
string |
No |
The ID of a destination region for image distribution. |
cn-hangzhou |
|
| RegionId |
string |
Yes |
The ID of the region. You can call the DescribeRegions operation to query the latest list of Alibaba Cloud regions. |
cn-hangzhou |
| ResourceGroupId |
string |
No |
The ID of the resource group. |
rg-bp67acfmxazb4p**** |
| BaseImageType |
string |
Yes |
The type of the base image. Valid values:
|
IMAGE |
| BaseImage |
string |
No |
The base image. The value of this parameter varies based on the value of
|
m-bp67acfmxazb4p**** |
| Name |
string |
No |
The name of the image pipeline. It must be 2 to 128 characters long, start with a letter or a Chinese character, and cannot start with Note
If you do not specify this parameter, the value of |
testImagePipeline |
| Description |
string |
No |
The description of the image pipeline template. 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 destination image name. Important
This parameter is deprecated. Use ImageOptions.ImageName instead.
|
testImageName |
| VSwitchId |
string |
No |
The ID of the VSwitch in the VPC that is used to launch the intermediate instance. If you do not specify this parameter, a new VPC and VSwitch are created. Ensure that you have a sufficient quota of VPC resources. For more information, see Usage limits. |
vsw-bp67acfmxazb4p**** |
| InstanceType |
string |
No |
The instance type of the intermediate instance. You can call the DescribeInstanceTypes operation to query instance types. If you do not specify this parameter, the system automatically selects an instance type with the minimum vCPUs and memory, subject to inventory. For example, |
ecs.g6.large |
| SystemDiskSize |
integer |
No |
The size of the system disk 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 |
Determines whether to release the intermediate instance when the image build fails. Valid values:
Default value: true. Note
If an intermediate instance cannot be started, it is not retained by default. |
true |
| BuildContent |
string |
No |
The content of the image build template. The content can be up to 16 KB in size. For more information about the supported commands, see Command reference for Image Builder. |
COMPONENT ic-bp12dvdzvr9k9***** COMPONENT acs:ecs:cn-hangzhou:18689161186*****:imagecomponent/ComponentName/1.*.* |
| ClientToken |
string |
No |
A client-generated, globally unique token to ensure the idempotence of the request. 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 image repair mode in the image template. Valid values:
Note
The repair items may change as the check and repair capabilities are improved. For more information about each repair item, see Image check overview. |
Standard |
ImageFamily
deprecated
|
string |
No |
The name of the destination image family. Important
This parameter is deprecated. Use ImageOptions.ImageFamily instead.
|
family |
| TestContent |
string |
No |
The content of the image test template. The content can be up to 16 KB in size. For more information about the supported commands, see Command reference for Image Builder. |
COMPONENT ic-bp12dvdzvr9k9***** COMPONENT acs:ecs:cn-hangzhou:18689161186*****:imagecomponent/ComponentName/1.*.* |
| ImportImageOptions |
object |
No |
The settings for importing an image. This parameter is required when |
|
| Architecture |
string |
No |
The architecture of the image to import. Valid values:
Default value: x86_64. |
x86_64 |
| OSType |
string |
No |
The type of the operating system. Valid values:
Default value: linux. |
linux |
| Platform |
string |
No |
The operating system distribution. Valid values:
Default value: Others Linux if OSType is set to Linux, or Other Windows if OSType is set to Windows. |
Aliyun |
| BootMode |
string |
No |
The boot mode of the image. Valid values:
Default value: BIOS. If Important
To prevent startup failures, ensure the boot mode is supported by the image. |
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 information about the disks of the custom image.
|
|
|
object |
No |
|||
| OSSBucket |
string |
No |
The OSS bucket that contains the image file. |
ecsimageos |
| OSSObject |
string |
No |
The name (key) of the image file that is stored in the OSS bucket. |
CentOS_5.4_32.raw |
| Format |
string |
No |
The format of the image. Valid values:
Default value: If left empty, the system automatically detects the image format. |
RAW |
| DiskImageSize |
integer |
No |
The size of the disk to create from the image file, in GiB. For the system disk, this value must be greater than or equal to the size of the image file. Valid values:
After you upload the base image file to an OSS bucket, you can view the size of the image file in the bucket. |
40 |
| Features |
object |
No |
The image feature attributes. |
|
| NvmeSupport |
string |
No |
Specifies whether the base image to be imported 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 destination image supports NVMe. Important
This parameter is deprecated. Use ImageOptions.ImageFeatures.NvmeSupport instead.
|
auto |
| AdvancedOptions |
object |
No |
The advanced settings. |
|
| RetainCloudAssistant |
boolean |
No |
Specifies whether to retain Cloud Assistant in the destination image. During the image building process, Cloud Assistant is automatically installed on the intermediate instance to run commands. You can select whether to retain Cloud Assistant after the process is complete. Valid values:
Default value: false. Note
This setting does not affect the Cloud Assistant client that is already installed in your image. |
true |
| ImageNameSuffix |
string |
No |
Specifies whether to disable the feature that automatically appends a suffix to the destination image name. Valid values:
|
disable |
| ImageOptions |
object |
No |
The properties of the destination image. |
|
| ImageName |
string |
No |
The prefix of the destination image name. The prefix must be 2 to 64 characters in length. It must start with a letter or a Chinese character. It cannot start with The complete image name is automatically generated by concatenating the prefix and the build task ID ( |
testImageName |
| ImageFamily |
string |
No |
The name of the destination image family. The name must be 2 to 128 characters long and start with a letter or a Chinese character. It cannot start with |
family |
| Description |
string |
No |
The description of the destination image. The description must be 2 to 256 characters in length and cannot start with |
This is description. |
| ImageFeatures |
object |
No |
The feature attributes of the destination image. |
|
| NvmeSupport |
string |
No |
Specifies whether the destination image supports NVMe. Valid values:
|
auto |
| ImageTags |
array<object> |
No |
The tags of the destination image. |
|
|
object |
No |
|||
| Key |
string |
No |
The key of the tag. The tag key must be 1 to 128 characters in length, cannot start with |
TestKey |
| Value |
string |
No |
The value of the tag. The tag value can be empty or up to 128 characters long. It cannot start with |
TestValue |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| ImagePipelineId |
string |
The ID of the image pipeline. |
ip-2ze5tsl5bp6nf2b3**** |
| RequestId |
string |
The ID of the request. |
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. | |
| 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. | |
| 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. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.