Reference Image Metadata

Both Packer templates and Terraform configuration files can reference HCP Packer image channels with the following data sources.

Consumers will receive an error when referencing metadata from a deactivated or deleted registry. An administrator may have manually deactivated or deleted the registry or HCP Packer may have automatically deactivated it because of billing issues. Contact HashiCorp Support with questions.

Packer Data Sources

Hands On: Try the Create Child Image from Registry Image tutorial on HashiCorp Learn.

You can use these data sources in Packer templates to build downstream images from a golden image that has metadata on the HCP Packer registry. Using these data sources may result in a billable request, depending on your pricing plan.

• The hcp-packer-iteration data source retrieves iteration metadata from a specified channel.
• The hcp-packer-image data source uses an iteration ID or a channel to retrieve an image’s metadata and location from HCP Packer.

You can pass the image metadata into a source block, so you can build child images from this base image. These data blocks are integral to implementing a golden image pipeline, since they let you build new images on top of the most recent approved version of an existing image. Refer to the Packer data source documentation for a full list of arguments and configuration options.

This example template uses the data sources to retrieve the AMI ID you built in us-west-2 and uses it as a base image for downstream builds.

# Create local and get image id from the base image
# Retrieve metadata from the production image channel
data "hcp-packer-image" "secondary-source" {
  bucket_name = "learn-packer-ubuntu"
  channel = "production"
  cloud_provider = "aws"
  region = "us-west-2"
}

# Set the `source_ami` to the base image id
source "amazon-ebs" "packer-secondary" {
  source_ami = data.hcp-packer-image.secondary-source.id
  ...
}

HCP Terraform Provider

Hands On: Try the Control Image with Channels tutorial on HashiCorp Learn.

You can use the HCP Terraform provider data sources to retrieve image metadata and reference it in your Terraform configuration. Using these data sources may result in a billable request, depending on your pricing plan.

• The hcp_packer_iteration data source retrieves iteration metadata from a specified channel.
• The hcp_packer_image data source uses an iteration ID and channel name to retrieve an image’s metadata and location from HCP Packer.

This example configuration uses the Terraform HCP provider to retrieve the AMI ID you built in us-west-2 and uses it to provision an EC2 instance. Refer to the Terraform documentation for more information about data sources and working with providers.

terraform {
  required_providers {
    hcp = {
      source = "hashicorp/hcp"
      version = "0.17.0"
    }

    aws = {
      source  = "hashicorp/aws"
      version = "~> 3.52.0"
    }
  }

    required_version = ">= 0.14.9"

}

# Create local variable and get image id from the base image
# Retrieve metadata from the production image channel
data "hcp_packer_image" "ubuntu-aws-west" {
  bucket_name    = "learn-packer-ubuntu"
  channel        = "production"
  cloud_provider = "aws"
  region         = "us-west-2"
}

provider "aws" {
  profile = "default"
  region  = "us-west-2"
}

# Provision an EC2 instance with the HCP Packer image
resource "aws_instance" "app_server" {
  ami           = data.hcp_packer_image.ubuntu-aws-west.cloud_image_id
  instance_type = "t2.micro"

  tags = {
    Name = "ExampleAppServerInstance"
  }
}

HCL Generator

HCP Packer can generate the HCL configuration to retrieve metadata from each image bucket in the registry. You specify the image channel, cloud provider, and region in the UI and then paste the autogenerated code into your Packer or Terraform template.

To generate HCL configuration for an image bucket:

1. Click Packer to go to your HCP Packer registry. The HCP Packer page appears with a list of image buckets in your organization.

2. Click an image bucket to open its Overview page.

3. Choose an option under Use as a data source:

• Use with Terraform to generate code using Terraform data sources
• Use with Packer to generate configuration using Packer data sources

1. Choose the image channel, cloud provider, and region for the image you want to reference. HCP Packer autogenerates HCL configuration based on your selections.

2. Click Copy code to copy the configuration to your clipboard.

3. Paste the autogenerated HCL code into the source block of your Terraform or Packer template.

Validate Iterations in Terraform Configurations

Administrators can revoke iterations for images that have become outdated or pose a security risk. Iterations can also be scheduled for revocation at a future date. You can validate for revoked images manually with the Sentinel policy-as-code framework or automatically with the Terraform Cloud run task integration.

Manual Validation

The hcp_packer_iteration and hcp_packer_image Terraform data sources will still retrieve information for revoked iterations. However, if the hcp_packer_image data source references a revoked image or an image that is scheduled to be revoked, the revoke_at attribute is set to the revocation timestamp.

You can use this attribute to validate Terraform configurations for revoked iterations. For example, the following Terraform configuration will only provision an EC2 instance if the data source returns an iteration that is not revoked.

resource "aws_instance" "app_server" {
  ami           = data.hcp_packer_image.ubuntu_us_east_2.cloud_image_id
  instance_type = "t2.micro"
  tags = {
    Name = "Learn-HCP-Packer"
  }

  lifecycle {
    precondition {
      condition = try(
        formatdate("YYYYMMDDhhmmss", data.hcp_packer_image.ubuntu_us_east_2.revoke_at) > formatdate("YYYYMMDDhhmmss", timestamp()),
        data.hcp_packer_image.ubuntu_us_east_2.revoke_at == ""
      )
      error_message = "Source AMI is revoked."
    }
  }
}

Automate Validation - Terraform Cloud Run Task Integration

Run tasks perform checks on Terraform Cloud operations to determine whether a run should proceed. The HCP Packer image validation Run Task checks the image artifacts within a Terraform configuration. For example, if the configuration references revoked images, users receive an error message with the number of revoked iterations and whether HCP Packer has metadata for a newer version.

For Plus tier registries, the image validation run task also helps you identify hard-coded and untracked images that may not meet security and compliance requirements. The run task notifies you when your configuration uses hard-coded machine image IDs rather than the HCP Packer data source. It also checks whether these images have associated metadata in an HCP Packer registry.

Refer to Terraform Cloud Run Tasks for more details and setup instructions.