From a7591c950a5ae051768e0afebe89c353eb1ff838 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Tue, 14 May 2024 13:59:47 -0400 Subject: [PATCH] Add details on the importance of using required_plugins --- website/content/docs/commands/init.mdx | 14 +++++------ .../templates/hcl_templates/blocks/packer.mdx | 24 +++++++++++++------ 2 files changed, 24 insertions(+), 14 deletions(-) diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index 0d1caa4dc..61858f542 100644 --- a/website/content/docs/commands/init.mdx +++ b/website/content/docs/commands/init.mdx @@ -56,7 +56,7 @@ for the ones that are missing. `packer init -upgrade` will try to get the latest versions for all plugins. -Import a plugin using the [`required_plugin`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) +Install a plugin using the [`required_plugin`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) block : ```hcl @@ -64,7 +64,7 @@ packer { required_plugins { happycloud = { version = ">= 2.7.0" - source = "github.com/azr/happycloud" + source = "github.com/hashicorp/happycloud" } } } @@ -76,15 +76,15 @@ as with all community tools, please do your own due diligence when using a new t ## Plugin Selection Plugin selection depends on the [source](/packer/docs/templates/hcl_templates/blocks/packer#source-addresses) and [version constraints](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints) defined within the `required_plugins` block. -For each of the required plugins Packer will query the source repository `github.com/azr/happycloud` whose fully qualified address -is `https://github.com/azr/packer-plugin-happycloud` for a plugin matching the version constraints for the host operating system. +For each of the required plugins Packer will query the source repository `github.com/hashicorp/happycloud` whose fully qualified address +is `https://github.com/hashicorp/packer-plugin-happycloud` for a plugin matching the version constraints for the host operating system. -Packer init will install the latest plugin version matching the version selection in the `required_plugins` block. +Packer `init` will install the latest plugin version matching the version selection in the `required_plugins` block. Setting a correct [version constraint string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints) is important for pinning plugin versions for build reproducibility. -By default `packer init` will install all required plugins in to the [Plugin Directory](/packer/docs/configure#packer-s-plugin-directory). -You can override the default location by using the `PACKER_PLUGIN_PATH` environement variable to specify a different directory. +`packer init` will install all required plugins into the [Plugin Directory](/packer/docs/configure#packer-s-plugin-directory). +You can override the default location by using the `PACKER_PLUGIN_PATH` environment variable to specify a different directory. Refer to [Installing Plugins](/packer/docs/plugins#installing-plugins) for more information on how plugin installation works. diff --git a/website/content/docs/templates/hcl_templates/blocks/packer.mdx b/website/content/docs/templates/hcl_templates/blocks/packer.mdx index ab6bcb646..8c564e039 100644 --- a/website/content/docs/templates/hcl_templates/blocks/packer.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/packer.mdx @@ -60,18 +60,28 @@ packer { required_plugins { happycloud = { version = ">= 2.7.0" - source = "github.com/azr/happycloud" + source = "github.com/hashicorp/happycloud" } } } ``` -For more information, refer to [Plugins](/packer/docs/plugins). +Using the `required_plugins` block to codify the plugins required for invoking a +`packer build` on your template(s) is a great way to ensure consistent builds across +different platforms or hosts. + +The block codifies two pieces of information that we've found critical to ensure reproducible builds: +1. **The source of a required plugin** indicates to users where a plugin where a plugin was downloaded from +and where to reach out if there are issues with the plugin. +1. **The version of a required plugin** indicates to users the exact or minimum version needed for the build. +This is a great way to pin approved versions of a plugin that can be installed across your environment or team. + +For more information on plugins, refer to [Plugins](/packer/docs/plugins). ## Source Addresses -A plugin's source address is its global identifier that provides users codified information on where a plugin is sourced and can be obtained. -When used in conjunction with the `packer init` command a source address tells Packer where to download the remote plugin from. +A plugin's source address is conceptually where a plugin binary can be downloaded from. Packer also uses this source as a global unique identifier. +When used in conjunction with the `packer init` command a plugin's source address tells Packer where to download it. At minimum source addresses consist of three parts delimited by slashes (`/`), as follows: @@ -108,7 +118,7 @@ various outputs, like error messages. ### Non-GitHub Source Addresses As mentioned above a plugin's source address is its global identifier that provides users codified information on where a plugin is sourced and can be obtained. -In cases where a plugin source does not originate from a GitHub repository, such an internal proxy or plugin binary store, custom source addresses can help +In cases where a plugin source does not originate from a GitHub repository, such as a plugin binary store, custom source addresses can help users taken advantage of plugin version pinning via required_plugins block and forego the use of `packer init` in favor of `packer plugins install --path`. For example if your organization has a need for pre-downloading approved Packer plugins into an internal artifact store (e.g mycompany.com/mirror/hashicorp/happycloud) @@ -119,10 +129,10 @@ packer plugins install --path path/to/binary mycompany.com/mirror/hashicorp/happ ``` The provided source address will translate directly to the file hierarchy in which the plugin binaries will be installed. -After a successful installation the custom source address can be add to your template to take advantage of version pinning for the hashicorp/happycloud plugin. +After a successful installation the custom source address can be added to your template to take advantage of version pinning for the `mycompany.com/mirror/hashicorp/happycloud` plugin. Invoking `packer init` on the template will respond without error and ensure that the correct version of the plugin is loaded. -If however, the plugin is not installed at the time you run `packer init` Packer will error indicationg that on GitHub source addresses are supported for remote installation. +If however, the plugin is not installed at the time you run `packer init` Packer will error indicating that only GitHub source addresses are supported for remote installation. ## Version Constraints