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

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

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

# HCP Packer Iteration Data Source

Type: `hcp-packer-iteration`

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

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

~> **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.

## Revoked Iterations

If an iteration is revoked, the `hcp-packer-iteration` data source will fail and Packer won't proceed with the build. Building new images from a revoked image is not compliant.
Iterations that are scheduled to be revoked will still be considered valid until the revocation date.

## Basic Example

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

```hcl
data "hcp-packer-iteration" "hardened-source" {
  bucket_name = "hardened-ubuntu-16-04"
  channel = "packer-test"
}
```

## Full Example

This data source can be used in conjunction with the hcp-packer-image
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 inside 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-iteration/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-iteration/DatasourceOutput.mdx'