Reference artifact metadata from Packer templates and Terraform configurations

This topic describes how to configure Terraform configurations and Packer templates to reference artifact metadata stored in the HCP Packer registry. Refer to Push metadata to HCP Packer for information about storing metadata in HCP Packer.

Overview

You can configure Packer templates and Terraform configuration files to reference artifact metadata stored in the HCP Packer registry. Add a data source to the template or configuration that specifies an HCP Packer channel associated with the metadata.

Channels are human-readable names that artifact consumers can use in their Packer templates or Terraform configurations, instead of hard-coding the artifact versions so that they automatically use the correct version in their applications. Refer to Create and manage channels for additional information.

You can manually configure the files or use the HCL generator in the HCP Packer UI to generate HCL that you can copy and paste into your template or configuration.

When you run the template or configuration, Packer or Terraform builds downstream artifacts from the golden artifact that has metadata on the HCP Packer registry. Using these data sources may result in a billable request depending on your pricing plan.

Hands On: Complete the following tutorials to get started:
Create Child Image from Registry Image
Control Image with Channels

Configure a Packer template

Add the following data sources to your Packer template:
- hcp-packer-version: Specifies a bucket name and channel in the HCP Packer registry to retrieve the version metadata. Refer to the hcp-packer-version configuration reference for details.
- hcp-packer-artifact: Specifies the bucket name, version ID, and other parameters that enable Packer to retrieve the metadata. Refer to the hcp-packer-artifact configuration reference for details.
Pass the metadata in a source block so that you can build child artifacts from the base artifact. The source data block lets you build new artifacts 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.

In the following example, the template retrieves the AMI ID in us-west-2 and uses it as a base artifact for downstream builds.

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

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

Refer to HCL generator for instructions on how to use the HCP Packer UI to generate configuration for your Packer template.

Configure a Terraform configuration file

You can use the HCP Terraform provider data source to retrieve artifact metadata and reference it in your Terraform configuration. Refer to the HCP Terraform provider documentation for details.

Add the provider to your Terraform configuration and specify the following parameters:

hcp_packer_version: Specifies a bucket name and channel in the HCP Packer registry to retrieve the version metadata. Refer to the hcp_packer_version configuration reference in the Terraform registry for details.
hcp_packer_artifact: Specifies the version ID and channel name to retrieve metadata from the HCP Packer registry. Refer to the hcp_packer_artifact configuration reference in the Terraform registry for details.

In the following example, the Terraform HCP provider retrieves the AMI ID from 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.81.0"
    }

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

    required_version = ">= 0.14.9"

}

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

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

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

  tags = {
    Name = "ExampleAppServerInstance"
  }
}

Refer to HCL generator for instructions on how to use the HCP Packer UI to generate configuration for your Terraform configuration.

HCL generator

HCP Packer can generate the HCL configuration to retrieve metadata from each bucket in the registry. Specify the channel, platform, and region in the UI and then paste the auto-generated code into your Packer or Terraform template.

Click Packer to open the HCP Packer registry page.
Click a bucket to open its Overview page.
Choose an option under Use as a data source:

Use with Terraform to generate code for Terraform data sources
Use with Packer to generate configuration for Packer data sources

Choose the artifact channel, platform, and region for the artifact you want to reference. HCP Packer autogenerates HCL configuration based on your selections.
Click Copy code to copy the configuration to your clipboard.
Paste the autogenerated HCL code into the source block of your Terraform or Packer template.

Deleted or deactivated registries

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