Packer checks a number of directories for plugins upon initialization,
with the introduction of multi-component plugins and underlying changes
to the Packer SDK the ordering changed slightly. These changes update
the related documentation to reflect the new ordering, and adds a plugin
loading ordering section to the docs to help users discover how plugin
loading works.
Include in this change are updates to the PACKER_CONFIG_DIR environment
variables to reflect the XDG base directory specification used as the
default Packer configuration directory layout.
* Update website/content/docs/configure.mdx
Packer uses a cache directory to download large files and for logistics around
large file download. By default, Packer caches things in the current directory,
under: `./packer_cache/`. This can be changed by setting the `PACKER_CACHE_DIR`
env var. It is recommended to share the same Packer cache dir across your
builds if you have multiple builds doing similar things to avoid downloading the
same ISO twice for example.
The format of the configuration file is basic JSON.
## Packer config file configuration Reference
### Packer config file configuration Reference
Below is the list of all available configuration parameters for the core
configuration file. None of these are required, since all have defaults.
@ -94,13 +67,20 @@ configuration file. None of these are required, since all have defaults.
and the [`packer init`](/packer/docs/commands/init) command to install plugins; if
you are using both, the `required_plugin` config will take precedence.
### HCP Packer Configuration
## Packer's plugin directory
@include "plugins/plugin-location.mdx"
You can configure both legacy JSON and HCL2 Packer templates to publish image metadata to an active HCP Packer registry. The HCP Packer registry helps you track information about machine images, clearly designate which images are appropriate for test and production environments, and query the right images to use in both Packer and Terraform configurations.
## Packer's cache directory
For complete configuration details and examples, refer to [Packer Template Configuration](/hcp/docs/packer/store-image-metadata/template-configuration) in the HCP Packer documentation.
Packer uses a cache directory to download large files and for logistics around
large file download. By default, Packer caches things in the current directory,
under: `./packer_cache/`. This can be changed by setting the `PACKER_CACHE_DIR`
env var. It is recommended to share the same Packer cache directory across your
builds if you have multiple builds doing similar things to avoid downloading the
same ISO twice for example.
## Full list of Environment Variables usable for Packer
## Environment Variables usable for Packer
Packer uses a variety of environmental variables. A listing and description of
@ -13,6 +13,10 @@ post-processor components that ship with the Packer binary. Packer automatically
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
@include "plugins/plugin-location.mdx"
## 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.
@ -22,10 +26,10 @@ Choose the tab that corresponds to the type of plugin you want to install. If yo
<Tabs>
<Tab heading="Packer init (recommended from Packer v1.7.0)">
~> **Note**: Only _multi-component plugin binaries_ -- that is plugins named
-> **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 keep on being detected but Packer cannot install them automatically.
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.
@ -64,9 +68,8 @@ packer {
Each plugin has two identifiers:
- A `source` address, which is only necessary when requiring a plugin outside the HashiCorp domain.
- A unique **local name**, which is used everywhere else in a Packer
configuration.
- 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
@ -135,7 +138,8 @@ follows:
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
-> 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.
@ -144,9 +148,34 @@ 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 location
## Plugin Installation Workflow
@include "plugins/plugin-location.mdx"
* [`packer init`](/packer/docs/commands/init) will install plugins in the **last** directory
in the following numbered list.
1. `PACKER_PLUGINS_PATH` if set will be the sole location for installing plugins. All other
plugin directories will be ignored.
1. `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
Wilken Rivera
3 years ago