packer/website/content/docs/datasources/hcp/hcp-packer-image.mdx

---
description: |
  The HCP Packer Image Data Source retrieves information about an
  image from the HCP Packer registry. This information can be used to
  provide a source image to various Packer builders.
page_title: HCP Packer Image - Data Sources
---

<BadgesHeader>
  <PluginBadge type="official" />
  <PluginBadge type="hcp_packer_ready" />
</BadgesHeader>

# HCP Packer Image Data Source

Type: `hcp-packer-image`

The `HCP Packer Image` Data Source retrieves information about an
image from the HCP Packer registry. This information can be used to
provide a source image to various Packer builders.

~> **Note:** HCP Packer is under active development, and we are currently offering a [public beta version](https://portal.cloud.hashicorp.com) to collect feedback and continue improving the product.
To get started, visit the [HCP Packer documentation](https://cloud.hashicorp.com/docs/packer) or try the [Get Started with HCP Packer](https://learn.hashicorp.com/collections/packer/hcp-get-started) collection on HashiCorp Learn.

## Basic Example

Below is a fully functioning example. It stores information about an image,
which can then be parsed and accessed as a variable.

```hcl
data "hcp-packer-image" "example" {
  bucket_name = "hardened-ubuntu-16-04"
  iteration_id = "${data.hcp-packer-iteration.hardened-source.id}"
  cloud_provider = "aws"
  region = "us-east-1"
}
```

## Full Example

This data source can be used in conjunction with the hcp-packer-iteration
data source to retrieve an image ID using a channel. You provide the channel
name to the iteration data source, then use the iteration source in the image
data source, then use the image data source inside your source block.

```hcl
# Retrieves information about the HCP Packer "iteration"; an "iteration" can be
# thought of as all the metadata created by a single call of `packer build`.
data "hcp-packer-iteration" "hardened-source" {
  bucket_name = "hardened-ubuntu-16-04"
  channel = "packer-test"
}

# Retrieves information about the HCP Packer "image"; an image can be thought
# of as all the metadata (including the artifact names) created by a single
# "source" builder; this can include multiple images so we provide a cloud
# region to disambiguate.
data "hcp-packer-image" "foo" {
  bucket_name = "hardened-ubuntu-16-04"
  iteration_id = data.hcp-packer-iteration.hardened-source.id
  cloud_provider = "aws"
  region = "us-east-1"
}

# This source uses the output from a previous Packer build. By using the
# HCP Packer registry in this way, you can easily create build pipelines where
# a single base image can be customized in multiple secondary layers.
source "amazon-ebs" "packer-secondary" {
  source_ami       = data.hcp-packer-image.foo.id
  # ...
}
```

## Configuration Reference

Configuration options are organized below into two categories: required and
optional. Within each category, the available options are alphabetized and
described.

### Required:

@include 'datasource/hcp-packer-image/Config-required.mdx'

There are currently no optional fields for this datasource, though we intend
to add filtering fields in the future.

### Output Fields:

@include 'datasource/hcp-packer-image/DatasourceOutput.mdx'