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

Define source images, components, and cross-region distribution in an image template, then run the build task to produce a validated custom image.

Prerequisites

The first time you create image components or templates, the system creates the service-linked role AliyunServiceRoleForECSImageBuilder, which grants Image Builder access to required Alibaba Cloud resources. If you use a RAM user, grant it permissions to use Image Builder. Alibaba Cloud accounts are automatically granted these permissions. See Manage service-linked role.

Step 1: Create an image template

Go to ECS Console - Image Builder.
In the upper-left corner of the page, select a region and resource group.
On the Image Builder tab of the Image Templates page, click Create Image Template.

Note
The first time you access Image Builder, click Image Builder on the Create Image Template 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. See Tags.

Configure Source Image

Parameter

Required

Description

Source Image Type

Yes

Select Image or Image Family.

Note

Only public images, custom images, shared images, and image families are supported as source images. Marketplace images and community images are not supported.

Image or Image Family

Yes

Specify the source image. The options depend on the Source Image Type value.

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

Configure Template Content

Parameter	Required	Description
Template Content	No	Add image components to the build template to create the image template. Note System image components produce stable and reliable images. We recommend using system image components to create image templates. Image components are available only in the ECS console. API operations do not support image components for creating templates.
Perform Image Repair	No	Enable image repair to automatically check for and fix common image issues and install required components, such as Cloud Assistant, before the build task runs. Supported check items: Linux operating system: GUESTOS.CloudInit GUESTOS.Dhcp GUESTOS.Virtio GUESTOS.OnlineResizeFS GUESTOS.Grub GUESTOS.Fstab Windows operating system: GUESTOS.Virtio GUESTOS.Update GUESTOS.Hotfix GUESTOS.Server Note Check items may increase as capabilities improve. See Overview of image check. Enabled by default. Note If disabled, the system performs image checks but does not repair images.
Perform Image Test	No	Enable image testing. After the build completes, the system automatically tests the new image with the specified components to verify it runs as expected. Important During testing, intermediate pay-as-you-go instances are created and billed. See Pay-as-you-go. Enabled by default.
Verify Template	Yes	Select Test-type image components for the image test template.

Configure Intermediate Instance

Important

Image building creates multiple intermediate pay-as-you-go instances. See Pay-as-you-go.

Parameter	Required	Description
vSwitch	No	Select a vSwitch in the current region. If not specified, the system creates a temporary VPC and vSwitch. Ensure your region has sufficient resource quotas.
Instance Type	No	Select an instance type for the intermediate instances. If not specified, the instance type with the fewest vCPUs and memory is automatically selected based on availability. For example, ecs.g6.large is selected first; if unavailable, ecs.g6.xlarge is used.
System Disk Size	No	The system disk size for each intermediate instance. Unit: GiB. Valid values: 20 to 500. Default value: 40.
Public Bandwidth (Mbps)	No	If your template content includes commands that require Internet access, set the public bandwidth to a non-zero value. Otherwise, the build task fails. Default value: 0 (no Internet access for intermediate instances).
Release if Image Building Fails	No	Specifies whether to release intermediate instances after the build task fails. Note If you select No to retain the intermediate instances, you continue to be charged after the build task fails. Release unneeded instances promptly. See Release an instance. Default value: Yes.

Configure Image Distribution

Parameter	Required	Description
Destination Image Name	No	A name prefix for the created image. The system appends the image building task ID (ExecutionId) to form the full name in the `<Custom name prefix>_<ID of the image building task>` format. Default value: `the ID of the image building task`.
Current Region	No	Specify distribution regions to copy the image to multiple regions. You can specify up to 20 regions. Default value: the region in which the image template resides.
Destination Region	No	Specify Alibaba Cloud account UIDs to share the created image with. The image is shared in the same region. You can specify up to 20 UIDs. Empty by default.
Execute Immediately	No	Specifies whether to immediately run an image building task. If not enabled, you can manually run the task after the template is created. See the Step 2: Execute an image building task section. Enabled by default.

(Optional) View the image template details.

Click the image template ID to view its details.
- On the Execute Immediately tab, view the historical execution details.
- On the Building History tab, view the build template content.
- On the Build Template tab, view the test template content.

Step 2: Execute an image building task

If you did not turn on Execute Immediately when creating the template, manually run the image building task as follows.

Considerations

Note the following before running an image building task:

Only one image building task can run at a time per image template.
Canceling a task does not affect other ongoing image building tasks.

Procedure

Go to ECS Console - Image Builder.
In the upper-left corner of the page, select a region and resource group.
On the Test Template tab of the Image Builder page, find the target image template and click Image Templates in the Actions column.
Note
- To cancel an ongoing task, click the image template ID, find the task on the null tab, and click Building History in the Actions column.
- Image creation time varies based on deployed services and build commands.
- After the task completes, Cancel appears in the Status column and the image ID is shown. Click the image ID to view details.
- If the task is in the Success state, check the Failed column for error details to troubleshoot issues.

References

Related API operations:
- CreateImagePipeline: creates an image template.
- StartImagePipelineExecution: runs an image building task.
- DescribeImagePipelines: queries image templates.
- DescribeImagePipelineExecutions: queries image building task details.
- CancelImagePipelineExecution: cancels an image building task.
After you create an image with a template, you can:
- View the custom image in each distribution region.
- Use the image to create ECS instances or replace the OS (system disk) of existing instances.