Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Concepts and Templates

Packer Plugins, Version Constraints and packer init

How Packer plugins work: required_plugins, source addresses, version constraints, packer init and upgrade, installing from a mirror or local file, and plugin naming rules.

Packer's core knows nothing about AWS, Docker or VMware. Every builder, provisioner, post-processor and data source is a plugin: a separate executable that Packer starts and talks to over a local connection. This keeps the core small, lets each integration release on its own schedule and lets you write your own. Your job is to say which plugins and which versions a template needs, and run packer init to get them.

Packer cannot run on this site, so HCL and shell commands are read-only. The Python stand-in implements a simplified version-constraint check you can experiment with.

Declaring plugins

Plugins are declared in the packer block:

HCL
packer {
  required_plugins {
    amazon = {
      version = ">= 1.3.0, < 2.0.0"
      source  = "github.com/hashicorp/amazon"
    }
    ansible = {
      version = "~> 1"
      source  = "github.com/hashicorp/ansible"
    }
  }
}
  • The key (amazon) is the local name. It must match the plugin's builder or provisioner prefix. A plugin named packer-plugin-amazon provides components such as amazon-ebs, amazon-ami (a data source) and amazon-import (a post-processor), all starting with amazon.
  • source is the address hostname/namespace/name. For plugins on GitHub that is github.com/<owner>/<name> (without the packer-plugin- prefix).
  • version is a constraint, explained below.

Many popular plugins are maintained by HashiCorp (amazon, docker, vagrant, ansible, azure, googlecompute, vsphere, qemu, virtualbox, vmware). Community and vendor plugins use the same system, with their own sources.

Version constraints

Constraints use the same operators as Terraform:

Constraint Allowed versions
= 1.4.0 or 1.4.0 Exactly 1.4.0
>= 1.4.0 1.4.0 or newer
< 2.0.0 Older than 2.0.0
>= 1.4.0, < 2.0.0 Both conditions (comma means AND)
~> 1.4 >= 1.4.0 and < 2.0.0 (the rightmost number may increase)
~> 1.4.2 >= 1.4.2 and < 1.5.0

Plugins use semantic versioning: the first number changes only for breaking changes. A constraint such as >= 1.0.0, < 2.0.0 or ~> 1 accepts new features and fixes but not breaking changes. Plain >= 1.0.0 is convenient for learning but allows a future 2.x release that may break your template, so pin an upper bound for production.

A stand-in to try constraints

This Python stand-in implements the operators from the table for three-part versions. It is simplified (no pre-release handling) but is enough to see how ~> behaves.

Python Stand-in: version constraint checker

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.

packer init picks the newest installed-or-downloadable version that satisfies the constraint, which is why ~> 1.4 selects 1.9.0 here but ~> 1.4.2 stays on 1.4.2.

packer init

Terminal
packer init .            # install what is missing
packer init -upgrade .   # allow newer matching versions than those installed

What init does:

  1. Reads every required_plugins block in the directory.
  2. Looks up available releases for each source (GitHub releases for github.com/... sources).
  3. Downloads the newest release that matches the constraint and its checksum file.
  4. Verifies the SHA-256 checksum and installs the binary in the plugin folder, a path that depends on the operating system (it lives under Packer's configuration directory; packer plugins installed lists the exact files).

If a template needs a plugin that is not installed, packer build and packer validate stop with a message asking you to run packer init. They never download plugins silently.

flowchart LR
  T["required_plugins<br/>in template"] --> I["packer init"]
  I --> R["Release list<br/>(GitHub)"]
  R --> D["Download + verify checksum"]
  D --> F["Plugin folder<br/>~/.config/packer/plugins"]
  F --> B["packer build<br/>starts plugin process"]

Plugins are downloaded once, then reused by every template that matches.

Plugin locations and offline use

  • Mirror or air gap: set PACKER_PLUGIN_PATH to a folder holding plugins that were downloaded earlier. This is also how CI caches them.
  • Install from a file (for example a plugin you built yourself): packer plugins install --path ./packer-plugin-foo github.com/acme/foo.
  • Manual install is also possible by placing the binary and its checksum file in the right folder structure, but prefer the command.
  • List what you have: packer plugins installed and, for a template, packer plugins required ..
  • Remove one: packer plugins remove github.com/hashicorp/docker.

In CI, cache the plugin folder keyed by a hash of your .pkr.hcl files so init runs fast and builds do not depend on GitHub being reachable every time (CI/CD patterns later in the track return to this).

Which components does a plugin provide?

Naming is by prefix: the component type is the plugin name plus a suffix.

Plugin Builder / source types Others
docker docker docker-push, docker-tag, docker-import, docker-save post-processors
amazon amazon-ebs, amazon-ebssurrogate, amazon-instance, amazon-chroot amazon-ami, amazon-secretsmanager data sources, amazon-import post-processor
qemu qemu
virtualbox virtualbox-iso, virtualbox-ovf, virtualbox-vm
ansible ansible, ansible-local provisioners

Built-in components that need no plugin: provisioners shell, shell-local, file, breakpoint, powershell, windows-shell, windows-restart; post-processors manifest, checksum, compress, artifice, shell-local; and the null builder.

Security notes

  • Plugins are executables that run on your machine with your credentials. Pin versions, and only use sources you trust.
  • Checksum verification during init protects against a corrupted download, not against a malicious release, so review release notes before upgrading.
  • Upgrade deliberately: change the version constraint in a pull request, run packer init -upgrade and build in a test environment first.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does ~> 1.4 allow?

    The pessimistic operator lets the last given number grow: ~> 1.4 means >= 1.4.0 and < 2.0.0. ~> 1.4.2 would stay below 1.5.0.
  2. 2. Which block holds the plugin requirements?

    required_plugins is nested inside the packer block.
  3. 3. What happens if you run packer build without having installed a required plugin?

    Plugins are only installed by init or plugins install, never during build.
  4. 4. Which environment variable adds an extra folder to search for plugins?

    PACKER_PLUGIN_PATH is used for mirrors, caches and locally built plugins.
  5. 5. Why pin an upper bound such as < 2.0.0?

    Major versions may break templates. Upper bounds keep builds reproducible until you opt in.

Summary

  • Builders, provisioners, post-processors and data sources come from plugins, declared in packer { required_plugins { ... } }.
  • Each entry has a local name, a source address and a version constraint; ~> allows only the rightmost number to grow.
  • packer init downloads and verifies the newest matching plugin; builds never download plugins themselves.
  • Use PACKER_PLUGIN_PATH and packer plugins install for mirrors, caches and locally built plugins.
  • Pin versions with upper bounds and upgrade on purpose.

Next: Build lifecycle and artifacts