Create and manage buckets

This topic describes how to create and manage artifact buckets in the HCP Packer registry. A bucket is a repository that stores information about each artifact that is built with Packer. Refer to Metadata storage overview for additional information about constructs in HCP Packer for storing metadata.

Introduction

Buckets can contain artifact metadata for machine images or containers from multiple providers. For example, a golden image for Amazon Web Services (AWS) may exist in multiple regions, or you may have an equivalent Azure image containing the same software. If you define these images in the same Packer template, the registry stores their metadata in the same bucket.

Create a bucket

HCP Packer automatically creates buckets the first time you use the packer build command to build a template.

To create a new bucket from an existing Packer template, specify a new value in the hcp_packer_registry.bucket_name field in the Packer template configuration. The next time you build the template, the HCP Packer creates a new bucket associated with the template. Refer to Push artifact metadata to HCP Packer for additional information.

You can also set the HCP_PACKER_BUCKET_NAME environment variable when building the Packer template. The environment variable overrides the bucket configured in the template. HCP Packer creates a new bucket if the value specified with the variable does not already exist.

Note that the environment variable is required if you are building Packer templates written in JSON. This is because JSON templates do not support the hcp_packer_registry configuration block. Refer to JSON and HCL2 feature reference for additional information.

View a bucket

You can view information associated with a bucket from the HCP Packer UI.

1. Click Packer in the sidebar. The HCP Packer page appears, listing all of the buckets in the project.
2. Click on a bucket ID. The overview page for the bucket appears. This page shows the bucket description, the artifact ID from the latest version, and any custom labels.
3. Click Versions in the sidebar to view details about each version.
4. Click Channels to view details about associated channels. Refer to Create and manage channels for additional information.

Edit a bucket

To edit the metadata contained in a bucket, modify the values specified in the hcp_packer_registry template block of your Packer template configuration. During the next build, HCP Packer overwrites the old values on the registry.

Note that you can only modify the bucket’s metadata, not the existing versions contained in the bucket, which are immutable. Existing versions retain their metadata even after updating the template file.

When you change the bucket’s name, the registry creates a new bucket with the new name for your template and stores all future artifact metadata in the new bucket, but it does not delete the old bucket.

Update a bucket's user permissions

You can update a user's permission at the bucket level through the Terraform HashiCorp Cloud Platform (HCP) Provider using the policy resource or binding resource to assign a role to the principal of your choice.

You can allow users, service principals, and groups to contribute to a bucket without modyfing their project-level viewer permissions to the rest of the HCP Packer registry. Refer to the HCP Packer permissions reference for more information about user permissions for HCP Packer.

Delete a bucket

You can permanently delete a bucket from the HCP Packer UI:

1. Go to the HCP Packer homepage and open the ellipses menu for the bucket you want to delete.
2. Click Delete bucket when prompted.

The bucket and all of its data are permanently removed from the HCP Packer registry.