»Template Configuration

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

You can configure any Packer template to push metadata to the HCP Packer registry, but we recommend that you use HCL2 Packer templates. The HCL2 support in Packer allows you to codify how Packer interacts with the registry and customize your image metadata.

»Requirements

To successfully configure your Packer template to push data to the HCP Packer registry, you need to:

• Download Packer v1.7.6 or later, featuring the HCP Packer registry integration.
• Use HCP-capable plugins:
  • packer-plugin-amazon >= v1.0.1
  • packer-plugin-googlecompute >= v1.0.5
  • packer-plugin-azure >= v1.0.3
• 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 will fail with an error explaining why it could not successfully connect to the registry.
• Set the HCP_PACKER_REGISTRY environment variable to on or add an hcl_packer_registry build block to your template.
• 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.

»Basic Configuration

Set the HCP_PACKER_REGISTRY environment variable to on to connect to the HCP Packer registry. When you call packer build, Packer pushes metadata to the registry:

• Image Bucket: This is where the registry stores the metadata from a single Packer template. With a basic configuration, Packer derives the image bucket name from the name of the build block, unless you change the bucket name. If there is not an image bucket with this name, the registry creates a new one. If the image bucket already exists, the registry creates a new iteration inside of the image bucket.
• Iteration: This is an immutable record of each packer build inside of an image bucket. Each complete iteration contains at least one build (details below) but may contain multiple builds, depending on how you configured sources in your template. Iterations have an incremental version and a unique identifier.
• Build: This is 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.

The example template below 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.

.

»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 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.

The build contains the build_labels defined in the hcp_packer_registry block.

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