Push artifact metadata to HCP Packer

This topic describes how to push metadata to HCP Packer when building artifacts with Packer. For information about metadata storage in HCP Packer, refer to Metadata storage overview. For information about Packer templates, refer to Packer Templates in the Packer documentation.

Overview

There are two methods for enabling Packer to push artifact metadata to HCP Packer when you run the packer build command. You can either set environment variables on the local machine or you can define the push behavior in the Packer template configuration.

Environment variable

You can use environment variables with both JSON and HCL2 templates. This lets you push artifact 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. Refer to Environment variables method for details.

For additional information about JSON and HCL2 templates, refer to the JSON and HCL2 Feature Comparison.

Packer template configuration

We recommend configuring the hcp_packer_registry block in your Packer template configuration instead of using environment variables. The hcp_packer_registry block lets you customize the artifact metadata and add labels that communicate important details about the artifact. Refer to Packer template configuration method for details.

Version fingerprint

When you build an artifact, Packer automatically generates a version fingerprint and associates it with the artifact. The version fingerprint is a unique identifier that determines if metadata for a template build on the registry is complete. The build fails when the fingerprint matches an existing, complete version. Refer to Version Fingerprinting for additional information.

Requirements

You must install Packer v1.7.6 or later on the local machine.

Plugins

Packer relies on plugins to perform many tasks. Refer to Packer integrations.

HCP authentication

Packer uses environment variables to authenticate with the HCP Packer registry and push artifact metadata to a particular organization and project. Set the following environment variables to a service principal key:

Refer to Service Principals for additional information.

Environment variable method

Set the following environment variables on the local machine to enable Packer to push metadata to the HCP Packer registry without modifying the Packer template:
- Set the HCP_PACKER_BUCKET_NAME environment variable to the name of the bucket where you want the registry to store metadata for this Packer build.
- If you are using Packer v1.7.6 - v1.8.3, you must also set the HCP_PACKER_REGISTRY to ON.
HCP Packer creates this bucket if it does not already exist. Otherwise, HCP Packer creates a new version inside of the bucket.
Run the packer build command to build the artifact and push the metadata to the registry.

Environment variables example

The following environment variable specifies that Packer should push artifact metadata to the example-amazon-ebs bucket in the HCP Packer registry:

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"]
}

{
    "builders": [
        {
            "type": "amazon-ebs",
            "name": "basic-example-east",
            "ami_name": "packer_AWS_{{timestamp}}",
            "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
        }]
  }

$ export  HCP_PACKER_BUCKET_NAME=example-amazon-ebs

When Packer builds the following example template, it produces a single Amazon EBS artifact and pushes the metadata to a registry named example-amazon-ebs as specified in the build.name field.

HCP Packer creates a new verison in the example-amazon-ebs bucket called v1 to denote that it is the first version of a completed artifact build. The v1 version contains a unique version fingerprint that you can use to identify the artifact version in the UI and HCP Packer data sources.

Packer template configuration method

Add the hcp_packer_registry block to your Packer template and configure custom metadata for Packer to push to the registry when building the artifact. You can only configure the hcp_packer_registry block in HCL2 Packer templates. Refer to the hcp_packer_registery configuration reference in the Packer documentation for details about configuring the block.

The values in the hcp_packer_registry block override the default values Packer derives from the build block. For example, the value specified in hcp_packer_registry.bucket_name overrides the build.name value.

You can also add a description and the following types of custom labels to communicate important details about the artifact:

bucket_labels: Specifies an arbitrary map of key-value pairs of strings. Use bucket labels to help you identify characteristics common to a set of artifacts, such as identifying which team maintains the Packer template and which operating system the associated artifacts use. HCP Packer applies custom bucket labels to an entire bucket.
build_labels: Specifies an arbitrary map of key-value pairs of strings. Use build labels to help you provide details about artifact characteristics within a particular version. For example, build labels 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 a version.

Template configuration example

The following example Packer template configuration includes metadata that describes the purpose of the purpose of the build. It also includes bucket and build labels so that consumers know which team is responsible for the bucket, the operating system associated with all builds, associated software versions, and a timestamp for the build.

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()
    }
  }
}

HCP Packer creates a new verison in the example-amazon-ebs-custom bucket that contains all of the metadata specified in the template when someone builds the artifact.