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

An AccessKey pair is created. The AccessKey pair 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 process of creating custom images. In addition, Packer standardizes and automates the image creation process and allows you to define images as code to facilitate cloud migration. 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.
Run the following command to go to the /usr/local/bin directory:
```
cd /usr/local/bin
```
Note
The /usr/local/bin directory is included in environment variables. You can install Packer in this directory or a different directory that is added to environment variables.
Run the following command to obtain the Packer installation package.
You can also go to the Install Packer page to obtain a Packer installation package that is suitable for the operating system and architecture of the Linux instance. In this example, the packer_1.8.5_linux_amd64.zip installation package is obtained.
```
wget https://releases.hashicorp.com/packer/1.8.5/packer_1.8.5_linux_amd64.zip
```
Run the following command to decompress the Packer installation package:
```
unzip packer_1.8.5_linux_amd64.zip
```
Run the following command to check whether Packer is installed and check the version of Packer:
```
packer -v
```
- If Packer is properly installed, a Packer version number is returned.
- If Packet is not installed, the command not found message is returned. Check whether the directory in which Packer resides is added to environment variables.

Step 2: Define a Packer template

To create a custom image by using Packer, create a template in the HCL or JSON format. In the template, specify a builder and a provisioner. For more information, see Builders and Provisioners. Packer provides various provisioners that you can use to create custom images. In this example, a Shell provisioner is used.

Run the following command to import your AccessKey ID:
```
export ALICLOUD_ACCESS_KEY=<AccessKey ID>
```
In the preceding command, replace <AccessKey ID> with your AccessKey ID. For information about how to query the AccessKey ID of a Resource Access Management (RAM) user, see View the information about AccessKey pairs of a RAM user.
Run the following command to import your AccessKey secret:
```
export ALICLOUD_SECRET_KEY=<AccessKey Secret>
```
In the preceding command, replace <AccessKey Secret> with your AccessKey secret. The AccessKey secret of 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. For more information, see Obtain an AccessKey pair.
Run the following command to create a file named alicloud.
Note
You can create the alicloud file in the HCL or JSON format. If you create the file in the HCL format, perform the subsequent operations that are suitable for a template in the HCL format.
HCL file
```
vi alicloud.pkr.hcl
```
JSON file
```
vi alicloud.json
```

Press the I key to enter Insert mode, copy the following sample Packer template content to the alicloud file, and then modify the parameters in the content based on your business requirements:

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 Packer creates the custom image, the CreateInstance operation is called to create a temporary ECS instance. The instance contains the operating system and software that are required to create the custom image. The temporary ECS instance is a pay-as-you-go instance. You are charged for the instance.
`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 Make sure that the base image that you select supports the instance type that you specify to create the temporary ECS instance. For example, if the base image is an Arm image whose ID contains _arm64_, you must specify an Arm-based instance type. Otherwise, the custom image cannot be created.
`image_family`	string	You must specify one of the parameters.	The image family name of the image that is used to create the temporary ECS instance. You can specify this parameter to obtain the latest available image from the specified image family to create the temporary ECS 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. 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 temporary ECS instance by using the private IP address of the instance over SSH. Default value: false. Valid values: false: assigns a public IP address to the instance and uses the public IP address to connect to the instance over SSH. true: does not associate an elastic IP address (EIP) with or assign a public IP address to the instance and uses the private IP address of the instance to connect to the instance over SSH. Note When Packer uses the private IP address of the temporary ECS instance to connect to the instance, the ECS instance on which Packer is run must connect to the same vSwitch as the temporary ECS instance.
`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 to include data disk snapshots in the custom image. Default value: false. Valid values: false: includes data disk snapshots in the custom image. true: does not include data disk snapshots in the custom image. In this case, the image is created based only on the system disk.
`profile`	string	No	The configuration file of Packer. If you specify this parameter, Packer preferentially obtains configurations from the specified configuration file.
`ram_role_name`	string	No	The name of the instance RAM role attached to the current ECS instance on which Packer is run. This parameter is used to obtain a temporary AccessKey pair to run the Packer template based on the instance RAM role attached to the current ECS instance. Note This parameter is suitable for scenarios in which Packer is run on ECS instances to which instance RAM roles are attached.
`ram_role_arn`	string	No	The Alibaba Cloud Resource Name (ARN) of the RAM role. This parameter is used in conjunction with the ram_session_name parameter to specify that Account A assumes the identity of Account B to create the custom image.
`ram_session_name`	string	No	The name of the RAM role. This parameter is used in conjunction with the ram_role_arn parameter to specify that Account A assumes the identity of Account B to create the custom 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 temporary ECS instance. You must specify Base64-encoded data. The instance user data cannot exceed 32 KB in size before Base64 encoding. For information about the limits, formats, and running frequencies of instance user data, see Customize initialization configurations for an instance. Note To ensure security, we recommend that you do not use plaintext to pass in confidential information, such as passwords or private keys, as part of instance user data. If you must pass in confidential information as part of instance user data, we recommend that you encrypt and encode the information in Base64 and then decode and decrypt the information in the same manner in 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 the Esc key, enter :wq, and then press the Enter key to save and close the alicloud file.

Step 3: Create a custom image by using Packer

To create a custom image by using the Packer template that you created, perform the following steps:

Run the following command to create a custom image.

HCL file

packer build alicloud.pkr.hcl

The following sample command output indicates that a custom image whose ID is m-m5e3f0gu2dxs4z0s**** is 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 sample command output indicates that a custom image whose ID is m-m5e3f0gu2dxs4z0s**** is 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****

View 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 upper-left corner of the top navigation bar, select the region that is specified in the alicloud file. Example: China (Qingdao).
4. On the Custom Images tab, view the custom image named packer_basic.