An image template lets you specify a source image, add image components, and configure cross-region and cross-account image distribution to customize image content. After you create an image template, the system generates an image building task based on the template. The system also automatically detects and fixes common image issues and tests the usability of the generated image. This topic describes how to create an image template and run an image building task in the ECS console.
Prerequisites
When you first create an image component or an image template, the system automatically creates the AliyunServiceRoleForECSImageBuilder service-linked role, which authorizes Image Builder to access related cloud resources. If you use a RAM user, you must grant the RAM user permission to manage the service-linked role for Image Builder. An Alibaba Cloud account has these permissions by default. For more information, see Manage the service-linked role for Image Builder.
Step 1: Create an image template
Go to ECS console - Image Builder.
In the top navigation bar, select the region and resource group of the resource that you want to manage.
-
On the Image Builder page, on the Image Templates tab, click Create Image Template.
NoteIf this is the first time you are using Image Builder, you are redirected to the Image Builder welcome page. Click Create Image Template.
-
Configure the image template parameters and then click OK.
The following table describes the parameters.
-
Basic Information
Parameter
Required
Description
Template Name
Yes
The name of the image template.
Description
No
The description of the image template.
Tag
No
The tags of the image template. You can use tags to manage resources in a unified manner. For more information, see Tags.
-
Configure Source Image
Parameter
Required
Description
Source Image Type/Source Image
Yes
Set this parameter to Images or Image Family.
NoteYou can use only a public image, custom image, shared image, or image family as the source image. Alibaba Cloud Marketplace images and community images are not supported.
Images or Select an image family
Yes
Select the source image. The options vary based on the value that you select for Source Image Type.
-
If you set Source Image Type to Image, you can select Custom Images, Public Images, or Share an image from the first drop-down list and then select an image ID from the second drop-down list.
-
If you set Source Image Type 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 quickly create an image template.
Note-
We recommend that you use system components to create image templates because system components help ensure that created images are stable and reliable.
-
You can add image components to quickly create image templates only in the ECS console. This feature is not supported by the API.
Perform Image Repair
No
You can enable image check and repair. Before an image building task runs, the system automatically checks for and fixes common issues in the image being built, and installs required components for cloud images, such as Cloud Assistant. The following check and repair items are supported:
-
Linux system
-
GUESTOS.CloudInit
-
GUESTOS.Dhcp
-
GUESTOS.Virtio
-
GUESTOS.OnlineResizeFS
-
GUESTOS.Grub
-
GUESTOS.Fstab
-
-
Windows system
-
GUESTOS.Virtio
-
GUESTOS.Update
-
GUESTOS.Hotfix
-
GUESTOS.Server
-
NoteThe check and repair items may increase as the check and repair capabilities are improved. For more information about each item, see Check and fix a custom image.
Default value: Image check and repair is enabled.
NoteIf you disable this feature, the system only checks the image and does not repair it.
Perform Image Test
No
You can enable image testing. After an image building task is complete, the system automatically uses the specified components to test the new image. This ensures that the image works as expected before production use.
ImportantThe test process creates a new intermediate instance for testing. The intermediate instance is a pay-as-you-go ECS instance and is subject to charges. For more information, see Pay-as-you-go.
Default value: Image testing is enabled.
Verify Template
Yes
Select an image component of the Test type.
-
-
Configure Intermediate Instance
ImportantWhen you build an image by using an image template, the image building process creates multiple intermediate instances. Intermediate instances are pay-as-you-go ECS instances and are subject to charges. For more information, see Pay-as-you-go.
Parameter
Required
Description
vSwitch
No
Specify an available vSwitch in the current region.
Default value: The system creates a temporary VPC and vSwitch. Make sure that you have sufficient resource quotas in the region.
Instance Type
No
The instance type of the intermediate instance.
Default value: The system automatically selects an instance type based on the principle of the fewest vCPUs and the smallest memory size, subject to inventory. For example, ecs.g6.large is selected by default. If the ecs.g6.large instance type is out of stock, ecs.g6.xlarge is selected.
The system disk size.
No
The system disk size of the intermediate instance. Valid values: 20 to 500. Unit: GiB.
Default value: 40 GiB.
Public Bandwidth (Mbit/s)
No
If your image building content contains commands that require Internet access, such as download commands, you must specify a value for the public bandwidth. Otherwise, the image building task fails.
Default value: 0. This value indicates that no Internet access is provided.
Release if Image Building Fails
No
Specify whether to retain intermediate instances.
NoteIf you choose to retain the intermediate instances, you are continuously charged for the instances. If you no longer need the intermediate instances, manually release them. For more information, see Release an instance.
Default value: Intermediate instances are released.
-
Configure Image Distribution
Parameter
Required
Description
Destination Image Name
No
The name prefix for the built image. The system automatically generates the complete image name by combining the prefix and the image building task ID (ExecutionId) in the format
Custom name prefix_Image building task ID.Default value:
Image building task ID.Current Region
No
By default, the region where the template resides is displayed.
Destination Region
No
If you want to copy the built image to multiple regions, specify distribution regions. The built image is distributed to the specified regions. You can specify from 0 to 20 regions.
Default value: The template's region.
Sharee UID
No
If you want to share the built image with other Alibaba Cloud accounts, specify their user IDs (UIDs). The image is then shared with the specified accounts in the same region. You can specify from 0 to 20 UIDs.
Default value: None.
Execute Immediately
No
Specify whether to immediately run the image building task. If you do not run the task immediately, you can run it manually later. For more information, see Step 2: Run a build task.
Default value: The task runs immediately after the template is created.
-
-
After the template is created, you can view its details.
Click the image template ID to go to the template details page and view the following information:
-
On the Building History tab, view the execution history of image building tasks.
-
On the Build Template tab, view the build content of the image template.
-
On the Test Template tab, view the content used to test the image.
-
Step 2: Run a build task
When you create an image template, you can choose to run the task immediately. To run a task manually at a later time, follow the steps in this section.
Usage notes
Before you proceed, note the following:
-
For the same image template, only one image building task can run at a time.
-
Canceling tasks does not affect other image building tasks.
Procedure
Go to ECS console - Image Builder.
In the top navigation bar, select the region and resource group of the resource that you want to manage.
-
On the Image Builder page, on the Image Templates tab, find the image template for which you want to run an image building task, and then click Run in the Actions column.
Note-
To cancel a running task, click the image template ID. On the Building History tab, find the task and click Cancel in the Actions column.
-
The build time varies depending on the services being deployed and the commands to be run. Please wait for the build to complete.
-
After the image building task is successfully run, the status of the task changes to Successful, and an image ID is generated. You can click the image ID to view image details.
-
If the task status is Failed, view the detailed error message in the Execution Result column to diagnose and resolve the issue.
-
Related documents
-
You can also use API operations to perform the following tasks:
-
After you run an image building task based on the customizations defined in an image template, you can perform the following operations:
-
View the built custom image in the destination region.
-
Create an ECS instance from the new image or replace the operating system of an ECS instance. For more information, see Create an ECS instance by using a custom image or replace the system disk.
-