Image Metadata

Every time you build a configured Packer template, the HCP Packer registry stores metadata about each new image artifact. You can also define custom metadata to communicate important information about each build to collaborators and image consumers.

Default Metadata

The registry produces some metadata by default to help organize image data into meaningful groups.

Image Buckets

Each registry has one or many image buckets that each map to a single Packer template. Image buckets contain iterations that store image metadata.

When you call packer build, the registry creates a new image bucket for the associated template if one does not already exist. If the image bucket already exists, the registry creates a new iteration inside of the image bucket. Changing an existing build template’s image bucket name creates a new bucket on the registry.

By default, Packer derives the image bucket name from the name field of the template’s build block. However, we recommend that you explicitly set the image bucket name using:

• The bucket_name property in a hcp_packer_registry block. (Preferred) This method codifies the name in your template, ensuring consistency across multiple builds.
• The HCP_PACKER_BUCKET_NAME environment variable.

You can also configure your template to add additional custom image bucket metadata.

Iterations

Each time you build a template, the registry creates a new iteration inside the associated image bucket. Iterations contain the metadata for all of the builds in the template. This record of the build has:

• An incremental version.
• A unique identifier called a build fingerprint.
• A publisher that denotes the service principal used to execute the build on this template.
• A published date.

In the example below, the “learn-packer-ubuntu-test” image bucket has three iterations.

Iteration Versions

When the registry has metadata from all of the builds in a template, it marks the iteration as complete and assigns it a version. The registry generates the version number sequentially, with the first version for an image bucket beginning at v1. You can only map image channels to complete iterations that have a version number.

Versions are unique to each image bucket and each version number can only be associated with one iteration. Version numbers are also immutable.

If part of a template build fails, the registry marks the iteration as incomplete and does not assign a version. The next time you build that template, the registry uses the associated build fingerprint to determine what build metadata is missing, and Packer only runs the builds necessary to complete the iteration.

Revoke Iterations

You can revoke an iteration to prevent consumers from accessing its metadata and using it to build artifacts. You can revoke an iteration immediately or set a future revocation date.

Delete Iterations

To delete an iteration:

1. Go to the HCP Packer homepage and click the image bucket containing the iteration you want to delete.
2. Click Iterations in the sidebar. A list of the iterations within that image bucket appears.
3. Click the elipses (...) to the right of the iteration you want to delete and select Delete iteration. The Delete iteration? box appears.
4. Click Delete iteration.

The iteration and all of its data have been permanently removed from the HCP Packer registry.

Builds

Each iteration can have one or many builds. Each build contains the metadata from all artifacts produced by a single builder. By default, each artifact has an image ID and a creation date, but individual image builders may also produce additional information for the artifact. The registry adds this information as auto-generated labels to each completed build.

For example, Azure image builders produce Azure Shared Image Gallery details for each artifact. The registry adds them as a build label to the resulting image and stores this data as JSON:

"labels": {
  "sig_image_name": "packer-test",
  "sig_image_version": "1.0.0",
  "sig_name": "packer-managed-images"
}

Auto-generated labels vary per builder or post-processor. Check the documentation for each of the Packer plugins for HCP Packer registry output details. You can also configure your template to add additional custom build metadata.

Build labels are immutable; once an iteration is complete, you cannot delete or modify them for that iteration.

Custom Labels

The hcp_packer_registry block lets you add additional labels to image buckets and builds. Labels are unstructured key/value pairs that the HCP Packer registry service stores as JSON.

• 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.

You can set, add, and update custom labels with the bucket_labels and build_labels arguments in the hcp_packer_registry block or through the HCP Packer API. You cannot set separate labels for each build within a single iteration. Build labels are immutable. Once an iteration is complete, you cannot modify or delete them for that iteration.

The following example 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.

"bucket_labels": {
  "team" = "amazon-development",
  "os"   = "Ubuntu"
}

build_labels = {
 "python-version"   = "3.9",
 "ubuntu-version" = "Xenial 16.04"
  "build-time" = timestamp()
}

HCP Packer displays custom labels in the UI. The following example shows build labels.

Refer to Template Configuration for more details about how to push custom metadata to the HCP Packer registry.

Image Ancestry

When Packer pushes image metadata to the registry, HCP Packer automatically tracks the new iteration’s direct source images (parents), if any. If your Packer template uses image channels to reference the parent images, HCP Packer can display ancestry status information in the UI. Ancestry information warns you about outdated images and lets you trace a source image to all of its descendants. Refer to Ancestry for more details.