Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Testing and Security

Validating Packer Templates: fmt, validate and inspect

Catch template mistakes early with packer fmt, init, validate and inspect, use the console, read PACKER_LOG output, run -on-error, and add checks to every pull request.

A Packer build can take ten minutes and cost real money, so you want mistakes found in seconds. Packer ships several commands that check a template without creating any cloud resources. Using them in every pull request is the cheapest form of testing you will ever do. This lesson covers the commands, what they catch, what they cannot catch and how to debug a build that does run.

Packer cannot run on this site. Commands are shown as read-only text and no real output is invented. The runnable examples are JavaScript stand-ins of a linter and a log filter.

The checking commands

Command What it does Cloud access?
packer fmt -check -diff . Verifies canonical HCL formatting (exit code 3 if files need changes) No
packer init . Downloads the plugins in required_plugins Downloads plugins
packer validate . Parses the template, checks block structure, types, references and required fields No (mostly)
packer inspect . Lists variables, sources and builds, a quick overview No
packer console . Interactive prompt to evaluate expressions and variables No
packer build -only=... . Runs real builds Yes

Run them in this order: fmt, init, validate. validate needs the plugins installed, so init must come first in a fresh checkout or CI job.

What validate catches

  • Syntax errors and misspelled block or argument names.
  • Missing required arguments for a source (for example no region).
  • Wrong value types (a string where a list is expected).
  • References to variables, locals or sources that do not exist.
  • Unused or undefined variables, when you pass -var for something that is not declared.

What validate does not catch

  • Credentials that are wrong or expired.
  • An AMI filter that matches nothing, or a nonexistent instance type in a region.
  • A boot command that does not match an installer.
  • A provisioner script that fails at runtime.
  • Policy: tags, encryption, allowed regions.

-syntax-only skips variable evaluation, which is useful when secrets are not available in a PR job. Normal validate wants every required variable to have a value, so give CI dummy values (-var 'api_token=dummy') or defaults for non-secret ones.

Using packer console

Terminal
packer console .
> var.region
> local.timestamp
> formatdate("YYYY-MM-DD", timestamp())

The console lets you test expressions, functions and string interpolation against your variables without building. It is the quickest way to debug a for expression or a filename like "${var.name}-${local.version}".

Debugging a build that fails

  • PACKER_LOG=1 prints detailed logs to stderr; PACKER_LOG_PATH=packer.log writes them to a file. Logs may contain sensitive values, so treat them like secrets and do not upload them from public CI.
  • -on-error=ask pauses after a failure so you can inspect the machine. Choices: cleanup (default), abort (leave everything), run-cleanup-provisioner, ask.
  • -debug steps through each action, pausing for Enter and saving the temporary SSH key.
  • -only / -except run a single source, for example -only='amazon-ebs.base'.
  • -parallel-builds=1 makes logs readable when a build has several sources.
  • -timestamp-ui adds timestamps to each line, helpful for finding slow steps.

When SSH never connects, check the security group and subnet routing, the ssh_username for the source image and ssh_timeout. When a provisioner hangs, look for interactive prompts (apt without -y, or DEBIAN_FRONTEND=noninteractive).

A PR check job

Terminal
packer fmt -check -diff -recursive .
packer init .
packer validate -var-file=ci.pkrvars.hcl .

Keep a ci.pkrvars.hcl with harmless non-secret values so validation works for forks without secrets. Add a linter for your own conventions, such as required tags, as a script (see below).

Try it: a tiny template linter

This stand-in applies team rules to a template described as data.

JS Template lint rules (stand-in)

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

No output.

Try it: filter a build log

JS Find the failing step in a log (stand-in)

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

No output.

The log lines above are invented for practice and do not show real Packer output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which commands should run before packer validate in a fresh CI job?

    validate needs the plugin schemas, which init downloads.
  2. 2. What can packer validate NOT detect?

    Validate does not talk to the cloud; runtime and credential problems appear during a build.
  3. 3. What does -on-error=ask do?

    You decide whether to clean up, abort or retry while the machine still exists.
  4. 4. Why be careful with PACKER_LOG output?

    Debug logs can expose tokens and paths; handle them like secrets.

Summary

  • Run fmt, init and validate on every pull request; they are fast and free.
  • validate finds structural and reference errors, not runtime or credential problems.
  • packer console evaluates expressions; PACKER_LOG, -on-error and -debug help with failing builds.
  • Add your own lint rules for tags, encryption and owners.

Next: Testing the images you build