You can call this operation to create an image template. Image templates can be used to build images.

Description

You can customize image content based on image templates and build images in different regions and accounts. When you create an image template, take note of the following items:

  • This operation can only be used to create custom image templates.
  • You can configure only public images, custom images, shared images, or image families that run Linux operating system as the source images of the custom image templates to be created.
  • When you use an image template to build an image, you need to create an intermediate instance to help build the image. The intermediate instance is billed on a pay-as-you-go basis. For more information, see Pay-as-you-go.

For the BuildContent parameter that specifies contents of image templates, take note of the following items:

  • If BuildContent contains FROM commands, the values of BaseImageType that specifies types of source images and BaseImage that specifies source images are overridden by the FROM commands.
  • If BuildContent does not contain FROM commands, the system builds a FROM command that consists of BaseImageType and BaseImage and adds the command to the first line of the template content. The format of the command is <BaseImageType>:<BaseImage>.
  • You can use Dockerfile to edit contents of image templates and then pass the edited contents into the BuildContent parameter. The content size cannot be greater than 16 KB. The content can contain up to 127 commands. For information about commands supported by contents of image templates, see Description of commands supported by Image Builder.
Note 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 Overview.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateImagePipeline

The operation that you want to perform. Set the value to CreateImagePipeline.

BaseImage String Yes m-bp67acfmxazb4p****

The source image.

  • When you set BaseImageType to IMAGE, set the BaseImage parameter to the ID of a custom image.
  • When you set BaseImageType to IMAGE_FAMILY, set the BaseImage parameter to the name of an image family.
BaseImageType String Yes IMAGE

The type of the source image. Valid values:

  • IMAGE: custom images
  • IMAGE_FAMILY: image families
RegionId String Yes cn-hangzhou

The region ID of the image template. You can call the DescribeRegions operation to query the most recent region list.

Tag.N.Key String No TestKey

The key of tag N. 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. It cannot start with acs: or aliyun, or contain http:// or https://.

Tag.N.Value String No TestValue

The value of tag N. Valid values of N: 1 to 20. The tag value can be an empty string. It can be up to 128 characters in length and cannot start with acs: or contain http:// or https://.

ResourceGroupId String No rg-bp67acfmxazb4p****

The ID of the resource group to which to assign the image template.

Name String No testImagePipeline

The name of the image template. The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-). It must start with a letter and cannot start with http:// or https://.

Note If you do not specify the Name parameter, the return value of ImagePipelineId is used by default.
Description String No This is description.

The description of the image template. The description must be 2 to 256 characters in length and cannot start with http:// or https://.

ImageName String No testImageName

The name prefix of the image to be created. The prefix must be 2 to 64 characters in length and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-). It must start with a letter and cannot start with http:// or https://.

The system generates the final complete image name that consists of the prefix and the ID of the build task (ExecutionId) in the format of {ImageName}_{ExecutionId}.

VSwitchId String No vsw-bp67acfmxazb4p****

The ID of the vSwitch.

If you do not configure this parameter, a new VPC and vSwitch is created by default. Make sure that the VPC quota in your account is sufficient. For more information, see Limits.

InstanceType String No ecs.g6.large

The instance type of the instance. 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 selected by default. If available ecs.g6.large resources are insufficient, the ecs.g6.xlarge instance type is selected.

SystemDiskSize Integer No 40

The system disk size of the intermediate instance. Unit: GiB. Valid values: 20 to 500.

Default value: 40.

InternetMaxBandwidthOut Integer No 0

The size of the outbound public bandwidth for the intermediate instance. Unit: Mbit/s. Valid values: 0 to 100.

Default value: 0.

DeleteInstanceOnFailure Boolean No true

Specifies whether to release the intermediate instance if the image fails to be built. Valid values:

  • true: releases the intermediate instance if the image fails to be built.
  • false: does not release the intermediate instance if the image fails to be built.

Default value: true.

Note If the intermediate instance fails to be started, the instance is released by default.
BuildContent String No FROM IMAGE:m-bp67acfmxazb4p****

The content of the image template. The content size cannot be greater than 16 KB. The content can contain up to 127 commands. For more information about commands supported by image template, see the Description section in this topic.

AddAccount.N RepeatList No 1234567890

The ID of Alibaba Cloud account N to which to share the created image. Valid values of N: 1 to 20.

ToRegionId.N RepeatList No cn-hangzhou

The ID of region N to which to distribute the created image. Valid values of N: 1 to 20.

If you do not configure this parameter, the image is created only in the current region by default.

ClientToken String No 123e4567-e89b-12d3-a456-426655440000

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 make sure that it is unique among different requests. The ClientToken value can only contain ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

Response parameters

Parameter Type Example Description
ImagePipelineId String ip-2ze5tsl5bp6nf2b3****

The ID of the image template.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=CreateImagePipeline
&BaseImage=m-bp67acfmxazb4p****
&BaseImageType=IMAGE
&RegionId=cn-hangzhou
&Name=testImagePipeline
&BuildContent=FROM IMAGE:m-bp67acfmxazb4p****
&<Common request parameters>

Sample success responses

XML format

<CreateImagePipelineResponse>
      <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
      <ImagePipelineId>ip-2ze5tsl5bp6nf2b3****</ImagePipelineId>
</CreateImagePipelineResponse>

JSON format

{
    "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E", 
    "ImagePipelineId": "ip-2ze5tsl5bp6nf2b3****"
}

Error codes

HTTP status code Error code Error message Description
404 InvalidResourceGroup.NotFound The ResourceGroup provided does not exist in our records. The error message returned because the specified resource group does not exist.

For a list of error codes, visit the API Error Center.