required_plugins:Add source addresses section

* Document the purpose of a source address
* Add a note about non-GitHub source addresses containing one of more sub-folder parts
pull/12979/head
Wilken Rivera 2 years ago
parent 4015e4d7be
commit ce7205ed79

@ -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

@ -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>/<NAMESPACE>/<TYPE>`
- **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

Loading…
Cancel
Save