HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Packer
Packer Home

You are viewing documentation for version v1.8.x. View latest version.

HCP Packer

The HCP Packer registry bridges the gap between image factories and image deployments, allowing development and security teams to work together to create, manage, and consume images in a centralized way.

The HCP Packer registry stores metadata about your images, including when they were created, where the image exists in the cloud, and what (if any) git commit is associated with your image build. You can use the registry to track information about the golden images your Packer builds produce, clearly designate which images are appropriate for test and production environments, and query for the right golden images to use in both Packer and Terraform configurations.

You can use HCP Packer with both JSON and HCL2 templates. If you are using JSON templates, we recommend getting started with the HCP Packer environment variables and then migrating to HCL when possible.

This page summarizes the methods you can use to connect JSON and HCL2 templates to the HCP Packer registry. It also provides a full list of HCP Packer environment variables. Refer to the Packer Template Configuration page in the HCP Packer documentation for full configuration details and examples.

HCP Packer Environment Variables

The following environment variables let you configure Packer to push image metadata to an active registry without changing your template. You can use environment variables with both JSON and HCL2 templates. Refer to Basic Configuration With Environment Variables in the HCP Packer documentation for complete instructions and examples.

You must set the following environment variables to enable Packer to push metadata to a registry.

  • HCP_CLIENT_ID - The HCP client ID of a HashiCorp Cloud Platform service principle that Packer can use to authenticate to an HCP Packer registry.

  • HCP_CLIENT_SECRET - The HCP client secret of the HashiCorp Cloud Platform service principle that Packer can use to authenticate to an HCP Packer registry.

  • HCP_PACKER_BUCKET_NAME - The name of the image bucket where you want HCP Packer to store image metadata from builds associated with your template. HCP Packer automatically creates the image bucket if it does not already exist. If your HCL2 template contains an hcp_packer_registry block, the bucket name specified in the configuration will be overwritten by this environment variable.

You can set these additional environment variables to control how metadata is pushed to the registry.

  • HCP_PACKER_BUILD_FINGERPRINT - A unique identifier assigned to each build. HCP Packer uses this identifier to determine if metadata for a build on the registry is complete. By default, HCP Packer uses the HEAD Git SHA for the template file. If the template is not version controlled, you must set this environment variable to a unique value before running packer build.

  • HCP_PACKER_REGISTRY - When set, Packer does not push image metadata to HCP Packer from an otherwise configured template. Allowed values are [0|OFF].

HCP Packer Registry Block

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

The hcp_packer_registry block is only available for HCL2 Packer templates. There is no PACKER_CONFIG equivalent for JSON.

Refer to hcp_packer_registry for a full list of configuration arguments. Refer to Custom Configuration in the HCP Packer documentation for information and examples about how to customize image metadata.