Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Images for Cloud and VMs

The Docker Builder and Container Images

Use Packer's docker builder to build container images with the same provisioners as VM images: commit and export modes, changes, tags, and when a Dockerfile is the better tool.

Packer is mostly known for virtual machine images, but the docker plugin lets the same template build a container image. You start from a base image, run provisioners inside the container and either commit it as a new image or export its filesystem as a tar archive. This is useful when you already have shell or Ansible provisioning that you want to reuse across VMs and containers.

Docker cannot run in this site's browser pages, so the HCL is read-only and the runnable examples are labelled JavaScript stand-ins for parsing and planning. For a real container build, install Docker and Packer locally.

A minimal template

HCL
packer {
  required_plugins {
    docker = {
      source  = "github.com/hashicorp/docker"
      version = ">= 1.1.0"
    }
  }
}

source "docker" "app" {
  image  = "debian:12-slim"
  commit = true
  changes = [
    "WORKDIR /srv/app",
    "ENV APP_ENV=production",
    "EXPOSE 8080",
    "ENTRYPOINT [\"/srv/app/run.sh\"]"
  ]
}

build {
  sources = ["source.docker.app"]

  provisioner "shell" {
    inline = [
      "apt-get update",
      "apt-get install -y --no-install-recommends ca-certificates curl",
      "rm -rf /var/lib/apt/lists/*"
    ]
  }

  post-processors {
    post-processor "docker-tag" {
      repository = "registry.example.com/team/app"
      tags       = ["1.0.0", "latest"]
    }
  }
}

The flow: Packer starts a container from image, runs provisioners with docker exec, then either commits the container (commit = true) or exports it (export_path = "image.tar"). You must choose exactly one of commit, export_path or discard.

The changes list

A committed image has no Dockerfile, so metadata is applied with changes, which accepts these Dockerfile instructions: CMD, ENTRYPOINT, ENV, EXPOSE, LABEL, MAINTAINER, ONBUILD, USER, VOLUME, WORKDIR. Instructions such as RUN and COPY are not allowed there; the provisioners do that work.

Provisioner caveats inside containers

  • A container has no init system by default, so provisioners that start services (systemd, service nginx start) do not behave as on a VM. Install the software and configure it; the container's entrypoint starts it later.
  • The default user is root, so sudo may not exist. Use execute_command if you need a wrapper.
  • Files from provisioner "file" go into a single layer on commit. Packer does not give you separate layers per provisioner; the whole build becomes essentially one new layer on top of the base.
  • No layer cache exists. Every packer build repeats all provisioners, unlike BuildKit.

Packer or Dockerfile?

Question Dockerfile / BuildKit Packer docker builder
Layer caching and fast rebuilds Excellent None
Multi-stage builds, small images Built in Manual
Reusing VM provisioning (Ansible roles) Awkward Natural
One template for AMI + container No Yes
Standard tooling, scanners, IDE support Best Fewer

A good rule: write ordinary application images with a Dockerfile. Use Packer's docker builder when the same configuration must produce several artifact types, or when your provisioning code already lives in Ansible or shell scripts that target machines.

Pushing to a registry

The docker-tag post-processor names the image and docker-push uploads it. Because credentials are needed, log in beforehand (docker login) or use the docker-push block's login options with variables, never literals. See tagging and pushing pipelines for the chain rules.

flowchart LR
  B["debian:12-slim"] --> P["Provisioners run in container"]
  P --> C["commit + changes"]
  C --> T["docker-tag"]
  T --> U["docker-push"]

The docker-tag and docker-push steps must be in the same post-processor chain, otherwise the tag artifact is lost.

Try it: validate the changes list

JS Check allowed 'changes' instructions (stand-in)

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

No output.

Try it: plan the tags

JS Tag planner (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. Which of these must you configure on a docker source?

    Packer needs to know what to do with the container when provisioning ends.
  2. 2. Which instruction is NOT allowed in the changes list?

    changes only sets image metadata; RUN-like work belongs in provisioners.
  3. 3. What does Packer's docker builder lack compared to BuildKit?

    Every build re-runs all provisioners; there is no per-step cache.
  4. 4. When is the Packer docker builder a good fit?

    Reusing provisioning across artifact types is its main advantage.

Summary

  • The docker builder runs provisioners in a container, then commits or exports it.
  • changes sets metadata (ENV, ENTRYPOINT, EXPOSE...) but cannot run commands.
  • There is no layer cache and no init system; keep containers simple.
  • Prefer Dockerfiles for ordinary apps; use Packer for shared provisioning across artifact types.

Next: Post-processors: what they do and how to chain them