Build an image
With Packer installed, it is time to build your first image. In this tutorial, you will build a t2.micro Amazon EC2 AMI.
Note
This tutorial will provision resources that qualify under the AWS free-tier. If your account doesn't qualify under the AWS free-tier, we're not responsible for any charges that you may incur.
Write Packer template
A Packer template is a configuration file that defines the image you want to build and how to build it. Packer templates use the Hashicorp Configuration Language (HCL).
Create a new directory named packer_tutorial. This directory will contain your Packer template for this tutorial.
Navigate into the directory.
Create a file aws-ubuntu.pkr.hcl, add the following HCL block to it, and save the file.
This is a complete Packer template that you will use to build an AWS Ubuntu AMI in the us-west-2 region. In the following sections, you will review each block of this template in more detail.
Packer Block
The packer {} block contains Packer settings, including specifying a required Packer version.
In addition, you will find required_plugins block in the Packer block, which specifies all the plugins required by the template to build your image. Even though Packer is packaged into a single binary, it depends on plugins for much of its functionality. Some of these plugins, like the Amazon AMI Builder (AMI builder) which you will to use, are built, maintained, and distributed by HashiCorp — but anyone can write and use plugins.
Each plugin block contains a version and source attribute. Packer will use these attributes to download the appropriate plugin(s).
- The
sourceattribute is only necessary when requiring a plugin outside the HashiCorp domain. You can find the full list of HashiCorp and community maintained builders plugins in the Packer Builders documentation page. - The version attribute is optional, but we recommend using it to constrain the plugin version so that Packer does not install a version of the plugin that does not work with your template. If you do not specify a plugin version, Packer will automatically download the most recent version during initialization.
In the example template above, Packer will use the Packer Amazon AMI builder plugin that is greater than or equal to version 1.2.8.
Source block
The source block configures a specific builder plugin, which is then invoked by a build block. Source blocks use builders and communicators to define what kind of virtualization to use, how to launch the image you want to provision, and how to connect to it. Builders and communicators are bundled together and configured side-by-side in a source block. A source can be reused across multiple builds, and you can use multiple sources in a single build. A builder plugin is a component of Packer that is responsible for creating a machine and turning that machine into an image.
A source block has two important labels: a builder type and a name. These two labels together will allow us to uniquely reference sources later on when we define build runs.
In the example template, the builder type is amazon-ebs and the name is ubuntu.
Each builder has its own unique set of configuration attributes. The amazon-ebs builder launches the source AMI, runs provisioners within this instance, then repackages it into an EBS-backed AMI.
In the example template, the amazon-ebs builder configuration launches a t2.micro AMI in the us-west-2 region using an ubuntu-jammy AMI as the base image, then creates an image named learn-packer-linux-aws from that instance. The builder will create all the temporary resources necessary (for example, keypairs, security group rules, etc..) to temporarily access the instance while the image is being created.
This example template also uses the SSH communicator. By specifying the ssh_username attribute, Packer is able to SSH into EC2 instance using a temporary keypair and security group to provision your instances. The next tutorial walks you through modify your AMI using provisioners.
The Build Block
The build block defines what Packer should do with the EC2 instance after it launches.
In the example template, the build block references the AMI defined by the source block above (source.amazon-ebs.ubuntu).
Tip
In later tutorials, you will add the provision block (define additional provisioning steps) and post-process block (define what do to with the build artifacts) to the build block.
Authenticate to AWS
Before you can build the AMI, you need to provide your AWS credentials to
Packer. These credentials have permissions to create, modify and delete EC2
instances. Refer to the
documentation
to find the full list IAM permissions required to run the amazon-ebs builder.
To allow Packer to access your IAM user credentials, set your AWS access key ID as an environment variable.
Now set your secret key.
Tip
If you don't have access to IAM user credentials, use another authentication method described in the Packer documentation.
Initialize Packer configuration
Initialize your Packer configuration.
Packer will download the plugin you've defined above. In this case, Packer will download the Packer Amazon plugin that is greater than or equal to version 1.2.8.
You can run packer init as many times as you'd like. If you already have the plugins you need, Packer will exit without an output.
Packer has now downloaded and installed the Amazon plugin. It is ready to build the AMI!
Format and validate your Packer template
We recommend using consistent formatting in all of your template files. The packer fmt command updates templates in the current directory for readability and consistency.
Format your template. Packer will print out the names of the files it modified, if any. In this case, your template file was already formatted correctly, so Packer won't return any file names.
You can also make sure your configuration is syntactically valid and internally consistent by using the packer validate command.
Validate your template. If Packer detects any invalid configuration, Packer will print out the file name, the error type and line number of the invalid configuration. The example configuration provided above is valid, so Packer will return nothing.
Build Packer image
Build the image with the packer build command. Packer will print output similar to what is shown below.
Visit the AWS AMI page to verify that Packer successfully built your AMI.
Congratulations — you built your first image using Packer!
Managing the Image
Packer only builds images. It does not attempt to manage them in any way. After they're built, it is up to you to launch or destroy them as you see fit.
After running the above example, your AWS account now has an AMI associated with it. AMIs are stored in S3 by Amazon so you may be charged.
You can remove the AMI by first deregistering it on the AWS AMI management page. Next, delete the associated snapshot on the AWS snapshot management page.
Next steps
In this tutorial, you launched an EC2 instance and used it to create an AMI. Although you essentially repackaged an existing AMI, you should now have a general idea of how Packer works, what templates are and how to validate and build templates into machine images. Now that you have created your first Packer image, continue to the next tutorial to install and configure software into your image with provisioners.
Refer to the following resources for additional details on the concepts covered in this tutorial:
- Read more about the Packer Amazon AMI builder plugin.
- Learn more about the
packer initandpacker buildcommands. - For more information about Packer-specific HCL blocks, refer to the Packer HCL documentation page.