Use Packer to create a custom image from an ECS instance - Elastic Compute Service

Packer is a lightweight open source tool that can be used to create images. Packer runs on mainstream operating systems, such as Windows, Linux, and macOS, and can create virtual machine images for multiple platforms in a paralleled and efficient manner. This topic describes how to install Packer on an Elastic Compute Service (ECS) instance, define a Packer template, and use Packer to create a custom image.

Prerequisites

You have an AccessKey pair, which consists of an AccessKey ID and an AccessKey secret. For more information, see Obtain an AccessKey pair.

Note

To prevent leaks of the AccessKey pair of your Alibaba Cloud account, we recommend that you create a Resource Access Management (RAM) user and use the credentials of the RAM user to create an AccessKey pair. For information about how to create a RAM user, see Create a RAM user.
An AccessKey secret for a RAM user is displayed only when you create the AccessKey pair for the RAM user. You cannot query the AccessKey secret after the AccessKey pair is created. Record and keep your AccessKey secret confidential.

Background information

Packer consists of various components, such as Builders, Provisioners, and Post-Processors. Packer uses templates in the Hashicorp Configuration Language (HCL) or JSON format to simplify the creation of custom images. It transforms the manual, ad-hoc image creation process into manageable configuration as code, lowering the barrier for migrating applications to the cloud. For more information about Packer, see the official Packer documentation.

Procedure

Step 1: Install Packer

Connect to a Linux instance.
For more information, see Connect to a Linux instance by using a username and password.
Change to the /usr/local/bin directory:
```
cd /usr/local/bin
```
Note
The /usr/local/bin directory is in the system's PATH. You can install Packer in this directory or any other directory that is already in the PATH.
Download the Packer installation package.
Alternatively, visit the Install Packer page to download the package for your instance's OS and architecture. This example uses packer_1.8.5_linux_amd64.zip.
```
wget https://releases.hashicorp.com/packer/1.8.5/packer_1.8.5_linux_amd64.zip
```
Unzip the Packer installation package:
```
unzip packer_1.8.5_linux_amd64.zip
```
Check the Packer version to verify the installation.
```
packer -v
```
- If the command returns a Packer version number, Packer is installed.
- If the command returns a command not found message, Packer is not installed correctly. Ensure the directory where Packer is located is in your system's PATH.

Step 2: Define a Packer template

To create a custom image with Packer, create a template file in HCL or JSON format. In this template, you must specify the Builders and Provisioners for creating the custom image. Packer provides a variety of provisioner types to configure the image's content. This topic uses the Shell provisioner as an example to define a Packer template.

Import your AccessKey ID.
```
export ALICLOUD_ACCESS_KEY=<AccessKey ID>
```
Replace <AccessKey ID> with your actual AccessKey ID. To find the AccessKey ID of a RAM user, see View the information about AccessKey pairs of a RAM user.
Import your AccessKey secret.
```
export ALICLOUD_SECRET_KEY=<AccessKey Secret>
```
Replace <AccessKey Secret> with your actual AccessKey Secret. The AccessKey Secret of a RAM user is displayed only when it is created and cannot be retrieved later. For more information, see Obtain an AccessKey pair.
Create a file named alicloud.
Note
You can use either of the following file formats to create the alicloud file. If you create an HCL file, ensure you use the HCL examples and commands in the subsequent steps.
HCL file
```
vi alicloud.pkr.hcl
```
JSON file
```
vi alicloud.json
```

Press the I key to enter Insert mode. Copy one of the following templates into the alicloud file and modify the parameters as needed.

HCL file

variable "access_key" {
  type    = string
  default = "${env("ALICLOUD_ACCESS_KEY")}"
}

variable "secret_key" {
  type    = string
  default = "${env("ALICLOUD_SECRET_KEY")}"
}

source "alicloud-ecs" "autogenerated_1" {
  associate_public_ip_address = true
  image_name                  = "packer_basic"
  instance_type               = "ecs.g6.large"
  internet_charge_type        = "PayByTraffic"
  io_optimized                = true
  region                      = "cn-qingdao"
  skip_image_validation       = true
  source_image                = "aliyun_3_x64_20G_alibase_20220907.vhd"
  ssh_username                = "root"
}

build {
  sources = ["source.alicloud-ecs.autogenerated_1"]
  provisioner "shell" {
    inline = ["sleep 30", "yum install redis.x86_64 -y"]
  }
}

JSON file

{
     "variables": {
       "access_key": "{{env `ALICLOUD_ACCESS_KEY`}}",
       "secret_key": "{{env `ALICLOUD_SECRET_KEY`}}"
     },
     "builders": [{
       "type":"alicloud-ecs",
       "region":"cn-qingdao",
       "image_name":"packer_basic",
       "source_image":"aliyun_3_x64_20G_alibase_20220907.vhd",
       "associate_public_ip_address":true,
       "ssh_username":"root",
       "instance_type":"ecs.g6.large",
       "internet_charge_type":"PayByTraffic",
       "io_optimized":true,
       "skip_image_validation":true
     }],
     "provisioners": [{
       "type": "shell",
       "inline": [
         "sleep 30",
         "yum install redis.x86_64 -y"
       ]
     }]
   }

The following table describes the parameters that are supported in a Packer template. For more information, see the official Packer documentation.

Parameter	Type	Required	Description
`region`	string	Yes	The region in which the temporary ECS instance that is used to create the custom image resides. Example: `cn-qingdao`.
`image_name`	string	Yes	The name of the custom image. Example: `packer_basic`.
`instance_type`	string	Yes	The instance type of the temporary ECS instance that is used to create the custom image. Example: `ecs.g6.large`. After the custom image is created, the temporary ECS instance is automatically released. Note When you use Packer to create a custom image, the CreateInstance operation is called to create a temporary ECS instance. This instance contains the operating system and software required for the image creation. This pay-as-you-go instance incurs fees.
`ssh_username`	string	Yes	The username that is used to connect to the temporary ECS instance over SSH.
`internet_charge_type`	string	No	The billing method for network usage of the temporary ECS instance that is used to create the custom image. Valid values: PayByBandwidth: pay-by-bandwidth. PayByTraffic: pay-by-traffic.
`source_image`	string	You must specify one of the parameters.	The ID of the base image that is used to create the temporary ECS instance. You can obtain the ID of the base image from the public image list in the ECS console or by calling the DescribeImages operation. Important When you configure this parameter, ensure that the selected image type is compatible with the specified instance type. For example, an Arm image (whose image ID contains `_arm64_`) must be used with an Arm-based instance type. Otherwise, the image build will fail.
`image_family`	string	You must specify one of the parameters.	The name of the image family. Packer uses the latest available image from this family to create the instance. Note The name must be 2 to 128 characters in length. The name cannot start with a digit, a special character, http://, or https://. The name can contain letters, digits, periods (.), underscores (_), hyphens (-), and colons (:).
`target_image_family`	string	No	The image family of the custom image to be created. Note The name must be 2 to 128 characters in length. The name cannot start with a digit, a special character, http://, or https://. The name can contain letters, digits, periods (.), underscores (_), hyphens (-), and colons (:).
`ssh_private_ip`	boolean	You must specify one of the parameters.	Specifies whether to connect to the instance over a private SSH connection. Default value: false. Valid values: false: An IP address is assigned for connection over the internet. true: An elastic IP address (EIP) or public IP address is not assigned. The instance is connected over its private IP address. Note To use a private connection, the machine on which Packer is running and the machine created by Packer must be in the same network environment, which means they must be in the same vSwitch.
`associate_public_ip_address`	boolean		Specifies whether to assign a public IP address to the temporary ECS instance.
`eip_id`	string		The ID of the EIP that is associated with the temporary ECS instance.
`skip_image_validation`	boolean	No	Specifies whether to skip image check. Default value: false.
`system_disk_mapping`	object	No	The system disk configurations. Example: `"system_disk_mapping": { "disk_name": "sysdisk", "disk_category": "cloud_essd", "disk_size": 40 }` For more information, see the Cloud disk configurations section of this topic.
`image_disk_mappings`	list	No	The data disk configurations in the custom image. Example: `"image_disk_mappings": { "disk_name": "datadisk", "disk_snapshot_id": "s-bp1xxxxxx", "disk_device": "dev/xvdb" }` For more information, see the Cloud disk configurations section of this topic.
`image_ignore_data_disks`	boolean	No	Specifies whether the created image includes data disk snapshots. Default value: false. Valid values: false: The created image includes data disk. true: The created image is based only on the system disk and does not include data disks.
`profile`	string	No	The configuration file for executing Packer. If this parameter is specified, configurations are preferentially obtained from this file.
`ram_role_name`	string	No	The name of the RAM role. This is used to obtain a temporary AccessKey for the local RAM role to execute the Packer template. Note This parameter applies only when Packer is executed on an ECS instance that has a RAM role attached.
`ram_role_arn`	string	No	The Alibaba Cloud Resource Name (ARN) of the RAM role. Used with `ram_session_name` to allow Account A to assume the role of Account B to create an image.
`ram_session_name`	string	No	The name of the RAM role session. Used with `ram_role_arn` to allow Account A to assume the role of Account B to create an image.
`ecs_ram_role_name`	string	No	The name of the instance RAM role attached to the temporary ECS instance. You can call the ListRoles operation provided by RAM to query the list of available instance RAM roles.
`ssh_keypair_name`	string	No	The name of the SSH key pair used to connect to the temporary ECS instance.
`ssh_private_key_file`	string	No	The private key file path of the SSH key pair used to connect to the temporary ECS instance.
`custom_endpoint_ecs`	string	No	The custom endpoint of the temporary ECS instance.
`security_group_id`	string	No	The ID of the security group in which to assign the temporary ECS instance.
`security_group_name`	string	No	The name of the security group in which to assign the temporary ECS instance. If you do not specify a security group ID, Packer creates a security group that uses the specified name.
`vpc_id`	string	No	The ID of the virtual private cloud (VPC) in which to create the temporary ECS instance.
`vpc_name`	string	No	The name of the VPC in which to create the temporary ECS instance. If you do not specify the `vpc_id` parameter, Packer creates a VPC that uses the specified name.
`vswitch_id`	string	No	The ID of the vSwitch to which to connect the temporary ECS instance.
`vswitch_name`	string	No	The name of the vSwitch to which to connect the temporary ECS instance. If you do not specify the `vswitch_id` parameter, Packer creates a vSwitch that uses the specified name.
`user_data`	string	No	The user data of the instance. The data must be Base64-encoded, and the raw data cannot exceed 32 KB in size. For more information about the limits, format, and execution frequency of user data, see Customize initialization configurations for an instance. Note To protect sensitive data like passwords and private keys during transmission, encrypt them before Base64 encoding, and then decrypt the data inside the instance.
`user_data_file`	string	No	The user data file of the temporary ECS instance.
`boot_mode`	string	No	The boot mode of the custom image. Valid values: BIOS, UEFI, and UEFI-Preferred.
`wait_snapshot_ready_timeout`	Integer	No	The snapshot timeout period. Default value: 3600. Unit: seconds.
`instance_name`	string	No	The name of the temporary ECS instance. The default value is the `InstanceId` value of the instance. Note The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-).
`image_force_delete`	boolean	No	Specifies whether to delete an existing image that has the same name as the custom image that you want to create. Default value: false. Valid values: true: deletes the existing image that has the same name as the custom image that you want to create and then creates the custom image. false: does not delete the existing image that has the same name as the custom image that you want to create. In this case, image creation fails.
`image_force_delete_snapshots`	boolean	No	Specifies whether to delete the snapshots associated with an existing image that has the same name as the custom image that you want to create. Default value: false. Valid values: true: deletes the existing image that has the same name as the custom image that you want to create and the snapshots associated with the existing image, and then creates the custom image. false: does not delete the existing image that has the same name as the custom image that you want to create or the snapshots associated with the existing image. In this case, image creation fails.
`image_version`	string	No	The version of the custom image.
`resource_group_id`	string	No	The ID of the resource group to which to assign the custom image.
`force_stop_instance`	boolean	No	Specifies whether to force stop the temporary ECS instance. Default value: false.
`disable_stop_instance`	boolean	No	By default, after Packer runs the provisioner, Packer stops the temporary ECS instance and then creates a custom image from the instance. However, the instance must be in the Running state in specific scenarios, such as when you run Sysprep on a Windows instance. Default value: false.
`run_tags`	object	No	The tags of the custom image. Example: `{"key":"value"}`.
`image_description`	string	No	The description of the custom image.
`image_share_account`	[]string	No	The users to which to share the custom image. Example: `["123456"]`.
`image_copy_regions`	[]string	No	The regions to which you want to copy the custom image. Example: `["cn-beijing"]`.
`provisioners`	string	No	The type of provisioner that is used to create the custom image. Valid values: File PowerShell Shell Local Shell Windows Shell For more information, see Provisioners.

Cloud disk configurations

Parameter	Type	Required	Description
`disk_name`	string	No	The name of the cloud disk. Note The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-).
`disk_category`	string	No	The category of the cloud disk. Valid values: cloud_efficiency: ultra disk cloud_ssd: standard SSD cloud_essd: Enterprise SSD (ESSD) cloud: basic disk
`disk_size`	int	No	The size of the cloud disk. Unit: GiB. The value of this parameter must be at least 20 and greater than or equal to the image size. Default value: 40 or the size of the image, whichever is greater.
`disk_description`	string	No	The description of the cloud disk. This parameter is left empty by default. Note The description must be 2 to 256 characters in length and cannot start with `http://` or `https://`.
`disk_snapshot_id`	string	No	The ID of the snapshot that you want to use to create the data disk.
`disk_delete_with_instance`	boolean	No	Specifies whether to release the data disk when the associated instance is released. Valid values: true false Default value: true.
`disk_device`	string	No	The mount point of the data disk.
`disk_encrypted`	boolean	No	Specifies whether to encrypt the data disk. Valid values: true false Default value: false.

Press Esc, type :wq, and then press Enter to save the file and exit.

Step 3: Use Packer to create a custom image

Follow these steps to build a custom image from the Packer template file.

Create a custom image.

HCL file

packer build alicloud.pkr.hcl

The following output shows that an image with the ID m-m5e3f0gu2dxs4z0s**** was created in the China (Qingdao) region.

alicloud-ecs.autogenerated_1: output will be in this color.

==> alicloud-ecs.autogenerated_1: Prevalidating source region and copied regions...
==> alicloud-ecs.autogenerated_1: Prevalidating image name...
    alicloud-ecs.autogenerated_1: Found image ID: aliyun_3_x64_20G_alibase_20220907.vhd
==> alicloud-ecs.autogenerated_1: Creating temporary keypair: packer_64bf3d40-2fe7-8251-276d-df59a0bb****
---------------------------
==> alicloud-ecs.autogenerated_1: Provisioning with shell script: /tmp/packer-shell3356722207
    alicloud-ecs.autogenerated_1: Last metadata expiration check: 0:00:11 ago on Tue 25 Jul 2023 11:12:18 AM CST.
---------------------------
    alicloud-ecs.autogenerated_1: Complete!
==> alicloud-ecs.autogenerated_1: Stopping instance: i-m5e87pt498pr8zv0****
==> alicloud-ecs.autogenerated_1: Waiting instance stopped: i-m5e87pt498pr8zv0****
==> alicloud-ecs.autogenerated_1: Creating image: packer_basic
    alicloud-ecs.autogenerated_1: Detach keypair packer_64bf3d40-2fe7-8251-276d-df59a0bb**** from instance: i-m5e87pt498pr8zv0****
==> alicloud-ecs.autogenerated_1: Cleaning up 'EIP'
==> alicloud-ecs.autogenerated_1: Cleaning up 'instance'
==> alicloud-ecs.autogenerated_1: Cleaning up 'security group'
==> alicloud-ecs.autogenerated_1: Cleaning up 'vSwitch'
==> alicloud-ecs.autogenerated_1: Cleaning up 'VPC'
==> alicloud-ecs.autogenerated_1: Deleting temporary keypair...
Build 'alicloud-ecs.autogenerated_1' finished after 4 minutes 32 seconds.

==> Wait completed after 4 minutes 32 seconds

==> Builds finished. The artifacts of successful builds are:
--> alicloud-ecs.autogenerated_1: Alicloud images were created:

cn-qingdao: m-m5e3f0gu2dxs4z0s****

JSON file

packer build alicloud.json

The following output shows that an image with the ID m-m5e3f0gu2dxs4z0s**** was created in the China (Qingdao) region.

alicloud-ecs output will be in this color.

==> alicloud-ecs: Prevalidating image name...
    alicloud-ecs: Found image ID: aliyun_3_x64_20G_alibase_20220907.vhd
==> alicloud-ecs: Creating temporary keypair: packer_6345090e-ec1f-8ea0-348c-f85ba047****
==> alicloud-ecs: Creating vpc
---------------------------
==> alicloud-ecs: Provisioning with shell script: /tmp/packer-shell090019677
    alicloud-ecs: Last metadata expiration check: 0:00:15 ago on Tue 11 Oct 2022 02:12:51 PM CST.
---------------------------
    alicloud-ecs: Complete!
==> alicloud-ecs: Deleting image snapshots.
==> alicloud-ecs: Creating image: packer_basic
    alicloud-ecs: Detach keypair packer_6345090e-ec1f-8ea0-348c-f85ba047**** from instance: i-m5e7it5p4dpwetfr****
==> alicloud-ecs: Cleaning up 'EIP'
==> alicloud-ecs: Cleaning up 'instance'
==> alicloud-ecs: Cleaning up 'security group'
==> alicloud-ecs: Cleaning up 'vSwitch'
==> alicloud-ecs: Cleaning up 'VPC'
==> alicloud-ecs: Deleting temporary keypair...
Build 'alicloud-ecs' finished.

==> Builds finished. The artifacts of successful builds are:
--> alicloud-ecs: Alicloud images were created:

cn-qingdao: m-m5e3f0gu2dxs4z0s****

Verify the created custom image.
1. Log on to the ECS console.
2. In the left-side navigation pane, choose Instances & Images > Images.
3. In the top navigation bar, select the region specified in your template file, such as China (Qingdao).
4. On the Custom Images tab, find the image named packer_basic.