HashiCorp Developer AI Private beta now available Sign up today
Packer
Packer Home

Installing Plugins

Packer plugins are separate, standalone applications that perform tasks during each build.

You do not need to install the builder, provisioner, or post-processor components that ship with the Packer binary. Packer automatically knows how to find and launch these built-in plugins.

This page explains how to install custom external plugins. Refer to External Plugins for a list of available plugins and their documentation.

Plugin Loading Order

Upon the initialization of Packer, any externally installed plugin will be automatically discovered and loaded.

Packer plugins will usually be located within a plugins sub-directory under Packer's main config directory PACKER_CONFIG_DIR. If PACKER_CONFIG_DIR is either not set or empty, a default equal to $HOME/.config/packer/plugins on UNIX, or %APPDATA%\packer.d\plugins for Windows, will be used.

Where applicable, some installation processes such as packer init may override the plugin loading process. Refer to the specific installation guides for any plugin loading overrides.

Packer uses the following process for loading the correct plugin:

  1. All directories under the PACKER_PLUGIN_PATH environment variable, if PACKER_PLUGIN_PATH is set. The PACKER_PLUGIN_PATH takes precedences over all other plugin directories; no other directories will be checked.
  2. The directory where packer is installed, or the executable directory.
  3. The current working directory, where packer build is being invoked. (".")
  4. The PACKER_CONFIG_DIR/plugins directory. PACKER_CONFIG_DIR refers to Packer's config directory, if it could be found.

Note: The PACKER_PLUGIN_PATH environment variable can be set to more that one directories; for example, ~/custom-dir-1:~/custom-dir-2. Separate directories in the PATH string using a colon (:) on UNIX systems and a semicolon (;) on Windows systems. The above example path would be able to find a single or multi-component plugin in either ~/custom-dir-1/packer/ or ~/custom-dir-2/.

Installation Guides

Choose the tab that corresponds to the type of plugin you want to install. If you are not sure, check the plugin's name.

  • Multi-component plugin names have the prefix packer-plugin-.
  • Single-component plugin names have a prefix containing the component type, like packer-provisioner- or packer-builder.

Note: Only multi-component plugin binaries -- plugins named packer-plugin-*, like the packer-plugin-amazon -- are expected to work with Packer init. The legacy builder, post-processor and provisioner plugin types will continue to be detected but Packer cannot install them automatically. If a plugin you use has not been upgraded to use the multi-component plugin architecture, contact your maintainer to request an upgrade.

Create a required_plugins block

  1. Add a required_plugins block to your packer block. Each block will tell Packer what version(s) of a particular plugin can be installed. Make sure to set a valid version constraint string.

Here is an example required_plugins block:

packer {
  required_plugins {
    myawesomecloud = {
      version = ">= 2.7.0"
      source = "github.com/azr/myawesomecloud"
    }
    happycloud = {
      version = ">= 1.1.3"
      source = "github.com/azr/happycloud"
    }
  }
}
  1. Run packer init from your project directory (the directory containing your Packer templates) to install all missing plugin binaries. Given the above example, Packer will try to look for a GitHub repository owned by user or organization azr named packer-plugin-myawesomecloud and packer-plugin-happycloud.

Names and Addresses

Each plugin has two identifiers:

  • A source address, which is necessary when requiring a plugin not bundled with the Packer binary.
  • A unique local name, which is used everywhere else in a Packer configuration.

Local Names

Local names allow you to access the components of a plugin and must be unique per configuration.

This is best explained using an example. In the above required_plugins block, we declared the local name "myawesomecloud" for the plugin azr/myawesomecloud. If the "myawesomecloud" plugin contains both an "ebs" builder and an "import" post-processor, then the builder will be accessed in a source block by using:

source "myawesomecloud-ebs" "example" {
  // builder configuration...
}

similarly, the import post-processor would be accessed by declaring the post-processor block:

post-processor "myawesomecloud-import" {
  // post-processor configuration...
}

If we change the required_plugins block to use a different local name "foo":

  required_plugins {
    foo = {
      version = ">= 2.7.0"
      source = "github.com/azr/myawesomecloud"
    }
  }

Then we'd instead access that builder using the source:

source "foo-ebs" "example" {
  // builder configuration...
}

Source Addresses

A plugin's source address is its global identifier. It also tells Packer where to download it.

Source addresses consist of three parts delimited by slashes (/), as follows:

<HOSTNAME>/<NAMESPACE>/<TYPE>

  • Hostname: The hostname of the location/service that distributes the plugin. Currently, the only valid "hostname" is github.com, but we plan to eventually support plugins downloaded from other domains.

  • 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 fictional myawesomecloud plugin could belong to the hashicorp namespace on github.com, so its source could be github.com/hashicorp/myawesomecloud,

Note: 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.

The source address with all three components given explicitly is called the plugin's fully-qualified address. You will see fully-qualified address in various outputs, like error messages.

Plugin Installation Workflow

  • packer init will install plugins in the last directory in the following numbered list.
  1. PACKER_PLUGIN_PATH if set will be the sole location for installing plugins. All other plugin directories will be ignored.
  2. PACKER_CONFIG_DIR\plugins on Windows systems, or PACKER_CONFIG_DIR/plugins on all other systems.
  • During the initialization of Packer, any plugin required in the required_plugins section will be looked up in all entries of the following list. First plugin found takes precedence. Two binaries of the same plugin with two different version will be considered as two different plugins. Highest found version matching required_plugins will be taken into consideration.

During initialization, on a darwin_amd64 system, Packer will look-up for the following files:

The first plugin-name/version files found will take precedence.

For plugins located under the github.com/azr/happycloud/ directory structure an accompanying SHA256SUM file will be required in order for packer init to ensure the plugin being loaded has not been tampered with. The SHA256SUM file will be automatically generated when a plugin is installed via packer init if the plugin was installed manually into PACKER_CONFIG_DIR/plugins/github.com/azr/happycloud/ then the file PACKER_CONFIG_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64_SHA256SUM must be generated manually as well.

Implicit Github urls

Using the following example :

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

The plugin getter will look for plugins located at:

  • github.com/azr/packer-plugin-happycloud

Packer will error if you set the packer-plugin- prefix in a source. This will avoid conflicting with other plugins for other tools, like Terraform.

Edit this page on GitHub