Packer Settings

The packer configuration block type is used to configure some behaviors of Packer itself, such as the minimum required Packer version needed to apply your configuration.

Packer Block Syntax

Packer settings are gathered together into packer blocks:

packer {
  # ...
}

Each packer block can contain a number of settings related to Packer's behavior. Within a packer block, only constant values can be used; arguments may not refer to named objects such as resources, input variables, etc, and may not use any of the Packer language built-in functions.

The various options supported within a packer block are described in the following sections.

Specifying a Required Packer Version

The required_version setting accepts a version constraint string, which specifies which versions of Packer can be used with your configuration.

If the running version of Packer doesn't match the constraints specified, Packer will produce an error and exit without taking any further actions.

Use Packer version constraints in a collaborative environment to ensure that everyone is using a specific Packer version, or using at least a minimum Packer version that has behavior expected by the configuration.

Specifying Plugin Requirements

The required_plugins block specifies all of the plugins required by the current template, mapping each local plugin name to a source address and a version constraint.

packer {
  required_plugins {
    happycloud = {
      version = ">= 2.7.0"
      source = "github.com/hashicorp/happycloud"
    }
  }
}

Using the required_plugins block to codify the plugins required for invoking a packer build on your template(s) is a great way to ensure consistent builds across different platforms or hosts.

The block codifies two pieces of information that we've found critical to ensure reproducible builds:

1. The source of a required plugin indicates to users where a plugin where a plugin was downloaded from and where to reach out if there are issues with the plugin.
2. The version of a required plugin indicates to users the exact or minimum version needed for the build. This is a great way to pin approved versions of a plugin that can be installed across your environment or team.

For more information on plugins, refer to Plugins.

Define plugin source

Specify the path to the plugin source code in the source field using the following format:

<HOSTNAME>/[SUBFOLDER/]<NAMESPACE>/<TYPE>

• <Hostname>: Specifies the hostname of the location or service that distributes the plugin. Packer only supports using github.com as the hostname when you install plugins using the packer init command. You can point to non-GitHub addresses, such as an internal proxy or plugin binary store, but Packer only pins the required version if you install the plugin using the packer plugins install –path command. Refer to the following documentation for additional information.
  • init command
  • plugins install
• <Subfolder>: The subfolder path segment is an optional part of the address that enables you to download plugin sources from custom addresses. You can specify a source containing up to 13 total path segments.
• <Namespace>: An organizational namespace within the specified host. This often is the organization that publishes the plugin. Type: A short name for the platform or system the plugin manages. The type is usually the plugin's preferred local name.

For example, the value of the source field for a plugin named myawesomecloud is github.com/hashicorp/myawesomecloud if it belongs to the hashicorp namespace on the host github.com.

The actual repository that myawesomecloud comes from must always have the name format github.com/hashicorp/packer-plugin-myawesomecloud, but the required_plugins block omits the redundant packer-plugin- repository prefix for brevity.

Version Constraints

Anywhere that Packer lets you specify a range of acceptable versions for something, it expects a specially formatted string known as a version constraint.

Version Constraint Syntax

Packer's syntax for version constraints is very similar to the syntax used by other dependency management systems like Bundler and NPM.

required_version = ">= 1.2.0, < 2.0.0"

A version constraint is a string literal containing one or more conditions, which are separated by commas.

Each condition consists of an operator and a version number.

Version numbers should be a series of numbers separated by periods (like 1.2.0), optionally with a suffix to indicate a beta release.

The following operators are valid:

• = (or no operator): Allows only one exact version number. Cannot be combined with other conditions.

• !=: Excludes an exact version number.

• >, >=, <, <=: Comparisons against a specified version, allowing versions for which the comparison is true. "Greater-than" requests newer versions, and "less-than" requests older versions.

• ~>: Allows the specified version, plus newer versions that only increase the most specific segment of the specified version number. For example, ~> 0.9 is equivalent to >= 0.9, < 1.0, and ~> 0.8.4, is equivalent to >= 0.8.4, < 0.9. This is usually called the pessimistic constraint operator.

Version Constraint Behavior

A version number that meets every applicable constraint is considered acceptable.

Packer consults version constraints to determine whether it has acceptable versions of itself.

A prerelease version is a version number that contains a suffix introduced by a dash, like 1.2.0-beta. A prerelease version can be selected only by an exact version constraint (the = operator or no operator). Prerelease versions do not match inexact operators such as >=, ~>, etc.