Create child artifact from parent artifact

HCP Packer makes it easier to maintain artifact pipelines. Traditionally, you would need to coordinate with downstream teams whenever you updated an upstream artifact. With HCP Packer and channels, upstream teams — like security or platform teams — can update parent artifacts and use channels to point to the latest version. When downstream teams rebuild their artifacts, Packer will automatically retrieve the channel's current version and rebuild with the new, updated parent artifact.

In this tutorial, you will use Packer to query a specific parent artifact's build version and build a new artifact using that parent artifact. Then, you will update the parent artifact's channel to point to another version, and rebuild the downstream child artifact on top of the new parent artifact.

Prerequisites

To complete this tutorial, you will need:

• Packer 1.10.1+ installed locally
• An HCP account with an HCP Packer Registry

You must have also completed the previous tutorials. In the previous tutorials, you:

• Created a service principal with Contributor access to HCP.
• Set your client ID and secret as environment variables.
• Configured your AWS credentials as environment variables.
• Built an image and push its metadata to HCP Packer.
• Set up a channel named production for your bucket.

Review example template

Open packer-application/application.pkr.hcl to review the Packer template that builds the child artifacts.

This Packer template file contains:

• A hcp-packer-version data source, which retrieves the channel's current version.

  packer-application/application.pkr.hcl

  data "hcp-packer-version" "ubuntu" {
    bucket_name  = "learn-packer-ubuntu"
    channel_name = "production"
  }
  

  Notice that this resource references the bucket name (learn-packer-ubuntu) and channel (production) you created in the previous steps.

• Two hcp-packer-artifact data sources, which retrieve the specific artifact from the version.

  packer-application/application.pkr.hcl

  data "hcp-packer-artifact" "ubuntu-east" {
    bucket_name         = "learn-packer-ubuntu"
    version_fingerprint = data.hcp-packer-version.ubuntu.fingerprint
    platform            = "aws"
    region              = "us-east-2"
  }
  
  data "hcp-packer-artifact" "ubuntu-west" {
    bucket_name         = "learn-packer-ubuntu"
    version_fingerprint = data.hcp-packer-version.ubuntu.fingerprint
    platform            = "aws"
    region              = "us-west-1"
  }
  

  Remember that a version may contain multiple artifacts from different cloud providers and regions. There are two hcp-packer-artifact data sources, one for each region, but they both reference the same version, data.hcp-packer-version.ubuntu.

• Two source template blocks, each one mapping to the parent artifact in its respective region.

  packer-application/application.pkr.hcl

  source "amazon-ebs" "application-east" {
    ami_name = "packer_AWS_{{timestamp}}"
  
    region         = "us-east-2"
    source_ami     = data.hcp-packer-artifact.ubuntu-east.external_identifier
    instance_type  = "t2.small"
    ssh_username   = "ubuntu"
    ssh_agent_auth = false
  
    tags = {
      Name = "learn-packer-application"
    }
  }
  
  source "amazon-ebs" "application-west" {
    ami_name = "packer_AWS_{{timestamp}}"
  
    region         = "us-west-1"
    source_ami     = data.hcp-packer-artifact.ubuntu-west.external_identifier
    instance_type  = "t2.small"
    ssh_username   = "ubuntu"
    ssh_agent_auth = false
  
    tags = {
      Name = "learn-packer-application"
    }
  }
  

  These source blocks retrieve the artifact by querying the AMI ID directly with the source_ami attribute.

• A build block with a hcp_packer_registry block. This defines the new HCP bucket name (learn-packer-application) and builds the two artifacts in parallel.

  packer-application/application.pkr.hcl

  build {
    hcp_packer_registry {
      bucket_name = "learn-packer-application"
      description = <<EOT
  Some nice description about the image being published to HCP Packer Registry.
      EOT
      bucket_labels = {
        "foo-version" = "3.4.0",
        "foo"         = "bar",
      }
    }
    sources = [
      "source.amazon-ebs.application-east",
      "source.amazon-ebs.application-west"
    ]
  }
  

Build the child artifact

Now that you have a template file configured for HCP Packer, build the artifact and push its metadata to the registry.

Change into the packer-application directory.

$ cd ../packer-application

Initialize your Packer template.

$ packer init application.pkr.hcl

Then, format the Packer template.

$ packer fmt application.pkr.hcl
application.pkr.hcl

Finally, build your image. Packer will display color-coded output for both builds. You can tell which build source an output line is associated with by the line's color or prefix.

$ packer build application.pkr.hcl
Tracking build on HCP Packer with fingerprint "01HMF680KXYJWF7GGCQ60EE520"
amazon-ebs.application-east: output will be in this color.
amazon-ebs.application-west: output will be in this color.

==> amazon-ebs.application-east: Prevalidating any provided VPC information
==> amazon-ebs.application-east: Prevalidating AMI Name: packer_AWS_1705611887
==> amazon-ebs.application-west: Prevalidating any provided VPC information
==> amazon-ebs.application-west: Prevalidating AMI Name: packer_AWS_1705611887
## ...
==> Wait completed after 3 minutes 25 seconds

==> Builds finished. The artifacts of successful builds are:
--> amazon-ebs.application-east: AMIs were created:
us-east-2: ami-02406e1178ee8421e

--> amazon-ebs.application-east: Published metadata to HCP Packer registry packer/learn-packer-application/versions/01HMF6811XPQ3QJBB0RHNF0TWF
--> amazon-ebs.application-west: AMIs were created:
us-west-1: ami-0e03e8607ddd7f491

--> amazon-ebs.application-west: Published metadata to HCP Packer registry packer/learn-packer-application/versions/01HMF6811XPQ3QJBB0RHNF0TWF

Visit the AWS us-east-2 AMI Dashboard and us-west-1 AMI Dashboard to verify that Packer has built your AMIs.

View artifact ancestry

Visit the HCP Packer dashboard to review the artifact metadata Packer uploaded to the HCP Packer registry.

For the learn-packer-ubuntu artifact, notice that the Children column contains Up to date. In this column, HCP Packer shows whether the downstream channels used to build each child artifact still point to the same versions.

For the learn-packer-application artifact, notice that the Parents column contains Up to date. In this column, HCP Packer shows whether the upstream channels used to build the latest artifact still point to the same versions.

Now select the learn-packer-application bucket. View the Ancestry table near the bottom to see information about the bucket's parents and children. Notice that there is no information about children because no other buckets use learn-packer-application as a parent.

Update artifact channel

Navigate to the learn-packer-ubuntu bucket, then click on Channels.

Edit the production channel by clicking on the ... and selecting Changed assigned version. Then, update the channel to the v2 version.

View updated ancestry status

Navigate back to the HCP Packer registry's bucket listing. View the parent cell for the learn-packer-application bucket. It now shows Out of date because learn-packer-application's parent bucket has a newer version assigned to its production channel.

Rebuild the child artifact

The parent artifact's production channel now points to a different version. You will rebuild the child artifact on top of the updated parent artifact.

$ packer build application.pkr.hcl
Tracking build on HCP Packer with fingerprint "01HMF6TDG8Y8MZXKC8Q96K5TR7"
amazon-ebs.application-east: output will be in this color.
amazon-ebs.application-west: output will be in this color.

==> amazon-ebs.application-east: Prevalidating any provided VPC information
==> amazon-ebs.application-east: Prevalidating AMI Name: packer_AWS_1705612491
==> amazon-ebs.application-west: Prevalidating any provided VPC information
==> amazon-ebs.application-west: Prevalidating AMI Name: packer_AWS_1705612491
## ...
==> Wait completed after 3 minutes 21 seconds

==> Builds finished. The artifacts of successful builds are:
--> amazon-ebs.application-east: AMIs were created:
us-east-2: ami-0fb5f604f5ba9ed91

--> amazon-ebs.application-east: Published metadata to HCP Packer registry packer/learn-packer-application/versions/01HMF6TE2Z7PM2GV3632RXDT8F
--> amazon-ebs.application-west: AMIs were created:
us-west-1: ami-000d2c9fe4ee1549a

--> amazon-ebs.application-west: Published metadata to HCP Packer registry packer/learn-packer-application/versions/01HMF6TE2Z7PM2GV3632RXDT8F

Visit the AWS us-east-2 AMI Dashboard and us-west-1 AMI Dashboard to verify that Packer has built your AMIs.

Next steps

In this tutorial, you used Packer to query a specific parent artifact's build version and built a new artifact using that parent artifact. Then, you updated the parent artifact's channel to point to another version, and rebuilt the child artifact on top of the new parent artifact.

For more information on topics covered in this tutorial, check out the following resources:

• Read more about referencing artifact metadata in the HCP Packer documentation.
• Visit the HCP Packer Glossary for additional descriptions of the terms covered in this tutorial.
• Visit the Build a Golden Image Pipeline With HCP Packer tutorial to build a sample application artifact with a golden image pipeline, then you will deploy the artifact to AWS using Terraform.
• Complete the Set Up HCP Terraform Run Task for HCP Packer tutorial to learn how to set up run tasks that ensure your Terraform configuration uses compliant artifacts.