From 90e94a42c8b38fd874493c2da9dcba43a4b2db15 Mon Sep 17 00:00:00 2001 From: Lucas Bajolet Date: Wed, 29 Nov 2023 09:55:58 -0500 Subject: [PATCH] docs: reorganise plugin installation docs 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. --- .../content/docs/plugins/install-plugins.mdx | 150 ++++++++++-------- 1 file changed, 86 insertions(+), 64 deletions(-) diff --git a/website/content/docs/plugins/install-plugins.mdx b/website/content/docs/plugins/install-plugins.mdx index fad795bbb59..5489913de70 100644 --- a/website/content/docs/plugins/install-plugins.mdx +++ b/website/content/docs/plugins/install-plugins.mdx @@ -13,9 +13,93 @@ 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 +Depending on the template type you're using (HCL2 or legascy 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 usef 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:** 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 +[plugin directory](https://developer.hashicorp.com/packer/docs/configure#packer-s-plugin-directory) +section. + +While Packer is not verbose during this step, you can peek into what it is discovering +with `PACKER_LOG=1` enabled, where you can find log lines similar to the following: + +```shell +[TRACE] discovering plugins in [...] +[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. + +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 +Linux x86_64 environment): + +```shell + +└── github.com + └── hashicorp + └── amazon + ├── packer-plugin-amazon_v1.2.8_x5.0_linux_amd64 + └── packer-plugin-amazon_v1.2.8_x5.0_linux_amd64_SHA256SUM +``` + +Both the plugin's binary, and the related SHA256SUM file must be placed alongside +each other for Packer to consider them for a `required_plugins` constraint. ## Installation Guides @@ -111,68 +195,6 @@ source "foo-ebs" "example" { } ``` -## 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:** 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 Installation Workflow - -* [`packer init`](/packer/docs/commands/init) will install plugins in the **last** directory -in the following numbered list. - -1. `PACKER_PLUGIN_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 -following files: - -* `PACKER_PLUGIN_PATH/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64` -* `PACKER_CONFIG_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64` - -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_CONFIG_DIR/plugins/github.com/azr/happycloud/` then the file -`PACKER_CONFIG_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64_SHA256SUM` must be generated manually as well. -