»Packer Template Configuration

Hands On: Try the Push Image Metadata to the Registry tutorial.

You can configure both HCL2 and JSON Packer templates to push metadata to the HCP Packer registry However, we recommend that you use HCL2 templates because they let you codify how Packer interacts with the registry and customize your image metadata. We provide limited metadata support for JSON templates, and future HCP Packer features and enhancements will only support HCL2.

Note: HCP Packer errors if you try to push metadata to a deactivated or deleted registry. An administrator can manually deactivate or delete a registry, and HCP Packer automatically deactivates registries with billing issues. Contact HashiCorp Support with questions.

Requirements

You must perform the following steps before your Packer template can push metadata to the HCP Packer registry:

Download the appropriate Packer version featuring the HCP Packer registry integration: Packer v1.7.6 or later
Use HCP-capable plugins:
Set the HCP_CLIENT_ID and HCP_CLIENT_SECRET environment variables to a service principal key. Packer uses these values to authenticate with the HCP Packer registry and push your image metadata to a particular organization and project. If these credentials are incorrect or the associated service principal is expired, Packer fails with an error explaining why it could not successfully connect to the registry.
Set an appropriate build fingerprint if your template is not version controlled.

Build Fingerprint

Packer uses a unique identifier called a build fingerprint to determine if metadata for a template build on the registry is complete. A template build is considered complete when Packer finishes building all builds for all sources and pushing each image’s metadata to the registry. By default, Packer uses the HEAD Git SHA for the template file to create a fingerprint. If your template is not version controlled, you must create an environment variable named HCP_PACKER_BUILD_FINGERPRINT and set it to a unique value each time you call packer build. Packer will not build the template unless it detects a build fingerprint.

Image Metadata Overview

The HCP Packer registry uses the following resources to store image metadata for each build:

Image Bucket: This resource stores all of the metadata from a single Packer template. It contains iterations and builds.
Iteration: This resource contains an immutable record of each packer build inside of an image bucket. Each complete iteration contains at least one build, and iterations can contain multiple builds, depending on how you configured sources in your template. Iterations have an incremental version and a unique identifier.
Build: This resource contains the image metadata produced by a single builder. A build may contain multiple images. Each image has a creation date and an ID that references the location of the stored image artifact. Refer to Image Metadata for more details.

Basic Configuration With Environment Variables

You can use environment variables with both JSON and HCL2 templates. This lets you push image metadata to the HCP Packer registry without making any changes to your Packer template.

This is the only way to push metadata to the HCP Packer registry from a JSON template. For HCL2 templates, this approach is appropriate for simple use cases, but we recommend using the hcp_packer_registry block for more complex pipelines. The hcp_packer_registry block lets you customize the image metadata, including adding labels that communicate important details about the image. Refer to custom configuration for more details.

To use environment variables to push metadata to the HCP Packer registry:

Follow the requirements to push metadata to the registry, including setting environment variables with your service principal and build fingerprint.
Set environment variables to connect your template to an image bucket.
- Packer v1.7.6 and later: Set the HCP_PACKER_REGISTRY environment variable to ON and the HCP_PACKER_BUCKET_NAME environment variable to the name of the image bucket where you want the registry to store metadata for this Packer build. For HCL2 templates, Packer can derive the image bucket name from the name of the build block, unless you change the bucket name. HCP Packer crates a new image bucket with this name if one does not exist. Otherwise, HCP Packer creates a new iteration inside of the image bucket.
- Packer v1.8.4 and later: Set the HCP_PACKER_BUCKET_NAME environment variable to the name of the image bucket where you want the registry to store metadata for this Packer build. HCP Packer creates this image bucket if it does not already exist. Otherwise, HCP Packer creates a new iteration inside of the image bucket.
Call packer build. Packer pushes image metadata to the registry.

The following example publishes image metadata for a single amazon-ebs build to an image bucket on the registry called "example-amazon-ebs".

packer {
  required_plugins {
    amazon = {
      version = ">= 1.0.1"
      source  = "github.com/hashicorp/amazon"
    }
  }
}

source "amazon-ebs" "basic-example-east" {
  region = "us-east-2"
  source_ami_filter {
    filters = {
      virtualization-type = "hvm"
      name                = "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*"
      root-device-type    = "ebs"
    }
    owners      = ["099720109477"]
    most_recent = true
  }
  instance_type  = "t2.small"
  ssh_username   = "ubuntu"
  ssh_agent_auth = false
  ami_name       = "packer_AWS_{{timestamp}}"
}

build {
  name = "example-amazon-ebs"
  sources = [ "source.amazon-ebs.basic-example-east"]
}

packer {
  required_plugins {
    amazon = {
      version = ">= 1.0.1"
      source  = "github.com/hashicorp/amazon"
    }
  }
}

source "amazon-ebs" "basic-example-east" {
  region = "us-east-2"
  source_ami_filter {
    filters = {
      virtualization-type = "hvm"
      name                = "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*"
      root-device-type    = "ebs"
    }
    owners      = ["099720109477"]
    most_recent = true
  }
  instance_type  = "t2.small"
  ssh_username   = "ubuntu"
  ssh_agent_auth = false
  ami_name       = "packer_AWS_{{timestamp}}"
}

build {
  name = "example-amazon-ebs"
  sources = [ "source.amazon-ebs.basic-example-east"]
}

Building this template creates a new iteration in the example-amazon-ebs image bucket. The registry labels this iteration as v1 to denote that it is version 1 of a completed image build.

Iteration details page on HCP Packer registry showing a completed template build with a basic configuration .

Refer to HCP Packer in the Packer documentation for a full list of HCP Packer environment variables.

Custom Configuration

The only metadata that Packer can infer from a template with the basic configuration are the build name and build fingerprint. We recommend adding the hcp_packer_registry block to your template so that you can customize the metadata that Packer sends to the registry.

You do not need to set the HCP_PACKER_REGISTRY environment variable when you add the hcp_packer_registry block to your template. The hcp_packer_registry block is only available for HCL2 Packer templates.

The data in the hcp_packer_registry block overrides the default image bucket name that Packer derives from the build block. You can also add a description and the following types of custom labels to communicate important details about the image.

Bucket labels can help you identify characteristics common to a set of images. For example, they may identify which team maintains the Packer template and which operating system the associated images use. HCP Packer applies custom bucket labels to an entire image bucket.
Build labels can help you provide details about the characteristics of images within a particular iteration. For example, they may identify the precise time of the build or the versions of the tools included in a build, providing an immutable record of these details for future consumers. HCP Packer applies custom build labels to all of the completed builds within an iteration.

The following example adds a description to the image bucket to let consumers know that this is the golden image for Amazon-backed applications. It uses bucket_labels to identify the team responsible for the image bucket and the operating system associated with all builds. It uses build_labels to identify the versions of Python and Ubuntu as well as the precise build time.

build {
  name = "amazon-golden"
  sources = [ "source.amazon-ebs.basic-example-east"]

  hcp_packer_registry {
    bucket_name = "example-amazon-ebs-custom"
    description = "Golden image for Amazon-backed applications"

    bucket_labels = {
      "team" = "amazon-development",
      "os"   = "Ubuntu"
    }

    build_labels = {
      "python-version"   = "3.9",
      "ubuntu-version" = "Xenial 16.04"
      "build-time" = timestamp()
    }
  }
}

build {
  name = "amazon-golden"
  sources = [ "source.amazon-ebs.basic-example-east"]

  hcp_packer_registry {
    bucket_name = "example-amazon-ebs-custom"
    description = "Golden image for Amazon-backed applications"

    bucket_labels = {
      "team" = "amazon-development",
      "os"   = "Ubuntu"
    }

    build_labels = {
      "python-version"   = "3.9",
      "ubuntu-version" = "Xenial 16.04"
      "build-time" = timestamp()
    }
  }
}

Building this template creates a new Iteration in the example-amazon-ebs-custom image bucket. The image bucket contains the description and bucket_labels defined in the hcp_packer_registry block.

Iteration details page on HCP Packer registry showing an image bucket with custom description and labels

The build contains the build_labels defined in the hcp_packer_registry block.

Iteration details page on HCP Packer registry showing a build with custom description and labels

Refer to the hcp_packer_registry block documentation for a complete list of available configuration options.

JSON and HCL2 Feature Comparison

Support for JSON templates is available with limited metadata support. We strongly recommend upgrading to HCL2 templates when possible.

Hands On: Try the Upgrade Packer JSON Template to HCL2 guilde to upgrade an existing JSON template to HCL2.

The following table shows which HCP Packer metadata features are available to Packer JSON and HCL2 templates.

Feature Name	HCL2 Templates	JSON Templates
Basic configuration with environment variables	Full Support	Full Support
Custom configuration via `hcp_packer_registry`	Full Support	No Support
Custom Image Bucket Description	Full Support	No Support
Custom Image Bucket Labels	Full Support	No Support
Custom Iteration Build Labels	Full Support	No Support
Custom Image Bucket Description	Full Support	No Support
Ability to use HCP Packer data sources	Full Support	No Support
HCP Packer Image Governance	Full Support	No Support
HCP Packer Image Ancestry Tracking	Full Support	Limited Support

Limited Ancestry Support for JSON Templates

Ancestry refers to the relationship between source images (parents) and their downstream descendants (children). When you push image metadata to the registry, HCP Packer automatically tracks that image’s source images, if any. You can retrieve this ancestry information with the HCP Packer API

For HCL2 templates only, the HCP Packer UI can also display ancestry statuses that warn you if an image was built from an old version of one or more ancestors. Refer to Ancestry for more details.