Image Channels

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

Image channels assign iterations to human-readable names that consumers can reference in Packer templates and Terraform configurations. You can update the iteration associated with the channel as you release new image versions. This allows consumers to automatically reference the correct version on the registry without having to update their code.

Updating a channel does not automatically notify downstream consumers or trigger downstream Packer builds or Terraform runs. Consumers will automatically use the channel’s latest image version the next time they execute pipelines that request image metadata from that channel.

You can create, update, and delete image channels in the UI as shown below or with the HCP Packer API.

Create Image Channels

You can only assign iterations to a channel when they are complete and the registry has assigned them a version number. To create, edit, or delete a channel:

1. Click Packer in the left sidebar. The HCP Packer page appears with a list of all existing image buckets in your organization.

2. Click a bucket to open its Overview page and then click Channels in the left sidebar. The Channels page appears.

3. Click + New Channel and complete the fields in the Create new channel box:

   • Channel name: This is the string that consumers will use to reference this iteration in code. Choose something short and descriptive.
   • Assign to an iteration: Choose the iteration for the version you want consumers to use when they reference this channel. You can also leave the iteration blank to create a placeholder for future iterations.
   • Channel access: Choose the access type:
     • Unrestricted: The channel will be visible to every member of your organization.
     • Restricted: The channel will only be visible to users of your organization with permission to create, edit, and delete resources.

4. Click Create channel. The new channel is visible on the Channels page and consumers can begin using the channel name in their code.

View Image Channel Details

To view image channel details:

1. Click an image bucket to open its Overview page and then click Channels. The Channels page appears containing a list of all image channels in the image bucket.

2. Click an image channel. The Overview page appears, showing the assigned iteration, the assignment history, and ancestry.

Assignment History

The assignment history shows iterations assigned to this image channel, including the current one. Next to each iteration is the assignment date. HCP stores assignment history for up to one year.

For Standard tier registries, only the last three iterations of a channel's assignment history are visible. The full assignment history is available to Plus tier registries. Refer to View and Change Registry Tier to upgrade the HCP Packer registry tier.

Ancestry

When Packer pushes image metadata to the registry, HCP Packer automatically tracks the new iteration's direct source images (parents) if any. If your Packer template uses image channels to reference the parent images, HCP Packer can display ancestry status information in the UI. Ancestry information warns you about outdated images and lets you trace a source image to all of its descendants.

The image channel details contain the ancestry status for the currently assigned iteration and the channel itself. This lets you check whether the assigned iteration's parents are up-to-date, or if the child images built from this channel are up-to-date.

Refer to Ancestry for more details about ancestry relationships and status.

Reference the Image Channel

You can use the HCL generator on the HCP Packer channel overview page to create a data source snippet for the Packer or Terraform configuration languages. Data sources are the recommended way to retrieve image metadata for building child images with Packer or deploying an image with Terraform. Refer to Reference Image Metadata for more details.

Edit and Delete Image Channels

HCP Packer does not notify consumers when an image channel has been changed or deleted, so make changes cautiously. When you delete an image channel, HCP Packer also permanently deletes its assignment history.

To edit or delete an existing image channel:

1. Go to an image bucket and click Channels in the left sidebar. The Channels page appears with a list of all existing channels in this image bucket.

2. Click the three dots next to the channel you want to edit or delete and select an option:

   • Edit assigned iteration: Choose another iteration and click Update Channel.
   • Edit channel access: Choose a different channel access type and click Confirm.
   • Delete Channel: If you are sure you want to delete this channel, click Delete.

Restore Deleted Image Channels

To restore a deleted image channel, add a new channel with the same channel name and assigned iteration.

Channel Access

You can restrict channel access to only users with the Contributor or Admin role. Restricted channels enable you to validate and test artifacts before making them available to downstream consumers in unrestricted channels.

Restricted channels are not visible to users with the Viewer role.

Automatic 'latest' Channel

Every image bucket has a latest channel by default. This channel is managed by HCP Packer and is automatically updated to the newest unrevoked iteration available in the bucket.

You can use the latest channel in Packer and Terraform templates like other user-managed image channels.

You can not change the iteration assigned to a bucket's latest channel or delete the channel.