» 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.
Note: You will trigger an error if you try to push metadata to a deactivated or deleted registry. An administrator can manually deactivate or delete a registry, and HCP Packer automatically deactivates registries with billing issues. Contact HashiCorp Support with questions.
» Requirements
To successfully configure your Packer template to push data to the HCP Packer registry, you need to:
- Download Packer v1.7.6 or later, featuring the HCP Packer registry integration.
- Use HCP-capable plugins:
- Set the
HCP_CLIENT_ID
andHCP_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 toon
or add anhcl_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".
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. You do not need to set the HCP_PACKER_REGISTRY
environment variable when you add the hcp_packer_registry
block to your template.
The data in the hcp_packer_registry
block overrides the default image bucket name that Packer derives from the build block. You can also add a description and the following types of custom labels to communicate important details about the image.
- Bucket labels can help you identify characteristics common to a set of images. For example, they may identify which team maintains the Packer template and which operating system the associated images use. HCP Packer applies custom bucket labels to an entire image bucket.
- Build labels can help you provide details about the characteristics of images within a particular iteration. For example, they 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 an iteration.
The following example adds a description to the image bucket to let consumers know that this is the golden image for Amazon-backed applications. It uses bucket_labels
to identify the team responsible for the image bucket and the operating system associated with all builds. It uses build_labels
to identify the versions of Python and Ubuntu as well as the precise build time.
Building this template creates a new Iteration in the example-amazon-ebs-custom
image bucket. The image bucket contains the description and bucket_labels
defined in the hcp_packer_registry
block.
The build contains the build_labels
defined in the hcp_packer_registry
block.
Refer to the hcp_packer_registry
block documentation for a complete list of available configuration options.