Creates an image template. Image templates can be used to create images.
Operation description
Usage notes
You can use image templates to customize image content and create images across regions and accounts. Take note of the following items:
- You can create only custom image templates.
- You can configure only public, custom, or shared Linux images or image families as the source images when you create image templates.
- When you create an image from an image template, an intermediate Elastic Compute Service (ECS) instance that uses the pay-as-you-go billing method is created. You are charged for the instance. For more information, see Pay-as-you-go.
When you use the BuildContent
parameter to specify the content of the image template, take note of the following items:
- If the
BuildContent
value containsFROM
commands, theFROM
commands override the values ofBaseImageType
that specifies the type of the source image andBaseImage
that specifies the source image. - If the
BuildContent
value does not containFROM
commands, the system creates aFROM
command that consists of theBaseImageType
andBaseImage
values in the format of<BaseImageType>:<BaseImage>
and adds the command to the first line of the template content. - You can use Dockerfile to edit the content of the image template and then pass the edited content into the
BuildContent
parameter. The content cannot be greater than 16 KB in size and can contain up to 127 commands. For information about commands supported by image templates, see Commands supported by Image Builder.
You can use image components to create image templates in the ECS console, but cannot call API operations to use image components to create image templates. For more information, see What is Image Builder.
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action
policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resources
is used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
Operation | Access level | Resource type | Condition key | Associated operation |
---|---|---|---|---|
ecs:CreateImagePipeline | create | *ImagePipeline acs:ecs:{#regionId}:{#accountId}:imagepipeline/* |
|
|
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
Tag | array<object> | No | The tags to add to the template. | |
object | No | The tag to add to the template. | ||
Key | string | No | The key of tag N. Valid values of N: 1 to 20. You cannot specify empty strings as tag keys. The tag key must be 1 to 128 characters in length and cannot contain | TestKey |
Value | string | No | The value of tag N. Valid values of N: 1 to 20. The tag value can be an empty string. The tag value must be 0 to 128 characters in length. It cannot start with | TestValue |
RegionId | string | Yes | The ID of the region. You can call the DescribeRegions operation to query the most recent region list. | cn-hangzhou |
ResourceGroupId | string | No | The ID of the resource group. | rg-bp67acfmxazb4p**** |
AddAccount | array | No | The IDs of Alibaba Cloud accounts to which to share the image that will be created based on the image template. You can specify up to 20 account IDs. | |
long | No | The ID of Alibaba Cloud account N to which to share the image that will be created based on the image template. Valid values of N: 1 to 20. | 1234567890 | |
ToRegionId | array | No | The IDs of regions to which you want to distribute the image that is created based on the image template. You can specify up to 20 region IDs. If you do not specify this parameter, the image is created only in the current region. | |
string | No | The ID of region N to which to distribute the image that will be created based on the image template. 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 | |
BaseImageType | string | Yes | The type of the source image. Valid values:
| IMAGE |
BaseImage | string | Yes | The source image.
| m-bp67acfmxazb4p**** |
Name | string | No | The name of the launch template. The name must be 2 to 128 characters in length. The name must start with a letter and cannot start with Note
If you do not specify Name , the return value of ImagePipelineId is used.
| testImagePipeline |
Description | string | No | The description of the image template. The description must be 2 to 256 characters in length. It cannot start with | This is description. |
ImageName | string | No | The prefix of the image name. The prefix must be 2 to 64 characters in length. The prefix must start with a letter and cannot start with The system generates the final complete image name that consists of the specified prefix and the ID of the build task ( | testImageName |
VSwitchId | string | No | The ID of the vSwitch. If you do not specify this parameter, a new VPC and vSwitch are created. Make sure that the VPC quota in your account is sufficient. For more information, see Limits and quotas. | vsw-bp67acfmxazb4p**** |
InstanceType | string | No | The instance type. You can call the DescribeInstanceTypes to query instance types. If you do not configure this parameter, an instance type that provides the fewest vCPUs and memory resources is automatically selected. This configuration is subject to resource availability of instance types. For example, the ecs.g6.large instance type is automatically selected. If available ecs.g6.large resources are 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 size of the outbound public bandwidth for 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 when the image cannot be created. Valid values:
Default value: true. Note
If the intermediate instance cannot be started, the instance is released by default.
| true |
BuildContent | string | No | The content of the image template. The content cannot exceed 16 KB in size and can contain up to 127 commands. For more information about the commands that are supported, see the "Usage notes" section of this topic. | FROM IMAGE:m-bp67acfmxazb4p**** |
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 token 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 | Note
This parameter is in invitational preview and is not publicly available.
| null |
ImageFamily | string | No | Note
This parameter is in invitational preview and is not publicly available.
| null |
TestContent | string | No | Note
This parameter is in invitational preview and is not publicly available.
| null |
Response parameters
Examples
Sample success responses
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. |
403 | ImagePipeline.NotSupportWindowsInstance | Image pipeline does not support windows instance at this time. | - |
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. |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation |
---|---|---|
2024-10-10 | The Error code has changed. The request parameters of the API has changed | View Change Details |
2023-03-28 | The Error code has changed | View Change Details |