Metadata storage overview

This topic provides an overview of how HCP Packer stores metadata about the artifacts you build with Packer.

Workflow

HCP Packer stores metadata about your Packer artifacts so that you can track updates, use the most up-to-date base artifacts, and deploy the most up-to-date downstream artifacts. The following process describes how HCP Packer acquires metadata from Packer builds:

1. Create a bucket in the HCP Packer registry to store artifacts. HCP Packer automatically creates a bucket when you build the artifact if a bucket does not already exist. Refer to Create and manage buckets for additional information.
2. Configure the Packer template or set environment variables that enable you to push artifact metadata in HCP Packer. To push metadata using a Packer template, the template must include the hcp_packer_registry build block. Refer to Push metadata to HCP Packer for additional information.
3. Run Packer and specify the template to build the artifact and generate metadata. Packer pushes the metadata to the registry in HCP Packer. Refer to the Packer documentation for instructions on how to run Packer commands.

Metadata organization hierarchy

Each HCP Packer project in your HCP organization has one Packer registry. The registry contains one or more buckets. Each bucket contains the version and build information associated with the artifacts built from a Packer template. Additionally, you can assign versions to channels, which are human-readable names that consumers can reference in Packer templates and Terraform configurations. Refer to Metadata concepts for additional information about each construct.

Rich CI/CD pipeline metadata

If you build artifacts using Packer v1.11.2 or later, HCP Packer also tracks rich metadata associated with your build pipeline, such as CI/CD platform, version control system, operating system, and Packer build command options.

HCP Packer tracks rich metadata in order to provide comprehensive metadata for each Packer build. This metadata enhances the security and provenance of artifacts, ensuring detailed information about the build environment and process is recorded and accessible.

It also provides traceability and helps you achieve compliance with supply-chain levels for software artifacts (SLSA) L1 standards. Refer to the SLSA documentation for additional information.

Refer to the Build pipeline metadata reference for details about the metadata HCP Packer tracks.

Metadata concepts

The metadata stored in HCP Packer is organized around the following concepts.

Buckets

HCP Packer stores artifact metadata for each version of the artifact in a bucket. Each HCP Packer registry has one or more buckets that map to a Packer template. Refer to Create and manage buckets for additional information.

Versions

Every time you build a Packer template, the registry creates a new artifact version in the associated bucket. A version is an immutable record generated by packer build command that contains the metadata for all of the builds in the template.

Versions let you track revisions and revocations of artifacts over time. Each complete version has at least one build, but a version may have many builds depending on how you configured sources in your template.

Builds

Each version has at least one build that contains the metadata from all artifacts produced by a single builder. By default, HCP Packer stores an artifact ID and a creation date, but individual builders may also produce additional information for the artifact. The registry adds this information as auto-generated labels to each completed build. Refer to Builders in the Packer documentation for additional information.

Ancestry

Ancestry refers to the relationship between source artifacts, or parents, and the child artifacts created from the source. Depending on whether you are using registry channels and whether HCP Packer is configured to track parent artifacts, HCP Packer creates an ancestry relationship between new child artifact versions and its source artifact when Packer pushes artifact metadata to the registry. Refer to View ancestry for additional information.

Channels

Channels are names that you can assign to versions. People that consume your artifacts can include the channel name in their Packer template or Terraform configurations so that they use the correct version without modifying their code. Refer to Create and manage channels for additional information.