The current documentation about installing plugins does not explain
(outside of the `packer init' section) how Packer discovers plugins,
what the expected file system hierarchy should be, and the quirk of how
this takes precedence over the rest when `required_plugins' is
specified.
This commit addresses that by reorganising the page to highlight general
usage questions on sources and plugins, and simplifies the tabs below to
only highlight installation methods.
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.
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/plugins) for a list of available plugins and their documentation.
## Plugin Loading Order
Depending on the template type you're using (HCL2 or legacy JSON), the methods for installing plugins may differ.
@include "plugins/plugin-location.mdx"
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.
`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.
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.
Refer to the [Installation Guides](#installation-guides) section of this page for information about
each, including usage examples.
The remainder of this document will serve as documentation on 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.
## 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 Loading Workflow
At initialization, Packer attempts to discover the plugins installed locally. The
logic follows what's described in Configuring Packer's
Lucas Bajolet
2 years ago
committed by
Lucas Bajolet