Since we're changing how packer manages plugin installation with 1.11.0,
we reflect those changes to the website documentation.
Now, we only describe the packer init and packer plugins install
commands, along with the `--path` flag for installing from a local
source.
The explanations of how packer discovers and picks which version of a
plugin to load are also included, along with the list of constraints
that determine whether a plugin can be considered or not to be loadable.
Packer plugins are separate, standalone applications that perform tasks during each build.
You do not need to install the 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](/packer/integrations) for a list of available plugins and their documentation.
This page explains how to install external plugins. Refer to [Integrations](/packer/integrations) for a list of available plugins and their documentation.
Depending on the template type you're using (HCL2 or legacy JSON), the methods for installing plugins may differ.
@ -22,50 +19,81 @@ command, and those requirements are explicitly documented in the template.
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.
Finally, you can manually install any plugin. This is mostly useful if you're in an environment with
restricted internet access, or if you're installing non-final versions of plugins.
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:
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.
Refer to the [Installation Guides](#installation-guides) section of this page for information about
each, including usage examples.
each method, including usage examples.
The remainder of this document will serve as documentation on how Packer interacts with plugins.
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
your builds if you encounter problems with that.
builds if you encounter problems with plugins.
## Source Addresses
A plugin's source address is its global identifier. It also tells Packer where
to download it.
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.
Source addresses are a URL, without a scheme (e.g. `"https://"`), query (e.g. `?arg=val`), or
fragment (e.g. `#anchor`).
Example: `github.com/hashicorp/happycloud`
Source addresses consist of three parts delimited by slashes (`/`), as
follows:
#### Github sources
`<HOSTNAME>/<NAMESPACE>/<TYPE>`
Github sources all follow this convention: `<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.
- **Hostname:** The hostname of the location/service that distributes the plugin.
- **Namespace:** An organizational namespace within the specified host.
This often is the organization that publishes the plugin.
This often is the organization that maintains 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
For example, the fictional `happycloud` plugin could belong to the
`hashicorp` namespace on `github.com`, so its `source` could be
`github.com/hashicorp/myawesomecloud`,
`github.com/hashicorp/happycloud`,
-> 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.
-> 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.
The source address with all three components given explicitly is called the
plugin's _fully-qualified address_. You will see fully-qualified address in
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.
## Plugin Loading Workflow
### 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.
In order for the binaries installed in this directory to be discovered and used
by Packer, they must follow this set of rules:
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:
a. The plugin version must match the name
b. The API version must match the name's
1. The version must be canonical: e.g. 1.0.1 (valid) vs. 01.000.01 (invalid)
1. The version must be valid semver (e.g. 1.0.0)
1. Pre-releases are accepted, but must be `-dev` only.
1. Metadata shall not be in the name of the plugin binary, only metadata-free versions will be considered valid for discovery purposes.
## Plugin Discovery Workflow
At initialization, Packer attempts to discover the plugins installed locally. The
logic follows what's described in Configuring Packer's
@ -80,31 +108,60 @@ with `PACKER_LOG=1` enabled, where you can find log lines similar to the followi
[INFO] Discovered potential plugin: [...]
```
This logic however is ignored when plugins are defined in `required_plugins` blocks;
instead, for every plugin required in this way, Packer will only consider them if they're
installed in Packer's plugin directory, under a directory hierarchy that matches the
source, with the plugin name respecting a convention.
Once this discovery step has finished, each discovered plugin will be ready to use
by Packer, on the highest available version.
For example, if we install the `github.com/hashicorp/amazon` plugin in version 1.2.8 through
either `packer init` or `packer plugins install`, this will yield the following (in a
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
```
-> packer plugins install --path only works with release versions of plugins.
</Tab>
</Tabs>
-> Note: the version does not need to be specified, Packer will automatically
determine which version to install based on the plugin's `describe` output.
Lucas Bajolet
2 years ago
committed by
Lucas Bajolet