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

• The hcp-packer-iteration data source retrieves iteration metadata from a specified channel.
• The hcp-packer-image data source uses this iteration ID 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.

# Add the registry base image, pulled from the production image channel
data "hcp-packer-iteration" "hardened-source" {
  bucket_name = "learn-packer-ubuntu"
  channel = "production"
}

# Create local and get image id from the base image
data "hcp-packer-image" "secondary-source" {
  bucket_name = "learn-packer-ubuntu"
  iteration_id = data.hcp-packer-iteration.hardened-source.id
  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
  ...
}

# Add the registry base image, pulled from the production image channel
data "hcp-packer-iteration" "hardened-source" {
  bucket_name = "learn-packer-ubuntu"
  channel = "production"
}

# Create local and get image id from the base image
data "hcp-packer-image" "secondary-source" {
  bucket_name = "learn-packer-ubuntu"
  iteration_id = data.hcp-packer-iteration.hardened-source.id
  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.

• 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 data source to add HCP Packer image
data "hcp_packer_iteration" "ubuntu" {
  bucket_name  = "learn-packer-ubuntu"
  channel      = "production"
}

# Create local variable and get image id
data "hcp_packer_image" "ubuntu-aws-west" {
  bucket_name    = "learn-packer-ubuntu"
  cloud_provider = "aws"
  iteration_id   = data.hcp_packer_iteration.ubuntu.ulid
  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"
  }
}

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 data source to add HCP Packer image
data "hcp_packer_iteration" "ubuntu" {
  bucket_name  = "learn-packer-ubuntu"
  channel      = "production"
}

# Create local variable and get image id
data "hcp_packer_image" "ubuntu-aws-west" {
  bucket_name    = "learn-packer-ubuntu"
  cloud_provider = "aws"
  iteration_id   = data.hcp_packer_iteration.ubuntu.ulid
  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"
  }
}

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."
    }
  }
}

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.