Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท CI/CD Patterns

Image Versioning, Registries and Promotion

Version golden images with semantic versions and commit SHAs, use channels such as dev, staging and prod, learn what the HCP Packer registry adds, and promote images safely with Terraform.

If every build produces a new image, you need a way to answer three questions: which image is running in production, which image is safe to roll out next and how to go back. Without a plan, teams end up with AMI ids pasted into Terraform files and nobody knows where they came from. This lesson covers naming, channels and promotion, and the optional HCP Packer registry that automates them.

Packer and registries cannot be reached from this site. HCL is read-only; the runnable examples are JavaScript stand-ins that model versions and channels. HCP Packer's interface and limits may change, so check its documentation for current details.

Version identity

A good image has several identities:

Identity Example Purpose
Semantic version 1.4.0 Human-friendly contract: major = base OS or breaking, minor = new software, patch = fixes
Build number / timestamp 20250214.1 Unique per build, orders builds
Git commit SHA a1b2c3d Exact template and scripts used
Cloud id ami-0aaa1111 What actually launches
Base image id ami-0parent9 Provenance of the parent

Put the first three in the image name and tags, and in the manifest. Never reuse a version for different content; an image version, like a release tag, is immutable.

Channels: pointers that move

A channel is a named pointer to a specific version, for example dev, staging and prod. Deployment code asks for "the image in channel prod" instead of an id. Promotion means moving the pointer; rollback means moving it back. Because versions are immutable and pointers are cheap, both operations are instant and auditable.

You can implement channels yourself:

  • Cloud parameter stores (AWS SSM Parameter Store, Azure Compute Gallery tags, GCE image families) hold "current prod AMI id".
  • Git: a file such as images/prod.json updated by a pull request, so promotion is reviewed.
  • HCP Packer: a managed registry that stores iterations with their cloud ids and has channels built in.

The HCP Packer registry

HCP Packer is HashiCorp's hosted service for image metadata. You enable it in the build block and it records every build:

HCL
build {
  hcp_packer_registry {
    bucket_name = "web-base"
    description = "Base image for web servers"
    bucket_labels = {
      team = "platform"
      os   = "ubuntu-24.04"
    }
    build_labels = {
      git_sha = var.git_sha
    }
  }

  sources = ["source.amazon-ebs.base"]
}

It needs HCP credentials in the environment (a service principal; keep them as CI secrets). The registry tracks:

  • Buckets (an image family such as web-base), versions (one per build run) and the artifact ids per cloud and region.
  • Channels that point to a version, with permissions on who may change them.
  • Ancestry: which parent image a child was built from. When a parent is revoked, children become visible as affected.
  • Revocation: marking a version as bad so Terraform data sources refuse to use it.

Terraform consumes the registry through data sources, so infrastructure code never contains an id:

HCL
data "hcp_packer_artifact" "web" {
  bucket_name  = "web-base"
  channel_name = "prod"
  platform     = "aws"
  region       = "eu-central-1"
}

resource "aws_instance" "web" {
  ami           = data.hcp_packer_artifact.web.external_identifier
  instance_type = "t3.small"
}

Check the provider documentation for the current data source names; HCP products evolve.

A promotion flow

flowchart LR
  B["Build 1.4.0"] --> D["channel: dev"]
  D -->|"boot tests pass"| S["channel: staging"]
  S -->|"integration tests + approval"| P["channel: prod"]
  P -->|"incident"| RB["move back to 1.3.2"]

Each arrow is an automated or approved pointer move; the image itself never changes.

Good rules:

  • Only the pipeline moves dev and staging; humans (or a protected approval job) move prod.
  • Keep at least the previous two production versions undeleted so rollback works.
  • Record who promoted what and when (audit log or a Git history of the channel file).
  • Revoke versions with known problems so nobody picks them up again.

Try it: semantic versions and channels

JS Channel registry (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: compare versions

JS Pick the newest semantic version (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a channel?

    Promotion and rollback are just moving the pointer between immutable versions.
  2. 2. Why should image versions be immutable?

    If a version could change, you could not trust what ran in production.
  3. 3. What does revoking a version in a registry do?

    Revocation prevents new deployments from picking a known-bad image.
  4. 4. Where should Terraform get the AMI id for production?

    A looked-up pointer keeps infrastructure code free of ids.

Summary

  • Give each build a semantic version, a commit SHA and a unique id; never reuse a version.
  • Channels (dev, staging, prod) are movable pointers; promotion and rollback are pointer moves.
  • HCP Packer, SSM parameters or a Git file can implement channels; Terraform reads them via data sources.
  • Revoke bad versions and keep previous production versions for rollback.

Next: Rebuild schedules and image lifecycle