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.

$ export HCP_CLIENT_ID=

Then, set an environment variable for your client secret.

$ export HCP_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

$ git clone https://github.com/hashicorp/learn-hcp-packer-get-started

Navigate to the cloned repository.

$ cd learn-hcp-packer-get-started

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 {
  hcp_packer_registry {
    bucket_name = "learn-packer-ubuntu"
    description = <<EOT
Some nice description about the image being published to HCP Packer Registry.
    EOT
    bucket_labels = {
      "owner"          = "platform-team"
      "os"             = "Ubuntu",
      "ubuntu-version" = "Focal 20.04",
    }

    build_labels = {
      {/* "build-time"   = timestamp()
      "build-source" = basename(path.cwd) */}
    }
  }
  sources = [
    "source.amazon-ebs.basic-example-east",
    "source.amazon-ebs.basic-example-west"
  ]
}

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.

$ packer init .

Now, format the Packer template.

$ packer fmt .
ubuntu-focal.pkr.hcl

By default, Packer will take the HEAD Git SHA for the template file to create a build fingerprint (in this case, the HEAD of the repository you cloned). We recommend version controlling your Packer template file to avoid creating the fingerprint yourself.

If Packer does not detect a build fingerprint, you will not be able to build 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.

$ packer build ubuntu-focal.pkr.hcl
amazon-ebs.basic-example-east: output will be in this color.
amazon-ebs.basic-example-west: output will be in this color.
==> amazon-ebs.basic-example-west: Publishing build details for amazon-ebs.basic-example-west to the HCP Packer registry
==> amazon-ebs.basic-example-east: Publishing build details for amazon-ebs.basic-example-east to the HCP Packer registry
==> amazon-ebs.basic-example-west: Prevalidating any provided VPC information
==> amazon-ebs.basic-example-west: Prevalidating AMI Name: packer_AWS_1646370805_v1.0.0
==> amazon-ebs.basic-example-east: Prevalidating any provided VPC information
==> amazon-ebs.basic-example-east: Prevalidating AMI Name: packer_AWS_1646370805_v1.0.0
## ...
==> Wait completed after 3 minutes 7 seconds
==> Builds finished. The artifacts of successful builds are:
--> amazon-ebs.basic-example-west: AMIs were created:
us-west-1: ami-046aad37f0f871201
--> amazon-ebs.basic-example-west: Published metadata to HCP Packer registry packer/learn-packer-ubuntu/iterations/01FX9NHN7D3N3R5CA87MPNJ0RT
--> amazon-ebs.basic-example-east: AMIs were created:
us-east-2: ami-08fde52ca64d008af
--> amazon-ebs.basic-example-east: Published metadata to HCP Packer registry packer/learn-packer-ubuntu/iterations/01FX9NHN7D3N3R5CA87MPNJ0RT

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. Each iteration has a unique identifier that maps to the git SHA or the value set in HCP_PACKER_BUILD_FINGERPRINT.

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