Create an image template and execute an image building task - Elastic Compute Service

In an image template, you can specify the source image, add image components, and configure cross-region and cross-account image distribution to customize the image content. After an image template is created, the system generates an image building task based on the content configured in the image template. The system also automatically checks for and repairs common image issues and tests whether the image created based on the image template is available. This topic describes how to create an image template and execute an image building task in the Elastic Compute Service (ECS) console.

Step 1: Create an image template

Log on to the ECS console.
In the left-side navigation pane, choose Instances & Images > > Image Builder.
In the top navigation bar, select the region and resource group to which the resource belongs.
On the Image Templates tab of the Image Builder page, click Create Image Template.
Note
The first time you access Image Builder, click Create Image Template on the Image Builder welcome page.

On the page that appears, configure the parameters and click OK.

The following tables describe the parameters.

Basic Information

Parameter	Required	Description
Template Name	Yes	Specify a name for the image template.
Description	No	Specify a description for the image template.
Tag	No	Add tags to the image template. For information about tags, see Tags.

Configure Source Image

Parameter

Required

Description

Source Image Type

Yes

Select Images or Image Family.

Note

You can specify only a public image, a custom image, a shared image, or an image family as the source image. Alibaba Cloud Marketplace images and community images are not supported.

Images or Image Family

Yes

Specify the source image. This parameter varies based on the value of the Source Image Type parameter.

If you set the Source Image Type parameter to Images, select Custom Images, Public Images, or Shared Images from the first Image drop-down list and then select an image ID from the second Image drop-down list.
If you set the Source Image Type parameter to Image Family, select an existing image family.

Configure Template Content

Parameter	Required	Description
Template Content	No	Add image components to the image build template to quickly create the image template. Note Image templates that are created by using system image components provide stable and reliable images. We recommend that you use system image components to create image templates. You can use image components to create image templates in the ECS console. However, you cannot call API operations to use image components to create image templates.
Perform Image Repair	No	You can enable the image repair feature to allow the system to automatically check for and repair common image issues and install required components, such as Cloud Assistant, before an image building task is executed. The following check items are supported: Linux operating system: GUESTOS.CloudInit GUESTOS.Dhcp GUESTOS.Virtio GUESTOS.OnlineResizeFS GUESTOS.Grub GUESTOS.Fstab Windows operating system: GUESTOS.Virtio GUESTOS.Updat GUESTOS.Hotfix GUESTOS.Server Note As the check and repair capabilities continue to improve, the number of check items may increase. For more information about check items, see Overview of image check. By default, the image repair feature is enabled. Note If you disable the image repair feature, the system performs image checks but does not repair images.
Perform Image Test	No	You can enable the image test feature. After an image building task is completed, the system automatically uses the specified components to test the new image to ensure that the image runs as expected. Important During the test process, intermediate pay-as-you-go instances are created. You are charged for the instances. For more information, see Pay-as-you-go. By default, the image test feature is enabled.
Verify Template	Yes	Select image components of the Test type for the image test template.

Configure Intermediate Instance

Important

When you use an image template to create an image, multiple intermediate instances are created. You are charged for the intermediate instances on a pay-as-you-go basis. For more information, see Pay-as-you-go.

Parameter	Required	Description
vSwitch	No	Select a vSwitch that is available in the current region. If you do not select a vSwitch, the system creates a temporary virtual private cloud (VPC) and vSwitch. Make sure that the resource quotas in your region are sufficient.
Instance Type	No	Select an instance type for the intermediate instances. If you do not configure this parameter, the instance type that provides the fewest vCPUs and memory resources is automatically selected. This configuration is subject to the 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.
System Disk Size	No	Specify the size of the system disk for each intermediate instance. Unit: GiB. Valid values: 20 to 500. Default value: 40.
Public Bandwidth (Mbps)	No	If your image template content contains a command that requires access to the Internet, you must set the public bandwidth to a non-zero value. Otherwise, the image building task fails. By default, Public Bandwidth (Mbit/s) is set to 0, which specifies that the intermediate instances cannot access the Internet.
Release if Image Building Fails	No	Specify whether to release the intermediate instances after the image building task fails. Note If you select No to retain the intermediate instances, you continue to be charged for the instances after the image building task fails. If you no longer require the intermediate instances, manually release the instances at the earliest opportunity. For more information, see Release an instance. Default value: Yes.

Configure Image Distribution

Parameter	Required	Description
Destination Image Name	No	Specify a name prefix for the image created based on the image template. The system appends the ID of the image building task (ExecutionId) to the prefix to generate a full name for the image in the `<Custom name prefix>_<ID of the image building task>` format. Default value: `the ID of the image building task`.
Distribution Region	No	If you want to copy an image to multiple regions, you can specify the distribution regions. The image is distributed to the specified regions. You can specify up to 20 distribution regions. Default value: the region in which the image template resides.
Shared User ID	No	If you want to share the created image with other Alibaba Cloud accounts, specify the user IDs (UIDs) of the Alibaba Cloud accounts. The created image is shared with the specified Alibaba Cloud accounts in the same region. You can specify up to 20 UIDs. This parameter is left empty by default.
Execute Immediately	No	Specify whether to immediately execute an image building task. If you specify not to immediately execute an image building task, you can manually execute a task after the image template is created. For more information, see the Step 2: Execute an image building task section of this topic. By default, an image building task is immediately executed after the image template is created.

(Optional) After the image template is created, view the details of the created image template.
Click the ID of the image template to go to the template details page and view the details of the image template.
- On the Building History tab, view the historical execution details of the image building task.
- On the Build Template tab, view the content of the image build template.
- On the Test Template tab, view the content of the image test template.

Step 2: Execute an image building task

When you create an image template, you can turn on Execute Immediately to trigger an image building task immediately after the image template is created. If you want to manually execute an image building task to create a custom image after an image template is created, perform the steps in this section.

Considerations

Before you run an image building task based on an image template, take note of the following items:

Only one image building task can be run at a time based on an image template.
You can cancel an image building task multiple times. Canceling an image building task does not interfere with the execution of other ongoing image building tasks.

Procedure

Log on to the ECS console.
In the left-side navigation pane, choose Instances & Images > > Image Builder.
In the top navigation bar, select the region and resource group to which the resource belongs.
On the Image Templates tab of the Image Builder page, find the image template based on which you want to execute an image building task and click Execute in the Actions column.
Note
- You can cancel ongoing image building tasks. To cancel an ongoing image building task that is based on an image template, click the image template ID, find the image building task on the Building History tab, and then click Cancel in the Actions column.
- The amount of time required to create an image may vary based on the services deployed in the image and the commands run to create the image.
- After the image building task is completed, Success is displayed in the Status column and the ID of the image that is created based on the image template is displayed in the Image ID column. You can click the image ID to view the details of the image.
- If the image building task is in the Failed state, you can view the detailed error message in the Execution Result column to identify and troubleshoot the issue.

References

You can call the following API operations:
- CreateImagePipeline: creates an image template.
- StartImagePipelineExecution: executes an image building task by using an image template.
- DescribeImagePipelines: queries information about one or more image templates.
- DescribeImagePipelineExecutions: queries the details of an image building task.
- CancelImagePipelineExecution: cancels an image building task.
After you create an image by using an image template, you can perform the following operations:
- View the custom image that is created based on the image template in each distribution region.
- Use the image that is created based on the image template to create ECS instances or replace the operating systems of existing ECS instances based on your business requirements. For more information, see Use a custom image to create one or more instances or Replace the operating system (system disk) of an instance.