»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 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. Specifically, you can add a description and labels to the image bucket to communicate important details about the image.

The data in the hcp_packer_registry block overrides the default image bucket name that Packer would normally infer. You do not need to set the HCP_PACKER_REGISTRY environment variable when you add the hcp_packer_registry block to your template.

The example block below adds a description to the image bucket letting other team members and consumers know that this is the golden image for Amazon-backed applications. It also labels the image’s Python version and operating system.

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

    labels = {
      "python_version" = "3.4.0",
      "os" = "ubuntu",
    }
  }

  hcp_packer_registry {    bucket_name = "example-amazon-ebs-custom"    description = "Golden image for Amazon-backed applications"
    labels = {      "python_version" = "3.4.0",      "os" = "ubuntu",    }  }

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

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