From 266c4d99d2fd813ea1d7f09b904403e5c3e25688 Mon Sep 17 00:00:00 2001 From: Lucas Bajolet Date: Mon, 13 May 2024 17:26:31 -0400 Subject: [PATCH] website: update discovery/envvar documentation With the changes coming up for 1.11.0, we update the Packer configuration docs so they describe the one way to load plugins, and the two environment variables which can be set to change this behaviour. --- website/content/docs/configure.mdx | 11 ++----- .../partials/plugins/plugin-location.mdx | 30 +++++-------------- 2 files changed, 11 insertions(+), 30 deletions(-) diff --git a/website/content/docs/configure.mdx b/website/content/docs/configure.mdx index 0cb8f42e6..fb0c247c9 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -124,14 +124,9 @@ each can be found below: using the Packer's config file, see the [config file configuration reference](#packer-config-file-configuration-reference) for more. -- `PACKER_PLUGIN_PATH` - a PATH variable for finding third-party packer - plugins. For example: `~/custom-dir-1:~/custom-dir-2`. Separate directories in - the PATH string using a colon (`:`) on POSIX systems and a semicolon (`;`) on - Windows systems. The above example path would be able to find a provisioner - named `packer-provisioner-foo` in either - `~/custom-dir-1/packer-provisioner-foo` or - `~/custom-dir-2/packer-provisioner-foo`. See the documentation on [plugin - directories](#packer-s-plugin-directory) for more. +- `PACKER_PLUGIN_PATH` - a PATH variable for finding packer plugins. + This takes precedence over `PACKER_CONFIG_DIR/plugins` for plugin discovery + if defined. - `CHECKPOINT_DISABLE` - When Packer is invoked it sometimes calls out to [checkpoint.hashicorp.com](https://checkpoint.hashicorp.com/) to look for diff --git a/website/content/partials/plugins/plugin-location.mdx b/website/content/partials/plugins/plugin-location.mdx index d8e997c7d..40df63adb 100644 --- a/website/content/partials/plugins/plugin-location.mdx +++ b/website/content/partials/plugins/plugin-location.mdx @@ -1,25 +1,11 @@ -Upon the initialization of Packer, any externally installed plugin will be automatically -discovered and loaded. +Upon initialization of Packer, all the installed plugins will be automatically discovered. -Packer plugins will usually be located within a plugins sub-directory under Packer's main config directory -[PACKER_CONFIG_DIR](/packer/docs/configure#packer-s-config-directory). If `PACKER_CONFIG_DIR` is -either not set or empty, a default equal to `$HOME/.config/packer/plugins` on UNIX, or `%APPDATA%\packer.d\plugins` -for Windows, will be used. +Packer plugins must be located under the `plugins` sub-directory under Packer's main config directory +[PACKER_CONFIG_DIR](/packer/docs/configure#packer-s-config-directory). +If `PACKER_CONFIG_DIR` is either unset or empty, a default value of `$HOME/.config/packer/plugins` on UNIX, +or `%APPDATA%\packer.d\plugins` for Windows, will be used. -Where applicable, some installation processes such as `packer init` may override the plugin loading process. -Refer to the specific installation guides for any plugin loading overrides. - -Packer uses the following process for loading the correct plugin: - -1. All directories under the `PACKER_PLUGIN_PATH` environment variable, if `PACKER_PLUGIN_PATH` -is set. The `PACKER_PLUGIN_PATH` takes precedences over all other plugin directories; no other directories will be checked. -1. The directory where `packer` is installed, or the executable directory. -1. The current working directory, where `packer build` is being invoked. (`"."`) -1. The `PACKER_CONFIG_DIR/plugins` directory. `PACKER_CONFIG_DIR` refers to *[Packer's config -directory](/packer/docs/configure#packer-s-config-directory)*, if it could be found. - --> **Note:** The `PACKER_PLUGIN_PATH` environment variable can be set to more that one directories; -for example, ~/custom-dir-1:~/custom-dir-2. Separate directories in the PATH string using a colon (:) on UNIX systems -and a semicolon (;) on Windows systems. The above example path would be able to find a single or multi-component plugin -in either `~/custom-dir-1/packer/` or `~/custom-dir-2/`. +If the `PACKER_PLUGIN_PATH` environment variable is set, it will be used instead of `PACKER_CONFIG_DIR/plugins`. +-> **Note:** Prior to Packer 1.11 the `PACKER_PLUGIN_PATH` environment variable supported values containing + multiple directories. Starting with Packer 1.11 and later this variable only supports a single directory.