Packer plugins are separate, standalone applications that perform tasks during each build.
This topic describes how to install external plugins for Packer. Refer to [Packer Plugins Overview](/packer/docs/plugins) for additional information about plugins.
This page explains how to install external plugins. Refer to [Integrations](/packer/integrations) for a list of available plugins and their documentation.
## Overview
Depending on the template type you're using (HCL2 or legacy JSON), the methods for installing plugins may differ.
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.
If you're using HCL2, `packer init` is recommended as you can install all your requirements with one
command, and those requirements are explicitly documented in the template.
You can specify a remote project on GitHub for Packer to install the plugin from. Refer to [Requirements](#requirements) for additional information about installing plugins from a remote source.
`packer plugins install` is also used to automate the installation from a source, and will need to
be repeated for as many plugins as you need.
We recommend this for JSON as the template cannot contain the information about the required plugins.
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.
While `packer plugins install` is able to install plugins remotely, you can use
the `--path` flag to install locally-sourced plugin binaries.
This is typically useful in two general cases:
### Manual installation method
1. You are in an environment with restricted access to a plugin's source.
1. You are trying to install a development version of a plugin for testing.
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 the plugin source is a non-GitHub project or if your plugins are still in development.
Refer to the [Installation Guides](#installation-guides) section of this page for information about
each method, including usage examples.
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](#requirements) for additional information about installing plugins from a remote source.
The remainder of this document documents how Packer interacts with plugins.
We encourage you to read this to get familiar with this process, as it will help you troubleshoot
builds if you encounter problems with plugins.
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.
## Source Addresses
A plugin's source address is conceptually where a plugin binary can be downloaded from.
Packer also uses this source as a global unique identifier.
This source translates directly to the file hierarchy in which the plugin binaries will be
installed.
### Installation directory
Source addresses are a URL, without a scheme (e.g. `"https://"`), query (e.g. `?arg=val`), or
fragment (e.g. `#anchor`).
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. Refer to the [Packer configuration reference](/packer/docs/configure) for additional information.
Example: `github.com/hashicorp/happycloud`
## Requirements
#### Github sources
To install a plugin from a remote source, the plugin must meet the following requirements:
Github sources all follow this convention: `<hostname>/<namespace>/<type>`.
- The plugin project must be hosted on GitHub.
- 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.
- **Hostname:** The hostname of the location/service that distributes the plugin.
### GitHub API token
- **Namespace:** An organizational namespace within the specified host.
This often is the organization that maintains the plugin.
GitHub's public API limits the number of unauthenticated requests per hour from a single IP address. Refer to the [GitHub rate limits documentation](https://docs.github.com/en/developers/apps/rate-limits-for-github-apps#normal-user-to-server-rate-limits) for additional information.
- **Type:** A short name for the platform or system the plugin manages. The
type is usually the plugin's preferred local name.
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](#authenticate-requests-to-the-github-api) for instructions.
For example, the fictional `happycloud` plugin could belong to the
`hashicorp` namespace on `github.com`, so its `source` could be
`github.com/hashicorp/happycloud`,
## Install a plugin
-> Note: the actual _repository_ that happycloud comes from must always have
the name format `github.com/hashicorp/packer-plugin-happycloud`, but the
source voluntarily omits the redundant `packer-plugin-` prefix for brevity.
1. In your Packer template file, add the `required_plugins` block to the `packer` block.
1. Specify the name of the plugin and its `version` and `source` parameters. Setting a correct [version constraint string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints) is important for
pinning plugin versions for build reproducibility. Refer to the [`packer` block configuration reference](/packer/docs/templates/hcl_templates/blocks/packer) for additional information.
The source address with all the components given explicitly is called the
plugin's _fully-qualified address_. You will see fully-qualified addresses in
various outputs, like error messages.
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:
### Source and local hierarchy
As mentioned above, each source URL will directly impact how Packer will install
a plugin to the local plugin directory.
Each component of the path described will become a subdirectory, and finally,
plugin binaries are installed at the end of that hierarchy.
Multiple versions can be installed along one another.
```hcl
packer {
required_plugins {
happycloud = {
version = ">= 2.7.0"
source = "github.com/hashicorp/happycloud"
}
}
}
```
In order for the binaries installed in this directory to be discovered and used
by Packer, they must follow this set of rules:
1. 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](/packer/docs/commands/init) for additional information.
1. The name of the binary must be in the `packer-plugin-<name>_<version>_x<api_version>_<os>_<arch>(.exe)?` format
1. The binary must be accompanied by a SHA256SUM file, which must contain the SHA256 hash of the binary
1. The `describe` command of the binary must return informations that match the plugin's name, namely:
## Manually install plugins using the CLI
a. The plugin version must match the name
You can use the `packer plugins install` command to manually install remote plugins. Include the `--path` flag and specify a local source so that Packer automatically calculates the SHA256SUM file and installs the files into the Packer plugin directory:
Refer to the [`packer plugins install`](/packer/docs/commands/plugins/install) reference for additional information.
While Packer is not verbose during this step, you can peek into what it is discovering
with `PACKER_LOG=1` enabled, where you can find log lines similar to the following:
```shell
[TRACE] discovering plugins in [...]
[INFO] Discovered potential plugin: [...]
```
## Upgrade plugins
Once this discovery step has finished, each discovered plugin will be ready to use
by Packer, on the highest available version.
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.
Example:
The following example upgrades plugins according to the template in the current directory:
In this example, the `happycloud` plugin will be the one and used to serve
happycloud-related components, in version 1.2.8.
Refer to [`packer init` command](/packer/docs/commands/init) for additional information.
### HCL2 and `required_plugins`
## Install a plugin under development
The aforementioned logic is all that can apply to legacy JSON templates.
HCL2 however introduces the concept of `required_plugins` blocks.
These blocks allow you to declare what plugins your template needs in order
to be able to build an artifact, along with version constraints.
You can install and use plugins that are still under development and report as `dev` versions. But if a non-development version of the plugin binary is available, Packer installs the non-development version according to the version constraints configured in the Packer template and uses it in the build.
Example:
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.
```hcl2
packer{
required_plugins {
happycloud = {
source = "github.com/hashicorp/happycloud"
version = "= 1.1.8"
}
}
}
```
In the following example, version `1.1.0` or newer is required:
With this constraint specified, Packer will not only be able to remotely install
the plugin you need with `packer init` (provided it is hosted on a remote that the command
supports), but also restrict which versions can be used for building the template.
```hcl
packer = {
required_plugins = {
amazon = {
source = "github.com/hashicorp/amazon"
version = ">= 1.1.0"
}
}
Using the aforementioned plugin hierarchy, a constraint like the one above will
take precedence over the usual discovery process, this time yielding version 1.1.8
of the happycloud plugin for serving its components.
. . .
## Installation Guides
}
```
### Packer init
Packer uses the `-dev` version of the Amazon plugin if the following binaries are available:
In order to use `packer init` for managing installation of your plugins, there are
two steps required.
Refer to the documentation in the [Packer plugin scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding?tab=readme-ov-file#build-from-source) for additional information.
First, add a [`required_plugins`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements)
block to your [packer block](/packer/docs/templates/hcl_templates/blocks/packer).
### Example Docker plugin
Each block will tell Packer what version(s) of a particular plugin can be installed.
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
```
-> You can only install one plugin per invocation of the command. If you need to install
a specific version of a plugin, you can specify a version to install as an optional
Successfully installed plugin github.com/hashicorp/happycloud from /root/packer-plugin-happycloud to /root/plugins/github.com/hashicorp/happycloud/packer-plugin-happycloud_v1.2.8-dev_x5.0_linux_amd64
```
1. Go to your personal [access token page](https://github.com/settings/tokens) to
generate a new token.
1. Set the `PACKER_GITHUB_API_TOKEN` environment variable to your token value:
-> Note: the version does not need to be specified, Packer will automatically
determine which version to install based on the plugin's `describe` output.
trujillo-adam
2 years ago
committed by
Lucas Bajolet