Install Plugins

This topic describes how to install external plugins for Packer. Refer to Packer Plugins Overview for additional information about plugins.

Overview

Specify one or more required plugins in a Packer template and run the initialization command. During initialization, Packer queries the source repository for plugins specified in the template that match the version constraints for the host operating system. Packer downloads and installs plugins and other dependencies specified in the template.

You can specify a remote project on GitHub or another host that distributes the plugin for Packer to install the plugin from. Refer to Requirements for additional information about installing plugins from a remote source.

When you run the Packer template, Packer first checks the directory for installed plugins that match the version requirements specified in the template. If a suitable version of the plugin is not installed, Packer prints an error. Packer downloads the required version from the source configuration.

Manual installation method

You can manually install plugins if you are unable to specify plugins in an HCL template file. You may need to use the manual plugin installation method if your plugins are still in development.

Manually install a plugin using the packer plugins install command. You specify a local or remote plugin source and include a path to the binary to generate the SHA256SUM file required to load the plugin during Packer builds. Refer to Requirements for additional information about installing plugins from a remote source.

Note that Packer checks the plugin installation directory against the required_plugins block in the Packer template when you build artifacts using the template. Plugins specified in the template that have been installed manually must still comply with the version constraints set in the template.

Installation directory

By default, Packer installs plugins into the plugins directory at $HOME/.config/packer/plugins on Unix and %APPDATA%\packer.d\plugins on Windows, but you can specify a different directory using the PACKER_PLUGIN_PATH environment variable.

Requirements

To install a plugin from GitHub, the plugin must meet the following requirements:

• The repository must be named packer-plugin-<name>.
• The project must have semantic version tags per the following format: v<major>.<minor>.<patch>.
• The release linked to the tag must be available with a shasums file that indicates which files are available in the release.

To install a plugin from a host other than github.com, the host must serve the plugin files over HTTPS using the directory structure described in Host your own plugin source.

GitHub API token

GitHub's public API limits the number of unauthenticated requests per hour from a single IP address. Refer to the GitHub rate limits documentation for additional information.

If you expect to exceed the request rate limit, you can use a GitHub API token to authenticate requests and exceed the rate limit. We recommend setting a GitHub API token when running Packer from a continuous integration server to avoid potential rate limiting errors. Refer to Authenticate requests to the GitHub API for instructions.

Install a plugin

1. In your Packer template file, add the required_plugins block to the packer block.

2. Specify the name of the plugin and its version and source parameters. Setting a correct version constraint string is important for pinning plugin versions for build reproducibility. Refer to the packer block configuration reference for additional information.

   The following example configures Packer to install a plugin called happycloud. When the template is initialized, Packer downloads version 2.7.0 or newer of the plugin from GitHub:

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

3. Run the packer init command. Packer lists all installed plugins then installs the latest plugin version matching the version constraints specified in the required_plugins block. Refer to the init command reference for additional information.

Install HashiCorp-maintained plugins

HashiCorp now makes the following official HashiCorp-maintained plugins available through the HashiCorp release site.

These plugins include:

• Amazon
• Ansible
• Azure
• Docker
• Google Cloud Platform
• QEMU
• Vagrant
• VirtualBox

Starting in Packer 1.14.0, Packer automatically installs these plugins from the new release source, and you do not need to make any changes to your Packer templates. To continue to automatically receive updates to these plugins, you must upgrade to Packer 1.14.0 or newer. If you cannot upgrade your version of Packer, you can still install new versions of these plugins manually. Refer to Manually install plugins using the CLI for more information.

Host your own plugin source

You can install plugins from infrastructure that you manage, such as an internal mirror or an artifact repository. Specify the host and path in the plugin's source address, for example plugins.example.com/mirror/hashicorp/happycloud. The host must serve the following directory structure over HTTPS under the source's path:

packer-plugin-happycloud/index.json
packer-plugin-happycloud/<version>/packer-plugin-happycloud_<version>_SHA256SUMS
packer-plugin-happycloud/<version>/<the zip files listed in the SHA256SUMS file>

This is the same directory structure that releases.hashicorp.com serves. Packer fetches index.json to discover the available versions, selects the version that matches the template's constraints, then downloads the plugin zip for the host platform and verifies it against the version's SHA256SUMS file.

Version directory names do not include a v prefix. When the zip file names in a version directory do not include a plugin protocol version, such as packer-plugin-happycloud_1.0.0_linux_amd64.zip, the directory must also include the version's packer-plugin-happycloud_1.0.0_manifest.json file as published on releases.hashicorp.com. The manifest supplies the protocol version that the file names omit.

Mirror a plugin from releases.hashicorp.com

Copy the plugin's directory tree from releases.hashicorp.com without modification, for example with wget --mirror or rsync. All verification artifacts, including the SHA256SUMS file, its signature, and each version's manifest.json, remain byte-identical to the files HashiCorp publishes.

Mirror a plugin published as GitHub release assets

Complete the following steps for each version of the plugin you want to serve:

1. Create a version directory without a v prefix, such as packer-plugin-happycloud/1.0.0/.

2. Copy the zip files from the GitHub release into the directory.

3. Copy the release's SHA256SUMS file into the directory, removing the v prefix from the version in the file name. For example, packer-plugin-happycloud_v1.0.0_SHA256SUMS becomes packer-plugin-happycloud_1.0.0_SHA256SUMS. Do not modify the file's contents.

4. Add the version to the plugin's index.json file. Only the version keys are required:

   {
     "versions": {
       "1.0.0": {},
       "1.0.1": {}
     }
   }
   

GitHub release asset names include the plugin protocol version, so these versions do not require a manifest.json file. A single host can serve content mirrored from releases.hashicorp.com and content mirrored from GitHub releases side by side, including for different versions of the same plugin.

Limitations

• Plugin sources are always fetched over HTTPS. Plain HTTP is not supported.
• The host's certificate must chain to a certificate authority in the operating system's trust store. Certificates issued by an internal CA require no additional Packer configuration once the system trusts the CA.
• Hostnames with port numbers, such as plugins.example.com:8443, are not supported in source addresses.
• Packer does not authenticate to plugin sources.

Manually install plugins using the CLI

You can use the packer plugins install command to manually install plugin binaries. Use the --path flag to specify a local source. Packer then automatically calculates the SHA256SUM file and installs the files into the Packer plugin directory:

$ packer plugins install --path <path-to-downloaded-extracted-binary> <hostname>/<namespace>/<plugin-name>

The following example installs the happycloud plugin from a locally-sourced binary:

$ unzip packer-plugin-happycloud.zip
$ ls -l
-rwxr-xr-x [...] happycloud
$ packer plugins install --path happycloud github.com/hashicorp/happycloud

Refer to the packer plugins install reference for additional information.

Upgrade plugins

To upgrade plugins that are already installed, run the packer init with the --upgrade flag. Packer retrieves the latest versions of installed plugins specified in the template configuration.

The following example upgrades plugins according to the template in the current directory:

$ packer init --upgrade .

Refer to packer init command for additional information.

Use a plugin under development

If a development binary, such as a manually-built binary, is available at the specified source, Packer uses it in the build if it is the highest compatible version installed and if no final plugin version with the same version number is installed alongside it.

In the following example, version 1.1.0 or newer is required:

packer = {
    required_plugins = {
        amazon = {
            source = "github.com/hashicorp/amazon"
            version = ">= 1.1.0"
        }
    }

. . .

}

Packer uses the -dev version of the Amazon plugin if the following binaries are available:

/Users/dev/.packer.d/plugins
└─ github.com
   └─ hashicorp
        └── amazon
          ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64
          ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64_SHA256SUM
          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64
          └── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM

When a non-development version of 1.1.1 becomes available, the binary takes precedence over the development binary:

/Users/dev/.packer.d/plugins
└─ github.com
   └─ hashicorp
        └── amazon
          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64
          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM
          ├── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64
          └── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64_SHA256SUM

Example Docker plugin

Complete the following steps to build and install a custom version of the Docker plugin as an example:

1. Clone the plugin's GitHub repository.

   $ git clone https://github.com/hashicorp/packer-plugin-docker.git
   

2. Change to the plugin directory root and run the go build command to build the plugin as a development binary.

   $ cd packer-plugin-docker
   $ go build -ldflags="-X github.com/hashicorp/packer-plugin-docker/version.VersionPrerelease=dev" -o packer-plugin-docker-dev
   

3. Validate the release version.

   $ ./packer-plugin-docker-dev describe
   {"version":"1.0.10-dev","sdk_version":"0.5.2","api_version":"x5.0","builders":["-packer-default-plugin-name-"],"post_processors":["import","push","save","tag"],"provisioners":[],"datasources":[]}
   

4. Use the packer plugins install command to install the development binary.

   packer plugins install --path packer-plugin-docker-dev github.com/hashicorp/docker
   Successfully installed plugin github.com/hashicorp/docker from $HOME/Development/packer-plugin-docker/packer-plugin-docker-dev to ~/github.com/hashicorp/docker/packer-plugin-docker_v1.0.10-dev_x5.0_darwin_arm64
   

5. Run a packer build with the newly installed plugin.

   $ packer build .
   

For convenience, the makefile in the Packer plugin scaffolding repository builds and installs development binaries using make dev.

Refer to the documentation in the Packer plugin scaffolding repository for additional information.

Authenticate requests to the GitHub API

You can set the PACKER_GITHUB_API_TOKEN environment variable to send more requests per hour than the limits imposed by the GitHub API:

1. Go to your personal access token page to generate a new token.

2. Set the PACKER_GITHUB_API_TOKEN environment variable to your token value:

   $ export PACKER_GITHUB_API_TOKEN=<token>