Push image metadata to the HCP Packer registry
The HCP Packer registry aligns the workflows of image factories and image deployments, allowing operations and development teams to work together to create, manage, and consume images from a centralized source. It helps downstream users use the preferred versions of machine images, manage dependencies in Packer build pipelines, and seamlessly track build artifacts across multiple regions and cloud providers.
In this tutorial, you will use Packer to build an AWS Amazon Machine Image (AMI) and push the image's metadata to the HCP Packer registry.
Prerequisites
This tutorial assumes that you are familiar with the standard Packer workflows. If you are new to Packer, complete the Get Started tutorials first.
To follow along with this tutorial, you will need:
- Packer 1.7.10 installed locally
- An HCP account
- An AWS account with credentials set as local environment variables. These credentials must 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.
Create HCP Packer registry
Go to the HashiCorp Cloud Platform portal. After logging in, you will find Packer under "Services" in the left navigation menu.
You must enable the HCP Packer registry before Packer can publish build metadata to it. Click the Create a registry button after clicking on the Packer link under "Services" in the left navigation. This only needs to be done once.
Create HCP service principal and set to environment variable
In HCP Packer, go to Access control (IAM) in the left navigation menu, then select the Service principals tab.
Create a service principal named packer
with the Contributor role.
Once you create the service principal, click the service principal name to view its details. From the detail page, click + Generate key to create a client ID and secret.
Copy and save the client ID and secret; you will not be able to retrieve the secret later. You will use these credentials in the next step.
Once you generate the keys for the service principal, set the client ID and secret as environment variables so that Packer can authenticate with HCP.
In your terminal, set an environment variable for the client ID.
Then, set an environment variable for your client secret.
Clone the example repository
In your terminal, clone the tutorial repository. It contains Packer template files to build an Ubuntu image and push its metadata to the HCP Packer registry. 16
Navigate to the cloned repository.
Review Packer template
Open ubuntu-focal.pkr.hcl
to review the template.
This Packer template uses the Packer Amazon plugin v1.0.2
or later.
There are two source
blocks to build Ubuntu 20.04 AMIs, one for each of the us-east-2
and us-west-1
regions. This enables Packer to run your builds in parallel.
The hcp_packer_registry
block lets you customize the metadata that Packer sends to HCP Packer registry. The block in this example defines the image bucket's name (learn-packer-ubuntu
), description, bucket labels and build labels.
Build the Packer image
Now that you have a template file configured for HCP Packer, you are ready to build the image and push its metadata to the registry.
First, initialize your Packer template.
Now, format the Packer template.
Finally, build your image. Packer displays color-coded output for both builds. You can tell which build source an output line is associated with by the line's color or prefix.
Visit the AWS us-east-2
AMI Dashboard and us-west-1
AMI Dashboard to verify that Packer has built your images.
Explore your image bucket
Visit the HCP Packer dashboard to review the image metadata that Packer uploaded to the HCP Packer registry. The HCP Packer registry only stores the image metadata, not the image itself.
The main HCP Packer dashboard displays a list of image buckets, the top-level category in the Packer registry. Each image bucket maps to a Packer template. Notice the image bucket's ID (learn-packer-ubuntu
) corresponds to the bucket_name
argument defined in your Packer template's build.hcp_packer_registry
block.
Select the learn-packer-ubuntu
bucket to find details about the image.
Here, you will find information about the bucket such as the description and labels. These are the values defined in your Packer template file's build.hcp_packer_registry
block.
Explore image iterations
Click on Iterations in the left navigation menu.
Every time Packer builds a template, it creates an immutable record of the build called an image iteration. An iteration may have multiple machine images associated with it, depending on how many sources and destination regions your configuration defines.
Packer gives each iteration a fingerprint using a randomly generated Unique Lexicographical Identifier (ULID) or the value set in the HCP_PACKER_BUILD_FINGERPRINT
environment variable.
Click on the latest iteration.
Each iteration has an author to track who made the changes, and at least one build that maps to the source configured in the Packer template. Each build has an immutable set of labels based on the Packer template (build_labels
) at the time of build.
Click on us-east-2
to view the image ID and creation time associated with that build.
Next steps
In this tutorial, you used Packer to build AMIs and push the images' metadata to the HCP Packer registry. In the process, you learned more about the hcp_packer_registry
block and HCP Packer buckets and iterations.
For more information on topics covered in this tutorial, check out the following resources:
- Read more about storing image metadata in the HCP Packer documentation
- Visit the HCP Packer Glossary for additional descriptions of the terms covered in this tutorial
- Learn more about the
hcp_packer_registry
template block