Docs

Elastic Compute Service

Creating custom images

Creating custom images by using Packer

Packer is a lightweight open-source tool that can efficiently and concurrently create images compatible with multiple cloud platforms by using a single template file. You can run Packer on mainstream operating systems, such as Windows, Linux, and macOS.

In the example in this topic, Packer is used to create a Linux image. For information about how to use Packer to create a Windows image, see Packer official documentation.

Prerequisites

The snapshot feature is enabled.

The server running Packer can access the Internet.

The sum of your VolcanoEngine account balance (cash balance) and coupon values is greater than or equal to CNY 100. For information about how to check the sum, see Account description. If the sum is insufficient, refer to Recharge guide to top up your account.

Usage notes

When you use Packer to create a custom image, pay-as-you-go cloud resources such as temporary ECS instances and EIPs are automatically created. After the custom image is created, the cloud resources are automatically deleted. You are charged for the cloud resources that are automatically created when you create a custom image. For more information, see Pay-as-you-go billing method.

Terms

Term	Description
Volcengine Image Builder(Builder)	The custom image generator of the platform, which is used to specify the Provisioners required by Packer and the configuration information used during the custom image creation process.
Provisioner	The configurator, which is used to specify the software and patches to be installed in the custom image when Packer is used to create the custom image. In this topic, Shell Provisioners are used as an example. For more information about Provisioners, see Provisioners.

Procedure

Step 1: Install Packer

Execute the following command to download Packer.

In this topic, 1.8.6_linux_amd64 is used as an example. For more Packer versions, see Packer official documentation.

wget https://releases.hashicorp.com/packer/1.8.6/packer_1.8.6_linux_amd64.zip

Execute the following command to decompress the Packer package.

Replace packer_1.8.6_linux_amd64.zip with the actual Packer file.

unzip packer_1.8.6_linux_amd64.zip

Execute the following command to move Packer to the directory for environment variables. This allows you to quickly use Packer from any directory.

mv packer /usr/local/bin/

Execute the following command to verify whether Packer is installed.

packer -v

If the following output is displayed, Packer is installed as expected.

If command not found is displayed, Packer is not installed as expected.

Step 2: Configure a Packer template

Before you use Packer to create a custom image, you need to create and configure a template file. In the template file, you need to specify information, such as the temporary instance used during the process of creating a custom image, the target region, Builder, and Provisioners.

Log in to the instance running Packer, and then execute the following command to create a configuration file with the .pkr.hcl suffix.

tip

HCL and JSON formats are supported for template files. We recommend that you use the HCL format.

Replace <volc_config> with the name of the file to be created.

vim <volc_config>.pkr.hcl

Press the i key to enter the edit mode and copy and paste the following content.

packer {
required_plugins {
volcengine = {
version = ">= 0.0.1"
source = "github.com/volcengine/volcengine"
}
}
}

source "volcengine-ecs" "foo" {
target_image_name = "packer_test"
source_image_id = "image-yc41yungxxxxxx"
region = "cn-beijing"
instance_type = "ecs.g2a.large"
associate_public_ip_address = "true"
public_ip_band_width = "20"
public_ip_id = ""
system_disk_size = "50"
system_disk_type = "ESSD_PL0"
ssh_username = "root"
temporary_key_pair_name = "packer-key"
}

build {
sources = ["source.volcengine-ecs.foo"]
provisioner "shell" {
inline = ["sleep 30", "yum install mysql -y"]
}

}

Description of important parameters:

For the complete usage instructions for the HCL template used in this topic, see HCL templates.

Parameter	Description	Sample value
packer	The Packer behaviors, such as specifying all plugins required for the current template. Retain the plugin configuration for volcengine in this example. For more information, see packer.	-
source	The Builder startup information. You need to specify volcengine-ecs by using the first tag, which specifies that an image is created for a platform ECS instance. For information about how to use the source parameter, see source.	-
L region	The region where the image that you want to create resides. For more information, see Regions and availability zones.	cn-beijing
L target_image_name	The name of the image that you want to create.	packer_test
L source_image_id	The ID of the base image. Packer creates a custom image based on the base image. You can use any public image, custom image, or shared image in your platform account as a base image. You can obtain the base image ID in the Image console.	image-38deyjkaxxxxx
L instance_type	The type of the temporary instance used for image creation. For more information, see Instance type overview.	ecs.g2i.large
L system_disk_size	The size of the system volume in GiB.	50
L system_disk_type	The type of the system volume.	ESSD_PL0
L associate_public_ip_address	Specifies whether to associate an EIP with the temporary instance. Valid values: false (default): No true: Yes. Data is transmitted over the Internet. warning When you set this parameter to true, you can: Use an existing EIP. In this case, specify the ID of the EIP of the target platform by using the public_ip_id parameter. Use a temporary EIP. In this case, you do not need to specify the public_ip_id parameter. You can specify the upper limit for the bandwidth of the temporary EIP by using the public_ip_band_width parameter. The temporary EIP is automatically released after the image is created.	true
L public_ip_id	The ID of the existing EIP that you want to use.	eip-13frvze8oo8hs3xxxxxx
L public_ip_band_width	The upper limit for the bandwidth of the temporary EIP. Default upper limit: 1 Mbps Valid upper limit: 1 to 200 Mbps tip This parameter takes effect only when you set the associate_public_ip_address parameter to true and leave the public_ip_id parameter empty.	1
L temporary_key_pair_name	The name of the temporary key pair used to connect to the temporary instance. The system automatically creates the key pair and uses the key pair for the temporary instance. You can also specify the ssh_password parameter to connect to the temporary instance by using a password. For information about SSH connection parameters, see SSH communicator.	packer-key
L ssh_username	The username used to connect to the temporary instance over SSH. The value of this parameter is fixed to root for Linux. For more information, see SSH communicator.	root
build	The Builders and Provisioners that Packer starts. For more usage details, see build.	-

Execute the following command to initialize the template file.

packer init <volc_config>.pkr.hcl

tip

If you use a JSON file to configure the Packer template, you can execute the packer hcl2_upgrade xxx.json command to convert the JSON file to an HCL file. For more information, see Upgrading Packer JSON template to HCL2.

Replace <volc_config> with the actual file name.

Step 3: Create a custom image

After you create and initialize the Packer template, you can create a custom image.

Execute the following command to import the AccessKey ID of your platform account.

export VOLCENGINE_ACCESS_KEY=<AccessKey ID>

tip

Replace <AccessKey ID> with your actual AccessKey ID. For more information, see User guide.

Execute the following command to import the AccessKey secret of your platform account.

export VOLCENGINE_SECRET_KEY=<AccessKey Secret>

tip

Replace <AccessKey Secret> with your actual AccessKey secret. For more information, see User guide.

Execute the following command to create a custom image.

packer build volc_config.pkr.hcl

tip

Replace volc_config.pkr.hcl with the actual file name.

The following figure shows a sample output. In this example, a custom image containing MySQL is created.

View the result

In the top menu bar, select the region and project where the target custom image is located.

Select the "Custom Image" tab.

If the status of the target image is Available in the "State" column, the custom image is created.

You can also click the image name to go to the image details page, select the "Associative snapshot" tab, and view the IDs of the snapshots associated with the volumes in the image, the volume types, and the capacity of the volumes. For information about the snapshot feature, see Snapshot overview.

Last updated: 2026.06.18 17:49:50