Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Concepts and Templates

Packer Source and Build Blocks in Depth

Learn how Packer source and build blocks fit together: multiple sources, build names, source-specific provisioners with only and except, build variables and execution order.

The source block says how to start a machine. The build block says what to do with it. Keeping them apart is Packer's best design decision: one source can feed several builds, and one build can run against several sources, so you write each piece once. This lesson shows how they combine, how Packer orders the work, and how to make a provisioner apply to only some sources.

Packer cannot run on this site. HCL is read-only; Python stand-ins model how builds, sources and names combine.

Defining sources

A source holds everything the builder needs to start and reach a machine: platform, region or hypervisor, base image, size, SSH user. It contains no installation steps.

HCL
source "amazon-ebs" "ubuntu" {
  region        = "eu-west-1"
  instance_type = "t3.micro"
  source_ami    = "ami-0123456789abcdef0"
  ssh_username  = "ubuntu"
  ami_name      = "base-ubuntu"
}

source "docker" "ubuntu" {
  image  = "ubuntu:24.04"
  commit = true
}

Source names must be unique per builder type: you can have source.docker.ubuntu and source.amazon-ebs.ubuntu at the same time.

One build, several sources

HCL
build {
  name    = "web"
  sources = [
    "source.amazon-ebs.ubuntu",
    "source.docker.ubuntu",
  ]

  provisioner "shell" {
    inline = ["echo configuring ${source.type}"]
  }
}

Packer runs one build per source, in parallel by default (limit with -parallel-builds=N). Their addresses are web.amazon-ebs.ubuntu and web.docker.ubuntu. Each has its own machine, its own log prefix and its own artifact. This is how you publish the same software as an AWS AMI and a container image from a single template.

flowchart TB
  S1["source.amazon-ebs.ubuntu"] --> B["build 'web'<br/>provisioners + post-processors"]
  S2["source.docker.ubuntu"] --> B
  B --> A1["AMI"]
  B --> A2["Docker image"]

Several sources, one set of steps, one artifact per source.

Several builds in one template

You can also have more than one build block, for example a base image and an application image. Builds run in the order you would expect only if you start them separately: blocks in the same template run in parallel, and Packer has no depends_on between them. If the second image must be built from the first, run two separate packer build commands (or two pipeline stages) and pass the first image's ID as a variable.

HCL
build {
  name    = "base"
  sources = ["source.docker.ubuntu"]
  provisioner "shell" { inline = ["apt-get update"] }
}

build {
  name    = "app"
  sources = ["source.docker.ubuntu"]
  provisioner "shell" { inline = ["echo app"] }
}

Without name, builds are identified only by their source address, which can collide in logs when two builds use the same source. Naming builds is cheap and removes the confusion.

Overriding a source inside a build

HCL
build {
  source "source.docker.ubuntu" {
    name  = "debug"
    image = "ubuntu:24.04"
    # arguments here override the original source for this build only
    commit = true
  }

  provisioner "shell" {
    inline = ["echo hi"]
  }
}

Giving a source a new name also changes its address in logs and in -only patterns (it becomes <build>.docker.debug). Use this when you build the same source twice with different settings.

Order inside a build

Inside one build, Packer runs things in a fixed order:

  1. Start the machine from the source.
  2. Run every provisioner, in file order, one at a time.
  3. Stop the machine and create the artifact.
  4. Run post-processors, in file order.
  5. Remove the temporary machine.

Provisioners from the same build block never run in parallel with each other. Only the sources in a build run in parallel.

Provisioners for specific sources: only and except

Sometimes one step must run only for some sources, for instance a package manager that does not exist in a container:

HCL
build {
  sources = [
    "source.amazon-ebs.ubuntu",
    "source.docker.ubuntu",
  ]

  provisioner "shell" {
    inline = ["apt-get update"]
  }

  provisioner "shell" {
    only   = ["amazon-ebs.ubuntu"]
    inline = ["sudo systemctl enable amazon-ssm-agent"]
  }

  provisioner "shell" {
    except = ["docker.ubuntu"]
    inline = ["sudo growpart /dev/xvda 1"]
  }
}

only lists sources the step is limited to; except lists sources it skips. Names are written as type.name. These two settings work on provisioners and post-processors. Use them sparingly: if half your steps are guarded, the sources probably deserve separate builds.

Build information in expressions

Inside a build you can use values that describe the current run:

Expression Meaning
build.name The build's name
source.name, source.type The source being built
build.PackerRunUUID A unique ID for this run (identical across all sources of one run)
build.ID The machine or artifact ID once known (for example the instance ID)
build.Host, build.Port, build.User How Packer connects to the machine
build.SSHPublicKey Public key Packer generated for this build
HCL
provisioner "shell" {
  inline = [
    "echo Run: ${build.PackerRunUUID}",
    "echo Source: ${source.type}.${source.name}",
  ]
}

Values like build.ID are only filled while the machine exists, so use them in provisioners, not in source arguments.

Error cleanup and pause

A build can define a provisioner that runs only when something fails:

HCL
build {
  sources = ["source.amazon-ebs.ubuntu"]

  provisioner "shell" {
    inline = ["./install.sh"]
  }

  error-cleanup-provisioner "shell" {
    inline = ["echo build failed on $(hostname) >> /tmp/failure.txt"]
  }
}

It runs when a step fails and the build is using -on-error=run-cleanup-provisioner. Typical uses: deregister a license, unregister from a registry, or upload debug logs before the machine is destroyed.

Every provisioner also accepts pause_before (wait a given time before running) and max_retries / timeout (retry and limit). These help when a service needs a moment to start or a mirror is flaky.

A stand-in to explore the build matrix

This Python stand-in computes the build addresses Packer would create from sources and build names, and which provisioners apply to each (honouring only and except). It lets you check an only filter before spending a cloud build on it.

Python Stand-in: the build matrix

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You will see that web.docker.ubuntu skips two steps, while web.amazon-ebs.ubuntu runs all three.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A build lists two sources. How many machines does Packer start?

    Each source gets its own machine and artifact; they run in parallel unless -parallel-builds limits them.
  2. 2. In what order do the steps inside one source's build run?

    Provisioners run one by one in the order written; post-processors run after the artifact is created.
  3. 3. How do you run a provisioner only for the amazon-ebs source named ubuntu?

    only takes a list of type.name strings. except is the inverse.
  4. 4. You need image B to be built from image A. What is the safe approach?

    Packer has no dependency ordering between builds in one run, so chain separate runs or pipeline stages.

Summary

  • A source describes how to start and reach a machine; a build applies provisioners and post-processors to listed sources.
  • Each source in a build gets its own machine, run in parallel by default; addresses look like build.type.name.
  • Inside one machine, provisioners run in order, then post-processors, then cleanup.
  • only and except limit a step to certain sources; error-cleanup-provisioner runs on failure when enabled.
  • Builds in one template do not depend on each other; chain them with separate runs.

Next: Plugins and packer init