-
Notifications
You must be signed in to change notification settings - Fork 3.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
3 changed files
with
107 additions
and
158 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,58 +1,25 @@ | ||
| Plugins will usually be located in the | ||
| [PACKER_HOME_DIR](/packer/docs/configure#packer-s-home-directory). | ||
| Upon the initialization of Packer, any externally installed plugin will be automatically | ||
| discovered and loaded. | ||
|
|
||
| * [`packer init`](/packer/docs/commands/init) will install plugins in the **last** directory | ||
| in the following numbered list. | ||
| 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. | ||
|
|
||
| * 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. | ||
| 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. | ||
|
|
||
| 1. The directory where `packer` is, or the executable directory. | ||
| 1. The current working directory. (`"."`) | ||
| 1. The `PACKER_HOME_DIR/plugins` directory. `PACKER_HOME_DIR` refers to *[Packer's home | ||
| directory](/packer/docs/configure#packer-s-home-directory)*, if it could be found. | ||
| 1. The director(y/ies) under the `PACKER_PLUGIN_PATH` env var, if `PACKER_PLUGIN_PATH` | ||
| is set. | ||
| Packer uses the following process for loading the correct plugin: | ||
|
|
||
| ~> **Note**: There can be more than one directory in the `PACKER_PLUGIN_PATH` | ||
| env var, it will be seperated by a semicolon (`;`) on Windows systems and a | ||
| colon (`:`) on other systems. The order priority will be kept. | ||
| 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. | ||
|
|
||
| Using the following example : | ||
| ```hcl | ||
| required_plugins { | ||
| happycloud = { | ||
| version = ">= 2.7.0" | ||
| source = "github.com/azr/happycloud" | ||
| } | ||
| } | ||
| ``` | ||
| -> **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/`. | ||
|
|
||
| The plugin getter will then install the binaries in the following location for a | ||
| system with no `PACKER_PLUGIN_PATH` env var set. | ||
|
|
||
| * `PACKER_HOME_DIR/plugins/github.com/hashicorp/happycloud/` | ||
|
|
||
| During initialization, on a `darwin_amd64` system, Packer will look-up for the | ||
| following files: | ||
|
|
||
| * `PACKER_EXEC_DIR/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64` | ||
| * `./github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64` | ||
| * `PACKER_HOME_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64` | ||
| * `PACKER_PLUGIN_PATH/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64` | ||
| * `./packer-plugin-happycloud` | ||
|
|
||
| The first plugin-name/version files found will take precedence. | ||
|
|
||
| For plugins located under the `github.com/azr/happycloud/` directory structure an accompanying SHA256SUM file | ||
| will be required in order for `packer init` to ensure the plugin being loaded has not been tampered with. | ||
| The SHA256SUM file will be automatically generated when a plugin is installed via `packer init` if the plugin | ||
| was installed manually into `PACKER_HOME_DIR/plugins/github.com/azr/happycloud/` then the file | ||
| `PACKER_HOME_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64_SHA256SUM` must be generated manually as well. | ||
|
|
||
| -> Note: `PACKER_HOME_DIR` is not an actual env var and refers to [Packer's home | ||
| directory](#packer-s-home-directory). `PACKER_EXEC_DIR` is not an actual env var | ||
| and refers to the directory where `packer` is, or the executable directory. |