---
description: >
  The `hcp_packer_registry` block specifies details for new or updated images in the HCP Packer registry. Learn how to configure the `hcp_packer_registry` block.
page_title: hcp_packer_registry block reference
---

# `hcp_packer_registry` block

This topic provides reference information about the `hcp_packer_registry` block.

## Description

The `hcp_packer_registry` block configures details about an image Packer creates or updates in the HCP Packer registry. Use the `hcp_packer_registry` block to customize the metadata Packer sends to HCP Packer Registry. 

To get started with HCP Packer, refer to the [HCP Packer documentation](/hcp/docs/packer) or try the [Get Started with HCP Packer tutorials](/packer/tutorials/hcp-get-started).

## Usage

This block is available from version 1.7.7 of Packer.

Add a `hcp_packer_registry` block to your template file to enable HCP
Packer mode. When in HCP Packer mode, Packer pushes metadata for all builds in the template to the remote
registry if the appropriate HCP credentials are set (`HCP_CLIENT_ID` and
`HCP_CLIENT_SECRET`). If no HCP credentials are set, Packer will fail the build
and exit immediately to avoid any potential artifact drift between the defined
builders (source blocks) and the HCP Packer registry.

~> **Note:** You will receive an error if you try to reference metadata from 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](https://support.hashicorp.com/) with questions.

```hcl
# file: builds.pkr.hcl
source "happycloud" "macos" {
  os = "macos_amd64"
}

build {
  sources = ["source.happycloud.macos"]
}
hcp_packer_registry {
  bucket_name = "ios-dev"

  description = <<EOT
Some nice description about the image which artifact is being published to HCP Packer Registry. =D
  EOT

  bucket_labels = {
    "team" = "ios-development",
    "os"   = "macos"
  }

  build_labels = {
    "xcode"   = "11.3.0"
    "version" = "Big Sur"
  }
}
```

- `bucket_name` (string) - The image name when published to the HCP Packer
  registry. Should always be the same, otherwise a new image will be created.
  Defaults to `build.name` if not set. Will be overwritten if
  `HCP_PACKER_BUCKET_NAME` is set.

- `bucket_labels` (map[string]string) - Map of labels. Can provide any information,
  such as tools versions (e.g. Go 1.17, Python 3.5, etc...). The bucket labels will
  appear at the image's main page and will be updated whenever it is changed
  and a new iteration for the bucket is pushed to the HCP Packer registry.

- `build_labels` (map[string]string) - Map of labels. Can provide any information,
  such as tools versions (e.g. Go 1.17, Python 3.5, etc...). The build labels will
  appear in the build section of an iteration. Build labels are specific to an iteration
  and will be added to a build when is pushed to the HCP Packer registry.
  Updates to build labels on a completed iteration is not allowed.

- `description` (string) - The image description. Useful to provide a summary
  about the image. The description will appear at the image's main page and
  will be updated whenever it is changed and a new build is pushed to the HCP
  Packer registry. Should contain a maximum of 255 characters. Defaults to
  `build.description` if not set.

- `labels` (map[string]string) - Deprecated in Packer 1.7.9. See [`bucket_labels`](#bucket_labels) for details.

