HCP Packer

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

The HCP Packer Registry stores metadata about your artifact, including when they were created, where the artifact exists on the external platform, and what (if any) git commit is associated with your build. You can use the registry to track information about the artifact your Packer builds produce, clearly designate which artifact are appropriate for test and production environments, and query for the right artifact 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 artifact 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 HCP Packer Bucket where you want HCP Packer to store artifact metadata from builds associated with your template. HCP Packer automatically creates the 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 version. To reuse a fingerprint that is associated with an existing incomplete version you must set this environment variable. Refer to Version Fingerprinting for usage details.

• HCP_PACKER_REGISTRY - When set, Packer does not push artifact 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 artifact metadata.

Version Fingerprinting

Packer uses a unique fingerprint for tracking the completion of builds associated to a version. 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 Versions

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 version so that you can resume building that version using the HCP_PACKER_BUILD_FINGERPRINT environment variable; a version can be resumed until it is marked as complete. This environment variable is necessary for resuming an incomplete version, otherwise Packer will create a new version 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 version 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 version.

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 version, 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 a version by setting the fingerprint provided by Packer in case of failure.

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