diff --git a/hcl2template/parser.go b/hcl2template/parser.go index 15c6cc37c..6a14fba13 100644 --- a/hcl2template/parser.go +++ b/hcl2template/parser.go @@ -156,7 +156,9 @@ func (p *Parser) Parse(filename string, varFiles []string, argVars map[string]st // equivalent of having : // packer { // required_plugins { - // amazon = "latest" + // amazon = { + // version = "latest" + // source = "github.com/hashicorp/amazon" // } // } // Note: using `latest` ( or actually an empty string ) in a config file diff --git a/packer/plugin-getter/plugins.go b/packer/plugin-getter/plugins.go index c7909174c..7fdcdac96 100644 --- a/packer/plugin-getter/plugins.go +++ b/packer/plugin-getter/plugins.go @@ -27,7 +27,7 @@ type Requirements []*Requirement type Requirement struct { // Plugin accessor as defined in the config file. // For Packer, using : - // required_plugins { amazon = ">= v0" } + // required_plugins { amazon = {...} } // Will set Accessor to `amazon`. Accessor string diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index 6d1e7c948..e0875474b 100644 --- a/website/content/docs/commands/init.mdx +++ b/website/content/docs/commands/init.mdx @@ -44,11 +44,10 @@ block : ```hcl packer { required_plugins { - myawesomecloud = { + happycloud = { version = ">= 2.7.0" - source = "azr/myawesomecloud" + source = "azr/happycloud" } - happycloud = ">= 2.7.0" } } ``` @@ -57,8 +56,8 @@ HashiCorp does not officially verify third party Packer plugins, plugins not und ## Plugin Selection Plugin selection depends on the source and version constraints defined within the `required_plugins` block. -For each of the required plugins Packer will query the source repository `azr/myawesomecloud` whose fully qualified address -is `https://github.com/azr/packer-plugin-myawesomecloud` 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/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 diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index 0e333a0e0..0852f5ea9 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -76,11 +76,11 @@ Here is an example `required_plugins` block: required_plugins { myawesomecloud = { version = ">= 2.7.0" - source = "azr/myawesomecloud" + source = "github.com/azr/myawesomecloud" } happycloud = { version = ">= 1.1.3" - source = "azr/happycloud" + source = "github.com/azr/happycloud" } } } @@ -130,7 +130,7 @@ If we change the required_plugins block to use a different local name "foo": required_plugins { foo = { version = ">= 2.7.0" - source = "azr/myawesomecloud" + source = "github.com/azr/myawesomecloud" } } ``` @@ -151,27 +151,23 @@ to download it. Source addresses consist of three parts delimited by slashes (`/`), as follows: -`[/]/` +`//` -* **Hostname** (optional): The hostname of the location/service that - distributes the plugin. If omitted, this defaults to - `github.com`, we recommend explicitly setting the hostname. Currently, the - only valid "hostname" is github.com, but we plan to eventually support plugins - downloaded from other domains. +* **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. If omitted, this - defaults to `hashicorp`. We recommend explicitly setting the namespace. + 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`, `hashicorp/myawesomecloud` or -`myawesomecloud`. Note: the actual _repository_ that myawesomecloud comes from -must always have the name format -`www.github.com/hashicorp/packer-plugin-myawesomecloud`, but the +`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. @@ -179,9 +175,8 @@ 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, but in most cases a simplified display version is used. Therefore you may see the shortened version `"myawesomecloud"` -instead of `"github.com/hashicorp/myawesomecloud"`. - --> **Note:** We recommend using explicit source addresses for all plugins. +instead of `"github.com/hashicorp/myawesomecloud"`. This will happen only when +the prefix is `github.com/hashicorp`. ## Plugin location @@ -192,17 +187,15 @@ instead of `"github.com/hashicorp/myawesomecloud"`. Using the following example : ```hcl required_plugins { - myawesomecloud = { + happycloud = { version = ">= 2.7.0" - source = "azr/myawesomecloud" + source = "github.com/azr/happycloud" } - happycloud = ">= 2.7.0" } ``` The plugin getter will look for plugins located at: -* github.com/azr/packer-plugin-myawesomecloud -* github.com/hashicorp/packer-plugin-happycloud +* github.com/azr/packer-plugin-happycloud Packer will error if you set the `packer-plugin-` prefix in a `source`. This will avoid conflicting with other plugins for other tools, like Terraform. diff --git a/website/content/docs/templates/hcl_templates/blocks/packer.mdx b/website/content/docs/templates/hcl_templates/blocks/packer.mdx index b68bd1226..b88d761b8 100644 --- a/website/content/docs/templates/hcl_templates/blocks/packer.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/packer.mdx @@ -59,11 +59,10 @@ version constraint. ```hcl packer { required_plugins { - myawesomecloud = { + happycloud = { version = ">= 2.7.0" - source = "hashicorp/myawesomecloud" + source = "github.com/hashicorp/happycloud" } - happycloud = ">= 2.7.0" } } ``` diff --git a/website/content/partials/plugins/plugin-location.mdx b/website/content/partials/plugins/plugin-location.mdx index 76ab8f6e6..3935c2bf9 100644 --- a/website/content/partials/plugins/plugin-location.mdx +++ b/website/content/partials/plugins/plugin-location.mdx @@ -24,28 +24,26 @@ colon (`:`) on other systems. The order priority will be kept. Using the following example : ```hcl required_plugins { - myawesomecloud = { + happycloud = { version = ">= 2.7.0" - source = "azr/myawesomecloud" + source = "github.com/azr/happycloud" } - happycloud = ">= 2.7.0" } ``` 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/azr/myawesomecloud/` * `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/myawesomecloud/packer-plugin-myawesomecloud_*_darwin_amd64_x5` -* `./github.com/azr/myawesomecloud/packer-plugin-myawesomecloud_*_darwin_amd64_x5` -* `PACKER_HOME_DIR/plugins/github.com/azr/myawesomecloud/packer-plugin-myawesomecloud_*_darwin_amd64_x5` -* `PACKER_PLUGIN_PATH/github.com/azr/myawesomecloud/packer-plugin-myawesomecloud_*_darwin_amd64_x5` -* `./packer-plugin-myawesomecloud` +* `PACKER_EXEC_DIR/github.com/azr/happycloud/packer-plugin-happycloud_*_darwin_amd64_x5.0` +* `./github.com/azr/happycloud/packer-plugin-happycloud_*_darwin_amd64_x5.0` +* `PACKER_HOME_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_darwin_amd64_x5.0` +* `PACKER_PLUGIN_PATH/github.com/azr/happycloud/packer-plugin-happycloud_*_darwin_amd64_x5.0` +* `./packer-plugin-happycloud` The first plugin-name/version files found will take precedence.