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 iteration. To reuse a fingerprint that is associated with an existing incomplete iteration you must set this environment variable. Refer to Iteration Fingerprinting for usage details.

• 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_ORGANIZATION_ID - The ID of the HCP organization linked to your service principal. This is environment variable is not required and available for the sole purpose of keeping parity with the HCP SDK authentication options. Its use may change in a future release.

• HCP_PROJECT_ID - The ID of the HCP project to use. This is useful if your service principal has access to multiple projects, as by default Packer will pick the one created first as target.

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.

Iteration Fingerprinting

Packer uses a unique fingerprint for tracking the completion of builds associated to an iteration. By default a fingerprint is automatically generated by Packer during each invocation of packer build, unless a fingerprint is manually provided via the HCP_PACKER_BUILD_FINGERPRINT environment variable.

In versions before 1.9.0, this fingerprint was computed from the Git SHA of the current HEAD in which your template is stored. If you were running builds using a non Git managed template, you had to set the HCP_PACKER_BUILD_FINGERPRINT environment variable prior to invoking packer build. Starting with Packer 1.9.0, fingerprint generation does not rely on Git at all, and instead Packer now generates a Unique Lexicographically sortable Identifier (ULID) as the fingerprint for every packer build invocation.

Fingerprints and Incomplete Iterations

When you build a template with Packer, there's always a chance that it does not succeed because of a network issue, a provisioning failure, or some upstream error. When that happens, Packer will output the generated fingerprint associated with the incomplete iteration so that you can resume building that iteration using the HCP_PACKER_BUILD_FINGERPRINT environment variable; an iteration can be resumed until it is marked as complete. This environment variable is necessary for resuming an incomplete iteration, otherwise Packer will create a new iteration for the build.

There are two alternatives for when and how to set your own fingerprint:

• You can set it prior to invoking packer build for the first time on this template. This will require the fingerprint to be unique, otherwise Packer will attempt to continue the iteration with the same fingerprint.
• You can invoke packer build on the template, and if it fails, you can then get the fingerprint from the output of the command and set it for subsequent runs, Packer will then continue building this iteration.

The first alternative is recommended for CI environments, as you can use environment variables from the CI to generate a unique, deterministic, fingerprint, and then re-use this in case the step fails for any reason. This will let you continue building the same iteration, rather than creating a new one on each invocation.

The second alternative is good for local builds, as you can interact with the build environment directly, and therefore can decide if you want to continue building an iteration by setting the fingerprint provided by Packer in case of failure.

Please note that in all cases, an iteration can only be continued if it has not completed yet. Once an iteration is complete, it cannot be modified, and you will have to create a new one.