Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Concepts and Templates

Packer Project Layout, Multiple Files and Legacy JSON

Organize a Packer project in several files, learn which file extensions Packer loads, how variable files are picked up, and how to migrate legacy JSON templates to HCL2.

A first template fits in one file. A real image project grows: variables, several sources, shell scripts, config files, a CI definition. How you lay it out decides whether the next engineer finds things quickly. This lesson explains how Packer loads a directory, which file names it treats specially, a layout that scales, and how to convert an older JSON template to HCL2.

Packer is not available on this site, so file trees and commands are read-only. The stand-in program classifies file names the way Packer's loading rules do, in a simplified form.

Packer loads a directory, not a file

Terminal
packer build .            # every matching file in the current directory
packer build web.pkr.hcl  # only this file (variables in other files will be missing)

When you pass a directory, Packer reads all files that end in:

  • .pkr.hcl (HCL2 templates)
  • .pkr.json (the JSON flavor of HCL2)
  • .pkrvars.hcl and .pkrvars.json only when named explicitly with -var-file, except files ending in .auto.pkrvars.hcl or .auto.pkrvars.json, which are loaded automatically

It then merges them into one configuration. Order does not matter, and definitions can be spread across files. Duplicate names (two variable "region" blocks) are an error. Other files such as *.sh, *.tpl or README.md are ignored by the loader; you reference them from provisioners.

Which files does Packer read?

*.pkr.hcl Templates: always loaded.
*.pkr.json JSON form: always loaded.
*.auto.pkrvars.hcl Values loaded automatically.
*.pkrvars.hcl Only with -var-file.

Everything else is ignored.

1 / 2

A layout that scales

TEXT
web-image/
  packer.pkr.hcl          # packer { required_version, required_plugins }
  variables.pkr.hcl       # variable blocks
  locals.pkr.hcl          # locals
  sources.pkr.hcl         # source blocks
  build.pkr.hcl           # build blocks
  data.pkr.hcl            # data sources
  values/
    dev.pkrvars.hcl
    prod.pkrvars.hcl
  files/
    nginx.conf
    app.service
  scripts/
    10-base.sh
    20-app.sh
    90-cleanup.sh
  README.md
  .gitignore

Why this works:

  • A reader opens variables.pkr.hcl to see every input, sources.pkr.hcl to see every platform.
  • Files in files/ are copied with the file provisioner; scripts in scripts/ run with shell. Numeric prefixes make the order obvious.
  • Value files in values/ are chosen explicitly: packer build -var-file=values/prod.pkrvars.hcl ..

Reference paths relative to where you run Packer. Packer sets path.root (the template directory) and path.cwd (the current directory) for use in expressions, so a path that survives running from another folder looks like this:

HCL
provisioner "file" {
  source      = "${path.root}/files/nginx.conf"
  destination = "/tmp/nginx.conf"
}

provisioner "shell" {
  script = "${path.root}/scripts/10-base.sh"
}

Several images in one repository

If one repository builds many images, use one directory per image and share common pieces through scripts, not through directory merging:

TEXT
images/
  base/       *.pkr.hcl
  web/        *.pkr.hcl
  worker/     *.pkr.hcl
scripts/      shared shell scripts

Each directory is a separate packer build images/web. Do not put all templates in one directory unless they should always build together.

Classifying files (stand-in)

This Python stand-in applies the rules above to a list of file names. It shows what would be loaded automatically, what needs -var-file, and what is ignored.

Python Stand-in: which files get loaded?

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.

Note template.json: the old extension is not loaded by the HCL2 loader. Legacy JSON templates must be named *.pkr.json after conversion (or run with the old command form, which newer Packer versions discourage).

The JSON flavor of HCL2

Everything HCL can say, .pkr.json can say too. It is useful when another program generates your templates. The structure mirrors HCL: blocks become objects.

JSON
{
  "source": {
    "docker": {
      "ubuntu": {
        "image": "ubuntu:24.04",
        "commit": true
      }
    }
  },
  "build": [
    {
      "sources": ["source.docker.ubuntu"],
      "provisioner": [
        { "shell": { "inline": ["echo hello"] } }
      ]
    }
  ]
}

Humans should prefer HCL (comments, expressions without quotes, readable diffs). JSON is only a good idea for generated files.

Migrating a legacy JSON template

Older Packer templates look like this (a builders array and double-brace interpolation such as {{timestamp}}):

JSON
{
  "variables": { "region": "eu-west-1" },
  "builders": [
    {
      "type": "amazon-ebs",
      "region": "{{user `region`}}",
      "source_ami": "ami-0123456789abcdef0",
      "instance_type": "t3.micro",
      "ssh_username": "ubuntu",
      "ami_name": "web-{{timestamp}}"
    }
  ],
  "provisioners": [
    { "type": "shell", "inline": ["echo hello"] }
  ]
}

Convert it with:

Terminal
packer hcl2_upgrade -with-annotations legacy.json

That writes legacy.json.pkr.hcl. Then:

  1. Rename it, for example build.pkr.hcl, and delete the JSON original.
  2. Run packer init . and add a proper packer { required_plugins } block (the generated one often has loose constraints).
  3. Run packer fmt . and packer validate ..
  4. Replace generated names with better ones: the converter calls the source autogenerated_1.
  5. Replace old interpolations with modern functions. {{timestamp}} becomes timestamp() (see Built-in functions).
  6. Build once and compare the artifact with the previous version.

Common surprise: some old interpolations (for example {{isotime}}) become helper functions with a legacy_ prefix. They keep the old behavior but are meant as a bridge, so replace them with formatdate(...), uuidv4() and build.name or source.name.

Habits for large projects

  • Put required_version and required_plugins in one file, so upgrades are one small diff.
  • Keep scripts executable and idempotent; test them outside Packer first.
  • Document required environment variables in README.md.
  • Run packer fmt -check and packer validate in CI on every pull request (CI/CD patterns).
  • Never store real credentials in *.auto.pkrvars.hcl; they would be loaded automatically and often get committed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You run packer build . in a folder with build.pkr.hcl, vars.pkr.hcl and prod.pkrvars.hcl. Which files are loaded?

    Template files are merged; plain .pkrvars.hcl files need -var-file, while .auto.pkrvars.hcl would be loaded automatically.
  2. 2. Does file order matter between template files in one directory?

    Packer merges the files; references work regardless of which file defines them.
  3. 3. Which command converts a legacy JSON template to HCL2?

    hcl2_upgrade writes an HCL2 file next to the JSON one. packer fix only updates old JSON syntax.
  4. 4. How do you refer to a script that sits next to the template regardless of the current directory?

    path.root is the directory of the template; path.cwd is where you ran the command.
  5. 5. Why is a .auto.pkrvars.hcl file risky for secrets?

    Because the file is picked up without any flag, people forget it exists and commit it. Use a secret manager or PKR_VAR_* variables instead.

Summary

  • Packer loads every *.pkr.hcl and *.pkr.json in a directory and merges them; order and file names do not matter.
  • Variable files load automatically only if they end in .auto.pkrvars.hcl (or .json); others need -var-file.
  • Split by concern (packer, variables, sources, build) and keep scripts and files in subfolders referenced with ${path.root}.
  • Use one directory per image when a repository builds several images.
  • Convert legacy JSON with packer hcl2_upgrade, then clean up names, plugin constraints and old interpolations.

Next: Builders overview