diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index e1f74f320..0d1caa4dc 100644 --- a/website/content/docs/commands/init.mdx +++ b/website/content/docs/commands/init.mdx @@ -70,22 +70,23 @@ packer { } ``` -HashiCorp does not officially verify third party Packer plugins, plugins not under the HashiCorp namespace `hashicorp/*`; as with all community tools, please do your own due diligence when using a new tool. +HashiCorp does not officially verify third party Packer plugins, plugins not under the HashiCorp namespace `hashicorp/*`; +as with all community tools, please do your own due diligence when using a new tool. ## Plugin Selection -Plugin selection depends on the source and version constraints defined within the `required_plugins` block. +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. -Packer init will install the latest found version matching the version selection -in the `required_plugins` section. Make sure to set a correct [version -constraint -string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints). The -plugins will be installed in the [Plugin -Directory](/packer/docs/configure#packer-s-plugin-directory). +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. -See [Installing Plugins](/packer/docs/plugins#installing-plugins) for more information on how plugin installation works. +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. + +Refer to [Installing Plugins](/packer/docs/plugins#installing-plugins) for more information on how plugin installation works. ## Options diff --git a/website/content/docs/templates/hcl_templates/blocks/packer.mdx b/website/content/docs/templates/hcl_templates/blocks/packer.mdx index b3e590e93..22bce4a39 100644 --- a/website/content/docs/templates/hcl_templates/blocks/packer.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/packer.mdx @@ -52,7 +52,7 @@ a minimum Packer version that has behavior expected by the configuration. later. The `required_plugins` block specifies all of the plugins required by the -current config, mapping each local plugin name to a source address and a +current template, mapping each local plugin name to a source address and a version constraint. ```hcl @@ -60,13 +60,51 @@ packer { required_plugins { happycloud = { version = ">= 2.7.0" - source = "github.com/hashicorp/happycloud" + source = "github.com/azr/happycloud" } } } ``` -For more information, see [Plugins](/packer/docs/plugins). +For more information, 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. + +At minimum source addresses consist of three parts delimited by slashes (`/`), as +follows: + +-> **Note:** In Packer 1.11 and later source addresses support one or more sub-folder paths +after the hostname to support users who require source addresses with more than three parts. +While `packer init` only supports remote installation of GitHub source addresses, running `packer init` on +plugins with custom source addresses allows users to take advantages of version pinning features offered by the +`required_plugins` block. For details on installing plugins using custom source addresses refer to [packer plugins install](/packer/docs/commands/plugins/install). + +`//` + +- **Hostname:** The hostname of the location/service that + distributes the plugin. + +- **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 components given explicitly is called the +plugin's _fully-qualified address_. You will see fully-qualified address in +various outputs, like error messages. ## Version Constraints