From 10febf4b9fe6407c00145806a16cd5cab29b0c66 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 18:59:58 +0000 Subject: [PATCH 01/24] backport of commit b23c7af217345b70bcf06727175d59c7d6dadf92 --- website/content/docs/release-notes/v1_11.mdx | 0 website/data/docs-nav-data.json | 9 +++++++++ 2 files changed, 9 insertions(+) create mode 100644 website/content/docs/release-notes/v1_11.mdx diff --git a/website/content/docs/release-notes/v1_11.mdx b/website/content/docs/release-notes/v1_11.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 396ee9010e3..4820bc42ac0 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -850,6 +850,15 @@ "title": "Configuring Packer", "path": "configure" }, + { + "title": "Release notes", + "routes": [ + { + "title": "v1.11", + "path": "release-notes/v1_11" + } + ] + }, { "divider": true }, From ff4a472b1119045f85bef856428048fffc4a1cc7 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 20:09:46 +0000 Subject: [PATCH 02/24] backport of commit d52159953c0e64929546511c80607994236c2bca --- website/content/docs/release-notes/v1_11.mdx | 37 ++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/website/content/docs/release-notes/v1_11.mdx b/website/content/docs/release-notes/v1_11.mdx index e69de29bb2d..5586f10aba0 100644 --- a/website/content/docs/release-notes/v1_11.mdx +++ b/website/content/docs/release-notes/v1_11.mdx @@ -0,0 +1,37 @@ +--- +page_title: Packer v1.111 release notes +description: Learn about the changes in Packer v 1.11 +--- + +# Packer v1.11 release notes + +This page describes changes to Packer in v1.11. Refer to the [Packer repository](https://github.com/hashicorp/packer/releases) for information about all releases. + +## New features + +This release includes the following updates. + +### Predictable plugin loading + +To boost stability, Packer no longer loads plugin binaries installed outside of its plugin directory. Additionally, Packer now only loads binaries that have accompanying SHA256SUM files. In previous versions, Packer automatically loads plugins placed in one of the known directories when the file is named according to one of the following naming conventions: + +`packer-plugin-` +`packer-plugin-_v0.0.1_x5.0_darwin_arm64` + +Refer to [Installing Plugins](/packer/docs/plugins/install-plugins) for details about how to load plugins. + +## Deprecations + +The following features, workflows, and components are deprecated and are no longer supported. + +### Legacy single-component plugins + +Packer no longer loads single-component plugins, such as legacy plugins that follow the deprecated naming convention of `packer-builder-` or `packer-provisioner--`. Packer only supports multi-component plugins, such as the Docker plugin for Packer. + +### Loading plugin binaries named `packer-plugin-` + +Packer no longer loads plugin binaries following the naming convention of `packer-plugin-`. Packer loads only plugins stored under `PACKER_PLUGIN_PATH` using the expected namespaced directory and CHECKSUM files. + +## Bug fixes + +Fixed an issue with how Packer discovers plugins to ensure proper version ordering. Packer no longer orders plugin versions lexicographically. Instead, Packer now loads versions that have a greater semantic number. For example, version `1.0.9` is lexicographically greater than `1.0.10`, but `1.0.10` is semantically greater than `1.0.9`. This fix results in Packer loading `1.0.10` instead of `1.0.9`. \ No newline at end of file From aed9b484bd44d47743743bbd8d00e759a46c2f9f Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 20:29:51 +0000 Subject: [PATCH 03/24] backport of commit 7faf8bc1946dca642fa38e3c545e654a33e6e2ea --- website/content/docs/commands/init.mdx | 107 +++++++------------------ 1 file changed, 31 insertions(+), 76 deletions(-) diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index 61858f54273..a49c3d5ca19 100644 --- a/website/content/docs/commands/init.mdx +++ b/website/content/docs/commands/init.mdx @@ -1,99 +1,54 @@ --- description: | - The `packer init` Packer command is used to download Packer plugin binaries. -page_title: packer init - Commands + Reference information about the `packer init` command, which downloads and installs Packer one or more plugin binaries specified in a Packer template written in HCL. +page_title: packer init command line reference --- -# `init` Command +# `init` command reference --> **Note:** Packer init does not work with legacy JSON templates. You can -upgrade your JSON template files to HCL using the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) command. +The `packer init` command initializes Packer according to an HCL template configuration. Refer to [Installing Plugins](/packer/docs/plugins/install) for additional information about installing plugins. --> **Note:** Packer init will only work with multi-component plugins -- that is -plugins that are named `packer-plugin-*`. To install a single-component plugin -- -that is `packer-provisioner-*`, `packer-builder-*`, etc. -- nothing changes, you will -have to [install the plugin manually](/packer/docs/plugins#installing-plugins). +## Description -The `packer init` command is used to download Packer plugin binaries. This is -the first command that should be executed when working with a new or existing -template. This command is always safe to run multiple times. Though subsequent -runs may give errors, this command will never delete anything. +Use the `packer init` command to download and install plugins according to the `required_plugins` block in Packer templates written in HCL. Refer to [Specifying plugin requirements](docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) in the template configuration reference for additional information about configuring the `required_plugins` block. -You should invoke `packer init` on either an HCL2 template, or a directory that contains -at least a valid HCL2 template, and eventually other related dependencies like varfiles -for example. +Legacy JSON templates are not supported. You can convert your JSON template files to HCL using the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) command. -Example: +We recommend running the `packer init` command as the first step when working with a new or existing template. You can run the command multiple times. Subsequent runs may produce errors, but the command never deletes already-installed plugins. -```sh -$ ls . -template.pkr.hcl varfile.pkrvars.pkr.hcl +### Third-party plugin verification -$ packer init template.pkr.hcl # You can invoke packer init on a single template in this case - # This works if the template is self-contained, but may fail if - # the template is meant to be built as a bundle of partials. +HashiCorp only verifies plugins from GitHub under the`hashicorp/*` namespace. We recommend that you vet and verify any third-party plugins you want to install. -$ packer init . # Alternatively, you can invoke packer init on a directory instead, - # which behaves the same in a configuration like this one, but if - # the target is a collection ofHCL2 templates, this is the - # preferred way to invoke it. -``` +### Installation location + +By default, Packer installs plugins into the plugins directory at `$HOME/.config/packer/plugins` on Unix and `%APPDATA%\packer.d\plugins` on Windows, but you can specify a different directory using the `PACKER_PLUGIN_PATH` environment variable. Refer to the [Packer configuration reference](/packer/docs/configure) for additional information. -Packer does not currently have the notion of a state like Terraform has. In other words, -currently `packer init` is only in charge of installing Packer plugins. - -Currently, `packer init` can only fetch binaries from public projects on **GitHub**. GitHub's public API, [limits the number of unauthenticated requests -per hour one IP can -do](https://docs.github.com/en/developers/apps/rate-limits-for-github-apps#normal-user-to-server-rate-limits). -Packer will do its best to avoid hitting those limits and in an average local -usage this should not be an issue. Otherwise you can set the -`PACKER_GITHUB_API_TOKEN` env var in order to get more requests per hour. Go to -your personal [access token page](https://github.com/settings/tokens) to -generate a new token. - -`packer init` will list all installed plugins then download the latest versions -for the ones that are missing. - -`packer init -upgrade` will try to get the latest versions for all plugins. - -Install a plugin using the [`required_plugin`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) -block : - -```hcl -packer { - required_plugins { - happycloud = { - version = ">= 2.7.0" - source = "github.com/hashicorp/happycloud" - } - } -} +## Usage +Use the following syntax to run the `packer init` command: + +```shell-session +$ packer init ``` -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. +The template must contain all dependencies when running the command on a single template file. The command fails if the template is intended to be built as a bundle of partials. -## Plugin Selection +## Examples -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/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. +The following example installs the plugins specified in a template named `template.pkr.hcl`: -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. +```shell-session +$ packer init template.pkr.hcl +``` -`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. +## Arguments -Refer to [Installing Plugins](/packer/docs/plugins#installing-plugins) for more information on how plugin installation works. +You can pass the following arguments: + +- Packer template: Specify the path to either an HCL2 template or a directory containing at least one valid HCL2 template and related dependencies. -## Options -- `-upgrade` - On top of installing missing plugins, update installed plugins to - the latest available version, if there is a new higher one. Note that this - still takes into consideration the version constraint of the template. +## Options -- `-force` - Forces reinstallation of plugins, even if already installed. Note - that only the highest installed version matching the template version - constraint will be reinstalled, all other plugins will be left untouched. +- `-upgrade`: Use this option to upgrade plugins that are already installed to the latest available version. Packer upgrades to the latest version in accordance with the version constraints specified in the template. +- `-force`: Use this option to force Packer to reinstall plugins. From f828d3de63a4ceb8459ba79bfc2b961c13a53890 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 20:37:44 +0000 Subject: [PATCH 04/24] backport of commit 4dd5f818fb748ed7b787e9568897a338c5a0f218 --- .../content/docs/commands/plugins/install.mdx | 70 ++++++++++++------- 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/website/content/docs/commands/plugins/install.mdx b/website/content/docs/commands/plugins/install.mdx index 0793aeb20d8..6756891b657 100644 --- a/website/content/docs/commands/plugins/install.mdx +++ b/website/content/docs/commands/plugins/install.mdx @@ -1,38 +1,54 @@ --- description: | - The "plugins install" command installs a Packer plugin. -page_title: plugins Command + Reference information about the `packer plugins install` command which downloads and installs Packer plugin binaries without a Packer template +page_title: packer plugins install command reference --- -# `plugins install` +# `packer plugins install` command reference -The `plugins install` subcommand installs a Packer plugin. +The `packer plugins install` command downloads and installs the most recent version of a plugin binary. Refer to [Installing Plugins](/packer/docs/plugins/install) for additional information about installing plugins. -The requested plugin will be remotely installed by default at its latest version, unless a version -constraint is specified. -The command also supports installing plugins from a locally-sourced binary, along with its -expected source location. +## Description + +Use the `packer plugins install` command to manually install plugins instead of specifying plugins in a template and initializing Packer. Refer to the [`packer init` command documentation](/packer/docs/commands/init) for information about installing plugins specified in a Packer template during initialization. + +### Third-party plugin verification + +HashiCorp only verifies plugins from GitHub under the`hashicorp/*` namespace. We recommend that you vet and verify any third-party plugins you want to install. + +### Installation directory + +By default, Packer installs plugins into the plugins directory at `$HOME/.config/packer/plugins` on Unix and `%APPDATA%\packer.d\plugins` on Windows, but you can specify a different directory using the `PACKER_PLUGIN_PATH environment variable. Refer to the [Packer configuration reference](/packer/docs/configure) for additional information. + +## Usage + +Use the following syntax to run the `packer plugins install` command: + +## Examples + +Specify a version number to install a specific version of the plugin. The following example installs the version `1.0.1` of `my-plugin` from a remote source: ```shell-session -$ packer plugins install -h -Usage: packer plugins install [OPTIONS...] [] - - This command will install the most recent compatible Packer plugin matching - version constraint. When the version constraint is omitted, the most recent - version will be installed. - - Ex: packer plugins install github.com/hashicorp/happycloud v1.2.3 - packer plugins install --path ./packer-plugin-happycloud "github.com/hashicorp/happycloud" - -Options: - -path Install the plugin from a locally-sourced plugin binary. - This installs the plugin where a normal invocation would, but will - not try to download it from a remote location, and instead - install the binary in the Packer plugins path. This option cannot - be specified with a version constraint. - -force Forces reinstallation of plugins, even if already installed. +$ packer plugins install github.com/hashicorp/my-plugin 1.0.0 ``` -## Related +Use the `--path` option to specify a local plugin binary. The following example installs `my-plugin` from a local folder: + +```shell-session +$ packer plugins install --path my-plugin github.com/hashicorp/my-plugin +``` + +## Arguments + +You can pass the following arguments: + +- ``: A local or remote source where the plugin binary is available. To download from a remote source, the plugin must be hosted on GitHub. For local binaries, you must also include the `--path` option. Refer to [Installing Plugins](/packer/docs/plugins/install) for additional information about installing plugins. +- ``: A specific version of the plugin to download and install. Packer accepts semantic version numbers that follow the `..` format. If omitted, the command installs the latest plugin version. + +## Options + +You can use the following options: + +`--path`: Use this option to specify a local plugin binary. You must use this option to install plugins from a local source. +`--force`: Use this option to force Packer to reinstall the plugin. -- [`packer init`](/packer/docs/commands/init) will install all required plugins. From 41c092f3c2145a77fcf07752c57f889a4c2c343b Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 20:57:17 +0000 Subject: [PATCH 05/24] backport of commit b78b9a43f502ab878b81b85cbd482281f15833d0 --- .../templates/hcl_templates/blocks/packer.mdx | 67 ++++--------------- 1 file changed, 13 insertions(+), 54 deletions(-) diff --git a/website/content/docs/templates/hcl_templates/blocks/packer.mdx b/website/content/docs/templates/hcl_templates/blocks/packer.mdx index 8c564e03936..27fbec5d050 100644 --- a/website/content/docs/templates/hcl_templates/blocks/packer.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/packer.mdx @@ -1,8 +1,7 @@ --- -page_title: packer - Blocks +page_title: packer block reference description: |- - The "packer" configuration section is used to configure some behaviors - of Packer itself. + Configuration reference for the `packer` block in Packer templates written in HCL. --- # Packer Settings @@ -78,61 +77,21 @@ This is a great way to pin approved versions of a plugin that can be installed a For more information on plugins, refer to [Plugins](/packer/docs/plugins). -## Source Addresses +### Define plugin source +Specify the path to the plugin source code in the `source` field using the following format: -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. +`/[SUBFOLDER/]/` -At minimum source addresses consist of three parts delimited by slashes (`/`), as -follows: +- ``: Specifies the hostname of the location or service that distributes the plugin. Packer only supports using `github.com` as the hostname when you install plugins using the `packer init` command. You can point to non-GitHub addresses, such as an internal proxy or plugin binary store, but Packer only pins the required version if you install the plugin using the `packer plugins install –path` command. Refer to the following documentation for additional information. + - [`init` command](/packer/docs/commands/init) + - [`plugins install`](/packer/docs/commands/plugins/install) +- ``: The subfolder path segment is an optional part of the address that enables you to download plugin sources from custom addresses. You can specify a source containing up to 13 total path segments. +- ``: 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. --> **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). +For example, the value of the `source` field for a plugin named `myawesomecloud` is `github.com/hashicorp/myawesomecloud` if it belongs to the `hashicorp` namespace on the host `github.com`. -`//` - -- **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. - -### 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 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) -you can use the `packer plugins install --path` command to install the binary with the custom source address and add an entry for it as a required plugin in your template. - -```shellsession -packer plugins install --path path/to/binary mycompany.com/mirror/hashicorp/happycloud -``` - -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 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 indicating that only GitHub source addresses are supported for remote installation. +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. ## Version Constraints From 043d4f00d98ceacec5359a6030a4e929a1a0bf0e Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 21:37:17 +0000 Subject: [PATCH 06/24] backport of commit 54a45f1acf56b9c917f92b9d49d8ded5fb3f7706 --- website/content/docs/configure.mdx | 90 +++++++++++++----------------- 1 file changed, 38 insertions(+), 52 deletions(-) diff --git a/website/content/docs/configure.mdx b/website/content/docs/configure.mdx index fb0c247c91a..28917dc64b2 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -1,87 +1,73 @@ --- description: | - There are various ways to configure Packer. By default Packer will use known folders, - which can be changed by using environment variables. + Learn how to use environment variables when running Packer that configure global behaviors. page_title: Configuring Packer --- # Configuring Packer --> **Note:** There are a few configuration settings that affect Packer globally -by configuring the core of Packer. These settings all have reasonable defaults, -so you generally don't have to worry about it until you want to tweak a -configuration. If you're just getting started with Packer, don't worry about -core configuration for now. +This topic describes how to configure Packer. The default configurations are suitable for learning how to get started, but you should refer to this topic for guidance as you become more familiar with Packer. -## Packer's config directory +## Overview -Packer's configuration directory can potentially contain plugins and internal -Packer files. The Packer config directory will be looked up on the following paths: +You can set Packer-specific environment variables in a configuration file to configure Packer behavior globally. Install configuration files in the Packer configuration directory to implement the configurations. You can also install plugin files and their SHA256SUM files to the plugins subdirectory under the configuration directory. Refer to [Installing Plugins](/plugins/install) for instructions. -| Unix | Windows | -| --------------------------- | --------------------------- | -| `${HOME}/.config/packer/` | `%APPDATA%\packer.d\` | +You can also define Packer settings in a JSON configuration file and add it to the execution path. This configuration method is deprecated. --> **Note:** On Unix systems, Packer defaults to using the XDG base directory specification. -When the environment variable `PACKER_CONFIG_DIR` is unset or empty a default equal to `$HOME/.config/packer` should be used. -In all other cases, where there is an existing older style `.packer.d` directory (e.g `$HOME/.packer.d/`) or PACKER_CONFIG_DIR is not empty -the older configuration directory will be used. +## Install a configuration file -Examples: +You can place internal configuration files into Packer's `config` directory. Packer checks the following paths for configuration files: + +| OS | Path | Notes | +| --- | ---| --- | +| Unix | `${HOME}/.config/packer/` | Packer follows the XDG base directory specification by default. As a result, Packer uses `$HOME/.config/packer` as the default directory when the `PACKER_CONFIG_DIR` environment variable is unset or empty. Packer ignores the XDG specification when the `PACKER_CONFIG_DIR` variable is set or when the installation uses `.packer.d`-style directories, for example `$HOME/.packer.d/`. Refer to the [XDG specification](https://specifications.freedesktop.org/basedir-spec/latest/) for additional information. | +| Windows | `%APPDATA%\packer.d\` | | + + +### Examples + +- **Unix**: If `$PACKER_CONFIG_DIR` is set to `/home/packer`, then the configuration directory is `/home/packer/.packer.d/`. Packer does not check other values. +- **Windows**: If `PACKER_CONFIG_DIR` is set to `C:/`, then the configuration directory is `C:/packer.d/`. Packer does not check other values. -- On a Unix system, if the `$PACKER_CONFIG_DIR` environment variable is set to - `/home/packer`, the config directory will be: `/home/packer/.packer.d/` and - other values will not be checked. -- On a Windows system, if the `PACKER_CONFIG_DIR` environment variable is set to `C:/`,the - config directory will be: `C:/packer.d/` and other values will not be checked. -## Packer's config file (deprecated) +## Install a JSON configuration file + +This installation method is deprecated since 1.7. Instead, use the [HCL2 +`required_plugins` block](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) to configure how Packer installs plugins. -Packer can optionally read a JSON file for the end user to set core settings. -The config file of Packer will be looked up on the following paths: +You use a JSON file to set core Packer settings. Packer checks the following paths for the configuration file: | Unix | Windows | | -------------------------------- | --------------------------------- | | `${PACKER_CONFIG}` | `%PACKER_CONFIG%` | | `${HOME}/.packerconfig` | `%APPDATA%\packer.config\` | -The format of the configuration file is basic JSON. -### Packer config file configuration Reference +### JSON configuration file reference + +Use basic JSON to configure the file. You can specify the configuration parameters for the core +configuration file. All parameters are optional. None of these are required, since all have defaults. -Below is the list of all available configuration parameters for the core -configuration file. None of these are required, since all have defaults. +- `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP connections on your local host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. +- `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP connections on your local host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. +- `builders`: Specifies a type of object that installs plugins. Refer to [Builders](/packer/docs/builders) for additional information. +- `commands`: Specifies a type of object that installs plugins. +- `post-processors`: Specifies a type of object that installs plugins. Refer to [Post-Processors](/packer/docs/post-processors) for additional information. +- `provisioners`: Specifies a type of object that installs plugins. Refer to [Provisioners](/packer/docs/provisioners) for additional information. -- `plugin_min_port` and `plugin_max_port` (number) - These are the minimum - and maximum ports that Packer uses for communication with plugins, since - plugin communication happens over TCP connections on your local host. By - default these are 10,000 and 25,000, respectively. Be sure to set a fairly - wide range here, since Packer can easily use over 25 ports on a single run. +The [`packer init`](/packer/docs/commands/init) command takes precedence over JSON-configure settings when installing plugins. -- `builders`, `commands`, `post-processors`, and `provisioners` are objects - that are used to install plugins. The details of how exactly these are set is - covered in more detail in the [installing plugins documentation - page](/packer/docs/plugins/install-plugins). It is instead recommended to use [HCL2 - `required_plugins`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) - and the [`packer init`](/packer/docs/commands/init) command to install plugins; if - you are using both, the `required_plugin` config will take precedence. -## Packer's plugin directory +## Configure the cache directory -@include "plugins/plugin-location.mdx" +Packer uses a cache directory to download large files and for logistics around large file download. By default, Packer caches files in the `./packer_cache/` folder of the current directory. Use the `PACKER_CACHE_DIR` environment variable to configure the cache directory. Refer to [`PACKER_CACHE_DIR`](/packer/docs/configure#packer_config_dir) for details. -## Packer's cache directory +We recommend using the same Packer cache directory across your builds if multiple builds perform similar actions. This is to avoid downloading the same large file, such as an ISO, multiple times. -Packer uses a cache directory to download large files and for logistics around -large file download. By default, Packer caches things in the current directory, -under: `./packer_cache/`. This can be changed by setting the `PACKER_CACHE_DIR` -env var. It is recommended to share the same Packer cache directory across your -builds if you have multiple builds doing similar things to avoid downloading the -same ISO twice for example. -## Environment Variables usable for Packer +## Configuration reference Packer uses a variety of environmental variables. A listing and description of each can be found below: From 46c6b294b79aad4e41bb7a9f3766dd6e6c85e989 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 21:42:11 +0000 Subject: [PATCH 07/24] backport of commit e6ea5d0900565410bed8b4cf1631f961b2ddec84 --- website/content/docs/plugins/index.mdx | 49 +++++++++++++++++++------- 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index 4a11840d1b9..94d2b142b09 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -1,21 +1,46 @@ --- description: | - Packer plugins let you add Packer functionality without modifying - the core source code. Packer plugins are able to add new builders, - provisioners, hooks, and more. + This topic provides overview information about installing and loading Packer plugins page_title: Plugins --- -# Packer Plugins +# Plugin installation overview -Packer plugins are separate, standalone applications that perform tasks during each build. +This topic provides overview information about installing and loading Packer plugins. Plugins are standalone applications that perform additional tasks during each build. -During a `packer build`, the process list shows `packer-` prefixed applications. One of those applications is the Packer binary, and the rest are plugins. Packer launches one plugin process for each component in the build. +## Introduction -The Packer binary has a set of built-in plugins that it can find and run automatically. You can also define a list of external plugins in your template for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code. +The Packer binary includes a set of built-in plugins that run automatically, but you also define a list of external plugins in your template for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code. Packer launches one plugin process for each component in the build. -Refer to the following plugin documentation: -- **Built-in Plugins:** Use [builders](/packer/docs/builders) to create machines and images, [data sources](/packer/docs/datasources) to fetch data, [provisioners](/packer/docs/provisioners) to install and configure machine images, and [post-processors](/packer/docs/post-processors) to perform additional tasks after provisioning -- **External Plugins:** Review the documentation for [available external plugins](/packer/plugins) not included with the Packer binary -- **Installing Plugins:** [Installation Guides](/packer/docs/plugins/install-plugins) to add external plugins to your Packer template and install the binaries -- **Developing Plugins:** Get started [creating custom external plugins](/packer/docs/plugins/creation) \ No newline at end of file +## Workflows + +To use a plugin with Packer, you must install the plugin code and its SHA256SUM file into the Packer plugins directory. Refer to [Installing Plugins](/packer/docs/plugins/install) for instructions. + +## Where Packer stores plugins + +Packer stores external plugins that are downloaded during initialization into the plugins directory. The default plugins directory is `$HOME/.config/packer/plugins` on Unix and `%APPDATA%\packer.d\plugins` on Windows. Refer to [`PACKER_PLUGIN_PATH`](/packer/docs/configure#packer_plugin_path) in the configuration reference for additional information. + +## Guidance + +Refer to the following plugin documentation for details about the plugin installation process: + +### Installing plugins + +Refer to [Installing Plugins](/packer/docs/plugins/install) for instructions on adding external plugins to your Packer template and installing the binaries. + +### External plugins + +Refer to the [Packer Integrations](/packer/integrations) documentation to learn about the available external plugins not included with the Packer binary. + + +### Built-in plugins + +- Packer uses plugins called _builders_ to create machines and images. Refer to [Builders](/packer/docs/builders) for additional information. +- The _data sources_ plugin fetches data to use in a template. Refer to [Data Sources](/packer/docs/datasources) for additional information. +- Plugins called _provisioners_ install and configure machine images after booting. Refer to [Provisioners](/packer/docs/provisioners) for additional information. +- _Post-processors_ perform additional tasks after provisioning. Refer to [Post-Processors](/packer/docs/post-processors) for additional information. + + +### Developing plugins + +Refer to the [Developing Plugins](/packer/docs/plugins/creation) to learn how to create custom external plugins. From 5cb18b0a1597163280df525c31dbb03697ac8133 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 22:15:44 +0000 Subject: [PATCH 08/24] backport of commit d60bb25687b138ae824c01f5ce77c60e4af75a1f --- .../content/docs/plugins/install-plugins.mdx | 298 ++++++++---------- 1 file changed, 128 insertions(+), 170 deletions(-) diff --git a/website/content/docs/plugins/install-plugins.mdx b/website/content/docs/plugins/install-plugins.mdx index 93032676b99..f5ee9a9f2bb 100644 --- a/website/content/docs/plugins/install-plugins.mdx +++ b/website/content/docs/plugins/install-plugins.mdx @@ -6,234 +6,192 @@ page_title: Install Plugins # Installing Plugins -Packer plugins are separate, standalone applications that perform tasks during each build. +This topic describes how to install external plugins for Packer. Refer to [Packer Plugins Overview](/packer/docs/plugins) for additional information about plugins. -This page explains how to install external plugins. Refer to [Integrations](/packer/integrations) for a list of available plugins and their documentation. +## Overview -Depending on the template type you're using (HCL2 or legacy JSON), the methods for installing plugins may differ. +Specify one or more required plugins in a Packer template and run the initialization command. During initialization, Packer queries the source repository for plugins specified in the template that match the version constraints for the host operating system. Packer downloads and installs plugins and other dependencies specified in the template. -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. +You can specify a remote project on GitHub for Packer to install the plugin from. Refer to [Requirements](#requirements) for additional information about installing plugins from a remote source. -`packer plugins install` is also used 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. +When you run the Packer template, Packer first checks the directory for installed plugins that match the version requirements specified in the template. If a suitable version of the plugin is not installed, Packer prints an error. Packer downloads the required version from the `source` configuration. -While `packer plugins install` is able to install plugins remotely, you can use -the `--path` flag to install locally-sourced plugin binaries. -This is typically useful in two general cases: +### Manual installation method -1. You are in an environment with restricted access to a plugin's source. -1. You are trying to install a development version of a plugin for testing. +You can manually install plugins if you are unable to specify plugins in an HCL template file. You may need to use the manual plugin installation method if the plugin source is a non-GitHub project or if your plugins are still in development. -Refer to the [Installation Guides](#installation-guides) section of this page for information about -each method, including usage examples. +Manually install a plugin using the `packer plugins install` command. You specify a local or remote plugin source and include a path to the binary to generate the SHA256SUM file required to load the plugin during Packer builds. Refer to [Requirements](#requirements) for additional information about installing plugins from a remote source. -The remainder of this document documents how Packer interacts with plugins. -We encourage you to read this to get familiar with this process, as it will help you troubleshoot -builds if you encounter problems with plugins. +Note that Packer checks the plugin installation directory against the `required_plugins` block in the Packer template when you build artifacts using the template. Plugins specified in the template that have been installed manually must still comply with the version constraints set in the template. -## Source Addresses -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. -This source translates directly to the file hierarchy in which the plugin binaries will be -installed. +### Installation directory -Source addresses are a URL, without a scheme (e.g. `"https://"`), query (e.g. `?arg=val`), or -fragment (e.g. `#anchor`). +By default, Packer installs plugins into the plugins directory at `$HOME/.config/packer/plugins` on Unix and `%APPDATA%\packer.d\plugins` on Windows, but you can specify a different directory using the `PACKER_PLUGIN_PATH environment variable. Refer to the [Packer configuration reference](/packer/docs/configure) for additional information. -Example: `github.com/hashicorp/happycloud` +## Requirements -#### Github sources +To install a plugin from a remote source, the plugin must meet the following requirements: -Github sources all follow this convention: `//`. +- The plugin project must be hosted on GitHub. +- The repository must be named `packer-plugin-`. +- The project must have semantic version tags per the following format: `v..`. +- The release linked to the tag must be available with a `shasums` file that indicates which files are available in the release. -- **Hostname:** The hostname of the location/service that distributes the plugin. +### GitHub API token -- **Namespace:** An organizational namespace within the specified host. - This often is the organization that maintains the plugin. +GitHub's public API limits the number of unauthenticated requests per hour from a single IP address. Refer to the [GitHub rate limits documentation](https://docs.github.com/en/developers/apps/rate-limits-for-github-apps#normal-user-to-server-rate-limits) for additional information. -- **Type:** A short name for the platform or system the plugin manages. The - type is usually the plugin's preferred local name. +If you expect to exceed the request rate limit, you can use a GitHub API token to authenticate requests and exceed the rate limit. We recommend setting a GitHub API token when running Packer from a continuous integration server to avoid potential rate limiting errors. Refer to [Authenticate requests to the GitHub API](#authenticate-requests-to-the-github-api) for instructions. -For example, the fictional `happycloud` plugin could belong to the -`hashicorp` namespace on `github.com`, so its `source` could be -`github.com/hashicorp/happycloud`, +## Install a plugin --> Note: the actual _repository_ that happycloud comes from must always have -the name format `github.com/hashicorp/packer-plugin-happycloud`, but the -source voluntarily omits the redundant `packer-plugin-` prefix for brevity. +1. In your Packer template file, add the `required_plugins` block to the `packer` block. +1. Specify the name of the plugin and its `version` and `source` parameters. Setting a correct [version constraint string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints) is important for +pinning plugin versions for build reproducibility. Refer to the [`packer` block configuration reference](/packer/docs/templates/hcl_templates/blocks/packer) for additional information. -The source address with all the components given explicitly is called the -plugin's _fully-qualified address_. You will see fully-qualified addresses in -various outputs, like error messages. + The following example configures Packer to install a plugin called `happycloud`. When the template is initialized, Packer downloads version 2.7.0 or newer of the plugin from GitHub: -### Source and local hierarchy - -As mentioned above, each source URL will directly impact how Packer will install -a plugin to the local plugin directory. -Each component of the path described will become a subdirectory, and finally, -plugin binaries are installed at the end of that hierarchy. -Multiple versions can be installed along one another. + ```hcl + packer { + required_plugins { + happycloud = { + version = ">= 2.7.0" + source = "github.com/hashicorp/happycloud" + } + } + } + + ``` -In order for the binaries installed in this directory to be discovered and used -by Packer, they must follow this set of rules: +1. Run the `packer init` command. Packer lists all installed plugins then installs the latest plugin version matching the version constraints specified in the `required_plugins` block. Refer to the [`init` command reference](/packer/docs/commands/init) for additional information. -1. The name of the binary must be in the `packer-plugin-__x__(.exe)?` format -1. The binary must be accompanied by a SHA256SUM file, which must contain the SHA256 hash of the binary -1. The `describe` command of the binary must return informations that match the plugin's name, namely: +## Manually install plugins using the CLI - a. The plugin version must match the name +You can use the `packer plugins install` command to manually install remote plugins. Include the `--path` flag and specify a local source so that Packer automatically calculates the SHA256SUM file and installs the files into the Packer plugin directory: - b. The API version must match the name's +```shell-session +$ packer plugins install --path // +``` -1. The version must be canonical: e.g. 1.0.1 (valid) vs. 01.000.01 (invalid) -1. The version must be valid semver (e.g. 1.0.0) -1. Pre-releases are accepted, but must be `-dev` only. -1. Metadata shall not be in the name of the plugin binary, only metadata-free versions will be considered valid for discovery purposes. +The following example installs the `happycloud` plugin from GitHub: -## Plugin Discovery Workflow +```shell-session +$ packer plugins install --path happycloud github.com/hashicorp/happycloud +``` -At initialization, Packer attempts to discover the plugins installed locally. The -logic follows what's described in Configuring Packer's -[plugin directory](/packer/docs/configure#packer-s-plugin-directory) -section. +Refer to the [`packer plugins install`](/packer/docs/commands/plugins/install) reference for additional information. -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: [...] -``` +## Upgrade plugins -Once this discovery step has finished, each discovered plugin will be ready to use -by Packer, on the highest available version. +To upgrade plugins that are already installed, run the `packer init` with the `--upgrade` flag. Packer retrieves the latest versions of installed plugins specified in the template configuration. -Example: +The following example upgrades plugins according to the template in the current directory: -```shell - -└── github.com - └── hashicorp - └── happycloud - ├── packer-plugin-happycloud_v1.1.8_x5.0_linux_amd64 - ├── packer-plugin-happycloud_v1.1.8_x5.0_linux_amd64_SHA256SUM - ├── packer-plugin-happycloud_v1.2.8_x5.0_linux_amd64 - └── packer-plugin-happycloud_v1.2.8_x5.0_linux_amd64_SHA256SUM +```shell-session +$ packer init --upgrade . ``` -In this example, the `happycloud` plugin will be the one and used to serve -happycloud-related components, in version 1.2.8. +Refer to [`packer init` command](/packer/docs/commands/init) for additional information. -### HCL2 and `required_plugins` +## Install a plugin under development -The aforementioned logic is all that can apply to legacy JSON templates. -HCL2 however introduces the concept of `required_plugins` blocks. -These blocks allow you to declare what plugins your template needs in order -to be able to build an artifact, along with version constraints. +You can install and use plugins that are still under development and report as `dev` versions. But if a non-development version of the plugin binary is available, Packer installs the non-development version according to the version constraints configured in the Packer template and uses it in the build. -Example: +If a development binary, such as a manually-built binary, is available at the specified source, Packer uses it in the build if it is the highest compatible version installed and if no final plugin version with the same version number is installed alongside it. -```hcl2 -packer{ - required_plugins { - happycloud = { - source = "github.com/hashicorp/happycloud" - version = "= 1.1.8" - } - } -} -``` +In the following example, version `1.1.0` or newer is required: -With this constraint specified, Packer will not only be able to remotely install -the plugin you need with `packer init` (provided it is hosted on a remote that the command -supports), but also restrict which versions can be used for building the template. +```hcl +packer = { + required_plugins = { + amazon = { + source = "github.com/hashicorp/amazon" + version = ">= 1.1.0" + } + } -Using the aforementioned plugin hierarchy, a constraint like the one above will -take precedence over the usual discovery process, this time yielding version 1.1.8 -of the happycloud plugin for serving its components. +. . . -## Installation Guides +} +``` -### Packer init +Packer uses the `-dev` version of the Amazon plugin if the following binaries are available: + +```shell-session +/Users/dev/.packer.d/plugins +└─ github.com + └─ hashicorp + └── amazon + ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64 + ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64_SHA256SUM + ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64 + └── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM +``` --> Using `packer init` requires using HCL2 templates. If you are using JSON and - want to start using HCL2 templates in order to leverage this feature, please - refer to our [JSON to HCL](/packer/docs/templates/json_to_hcl) guide. +When a non-development version of 1.1.1 becomes available, the binary takes precedence over the development binary: + +```shell-session +/Users/dev/.packer.d/plugins +└─ github.com + └─ hashicorp + └── amazon + ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64 + ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM + ├── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64 + └── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64_SHA256SUM +``` -In order to use `packer init` for managing installation of your plugins, there are -two steps required. +Refer to the documentation in the [Packer plugin scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding?tab=readme-ov-file#build-from-source) for additional information. -First, add a [`required_plugins`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) -block to your [packer block](/packer/docs/templates/hcl_templates/blocks/packer). +### Example Docker plugin -Each block will tell Packer what version(s) of a particular plugin can be installed. -Make sure to set a valid -[version constraint string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints). +Complete the following steps to build and install a custom version of the Docker plugin as an example: -Here is an example `required_plugins` block: +1. Clone the plugin's GitHub repository. -```hcl -packer { - required_plugins { - myawesomecloud = { - version = ">= 2.7.0" - source = "github.com/hashicorp/myawesomecloud" - } - happycloud = { - version = ">= 1.1.3" - source = "github.com/hashicorp/happycloud" - } - } -} -``` + ```shell-session + $ git clone https://github.com/hashicorp/packer-plugin-docker.git + ``` + +1. Change to the plugin directory root and run the `go build` command to build the plugin as a development binary. -Once your template contains those `required_plugins`, run -[`packer init`](/packer/docs/commands/init) to install all missing plugin -binaries. -Given the above example, Packer will try to look for a GitHub -repository owned by user or organization `hashicorp` named -`packer-plugin-myawesomecloud` and `packer-plugin-happycloud`. + ```shell-session + $ cd packer-plugin-docker + $ go build -ldflags="-X github.com/hashicorp/packer-plugin-docker/version.VersionPrerelease=dev" -o packer-plugin-docker-dev + ``` --> Note: `packer init` tries to install plugins matching the version constraints required by the template. - Running `packer init` multiple times on the same template will result in no changes if all matching plugins - have already been installed. If you want to update a plugin or force re-installation, you may use the - `--update` or `--force` arguments. +1. Validate the release version. -### Packer plugins install + ```shell-session + $ ./packer-plugin-docker-dev describe + {"version":"1.0.10-dev","sdk_version":"0.5.2","api_version":"x5.0","builders":["-packer-default-plugin-name-"],"post_processors":["import","push","save","tag"],"provisioners":[],"datasources":[]} + ``` -Plugin installation via `packer plugins install` works similar to that of the `packer init` command, but -no `required_plugins` block are required. +1. Use the `packer plugins install` command to install the development binary. -```shell -packer plugins install github.com/hashicorp/vagrant -``` + ```shell-session + packer plugins install --path packer-plugin-docker-dev github.com/hashicorp/docker + Successfully installed plugin github.com/hashicorp/docker from $HOME/Development/packer-plugin-docker/packer-plugin-docker-dev to ~/github.com/hashicorp/docker/packer-plugin-docker_v1.0.10-dev_x5.0_darwin_arm64 + ``` --> You can only install one plugin per invocation of the command. If you need to install - a specific version of a plugin, you can specify a version to install as an optional - argument to the command line. - e.g.: `packer plugins install "github.com/hashicorp/vagrant" "v1.0.1"` +1. Run a `packer build` with the newly installed plugin. -The command will install the plugin in the `PACKER_CONFIG_DIR` set, or its -default location, which depends on the OS/environment, as documented in -[Configuring Packer](/packer/docs/configure#packer-s-plugin-directory). + ```shell-session + $ packer build . + ``` -#### Using packer plugins install to install a local copy of a binary +For convenience, the makefile in the Packer plugin scaffolding repository builds and installs development binaries using `make dev`. -If the plugin you want to install cannot be installed remotely, you can use the -`--path` argument for `packer plugins install` in order to use the provided -plugin binary as source. +## Authenticate requests to the GitHub API -Example: +You can set the `PACKER_GITHUB_API_TOKEN` environment variable to send more requests per hour than the limits imposed by the GitHub API: -```shell -$ ls -l packer-plugin-happycloud --rwxrwxr-x 1 root root 44745210 Jan 01 1979 packer-plugin-happycloud -$ PACKER_PLUGIN_PATH=/root/plugins packer plugins install --path ./packer-plugin-happycloud "github.com/hashicorp/happycloud" -Successfully installed plugin github.com/hashicorp/happycloud from /root/packer-plugin-happycloud to /root/plugins/github.com/hashicorp/happycloud/packer-plugin-happycloud_v1.2.8-dev_x5.0_linux_amd64 -``` +1. Go to your personal [access token page](https://github.com/settings/tokens) to +generate a new token. +1. Set the `PACKER_GITHUB_API_TOKEN` environment variable to your token value: --> Note: the version does not need to be specified, Packer will automatically - determine which version to install based on the plugin's `describe` output. + ```shell-session + $ export PACKER_GITHUB_API_TOKEN= + ``` \ No newline at end of file From dbc716afa4d41ede4cd11a83bbd7e1ab878faa67 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 22:21:31 +0000 Subject: [PATCH 09/24] backport of commit e6a40238f76701877d6d3a8bddfb470c9a4c3c60 --- website/content/docs/upgrade/v1_11.mdx | 0 website/data/docs-nav-data.json | 9 +++++++++ 2 files changed, 9 insertions(+) create mode 100644 website/content/docs/upgrade/v1_11.mdx diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 4820bc42ac0..dfff8889c4f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -859,6 +859,15 @@ } ] }, + { + "title": "Upgrades", + "routes": [ + { + "title": "Upgrade to v1.11", + "path": "upgrade/v1_11" + } + ] + }, { "divider": true }, From a7ecbb7647f89d6baa42deddf6bfc69a59b28fb7 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 22:51:08 +0000 Subject: [PATCH 10/24] backport of commit 5ba4f885e44d4aec346069113999e1fde3830039 --- website/content/docs/upgrade/v1_11.mdx | 29 ++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx index e69de29bb2d..8b9343bb13a 100644 --- a/website/content/docs/upgrade/v1_11.mdx +++ b/website/content/docs/upgrade/v1_11.mdx @@ -0,0 +1,29 @@ +--- +page_title: Upgrade to v1.11 +description: Learn how to upgrade your Packer installation to v1.11 +--- + +# Upgrade to v1.11 + +This topic describes how to upgrade to v1.11. Refer to the [Packer v1.11 release notes](/packer/docs/release-notes/v1_11) for information about changes in v1.11 from the previous release. + +## Requirements + + + +## Upgrade from v1.10 + + + +## Upgrade from a version older than v1.10 + + + +## Troubleshooting + +This section provides guidance on potential issues you may experience after upgrading + +### Missing plugins error + +Packer may report that you one or more plugins are missing after the upgrade. You may need to reinstall the plugins as described in [Installing Plugins](/packer/docs/plugins/install). + From 24502043d478a458282f3ec1d1ceab542379e6e8 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 22:55:31 +0000 Subject: [PATCH 11/24] backport of commit 0cdaab6474cfd241f6b882f551706abdf514e649 --- website/content/docs/upgrade/v1_11.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx index 8b9343bb13a..c6ddc5ac40d 100644 --- a/website/content/docs/upgrade/v1_11.mdx +++ b/website/content/docs/upgrade/v1_11.mdx @@ -9,15 +9,15 @@ This topic describes how to upgrade to v1.11. Refer to the [Packer v1.11 release ## Requirements - +[comment]: < > (Delete this section if there is no content for it) ## Upgrade from v1.10 - - +[comment]: < > (Describe the steps) + ## Upgrade from a version older than v1.10 - +[comment]: < > (Delete this section if there is no content for it) ## Troubleshooting From 45f2d01bae6ed4935a139043e968b42c0ac94eb7 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 24 May 2024 23:04:08 +0000 Subject: [PATCH 12/24] backport of commit bb83c82d4895267443ddbcd48930ae54dcc1f961 --- website/content/docs/community-tools.mdx | 2 +- website/content/docs/plugins/creation/custom-builders.mdx | 2 +- website/content/docs/plugins/creation/index.mdx | 2 +- .../docs/plugins/{install-plugins.mdx => install.mdx} | 0 website/content/docs/release-notes/v1_11.mdx | 2 +- website/redirects.js | 5 +++++ 6 files changed, 9 insertions(+), 4 deletions(-) rename website/content/docs/plugins/{install-plugins.mdx => install.mdx} (100%) diff --git a/website/content/docs/community-tools.mdx b/website/content/docs/community-tools.mdx index 3a222f17a75..b984fb61d78 100644 --- a/website/content/docs/community-tools.mdx +++ b/website/content/docs/community-tools.mdx @@ -19,7 +19,7 @@ vendors. These plugins are not officially tested nor officially maintained by HashiCorp, and are listed here in order to help users find them easily. To learn more about how to use community plugins, or how to build your own, -check out the docs on [extending Packer](https://developer.hashicorp.com/packer/docs/plugins/install-plugins) +check out the docs on [extending Packer](/packer/docs/plugins/install) If you have built a plugin and would like to add it to this community list, please make a pull request so that we can document your diff --git a/website/content/docs/plugins/creation/custom-builders.mdx b/website/content/docs/plugins/creation/custom-builders.mdx index fbc303ca9d9..230d9596aad 100644 --- a/website/content/docs/plugins/creation/custom-builders.mdx +++ b/website/content/docs/plugins/creation/custom-builders.mdx @@ -306,5 +306,5 @@ order to make it available to the Packer core as a plugin. We have created a [scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/builder/scaffolding/builder.go) repo to give you an idea of the relationship between the builder implementation and the server implementation within a repository, and then read -[basics of how Plugins work](/packer/docs/plugins/install-plugins), which breaks down all the +[basics of how Plugins work](/packer/docs/plugins/install), which breaks down all the server details. diff --git a/website/content/docs/plugins/creation/index.mdx b/website/content/docs/plugins/creation/index.mdx index 763877aa0fe..ddf2e10bd47 100644 --- a/website/content/docs/plugins/creation/index.mdx +++ b/website/content/docs/plugins/creation/index.mdx @@ -9,7 +9,7 @@ page_title: Extending # Developing Plugins Packer is extensible and supports plugins that let you -create and use custom builders, provisioners, post-processors, and data sources. This page explains how to develop Packer plugins. Before you begin, we recommend reviewing the Packer documentation and the instructions for [installing external plugins](https://developer.hashicorp.com/packer/docs/plugins/install-plugins). +create and use custom builders, provisioners, post-processors, and data sources. This page explains how to develop Packer plugins. Before you begin, we recommend reviewing the Packer documentation and the instructions for [installing external plugins](/packer/docs/plugins/install). ~> **Warning** This is an advanced topic. You should have strong knowledge of Packer before you start writing plugins. diff --git a/website/content/docs/plugins/install-plugins.mdx b/website/content/docs/plugins/install.mdx similarity index 100% rename from website/content/docs/plugins/install-plugins.mdx rename to website/content/docs/plugins/install.mdx diff --git a/website/content/docs/release-notes/v1_11.mdx b/website/content/docs/release-notes/v1_11.mdx index 5586f10aba0..29449003864 100644 --- a/website/content/docs/release-notes/v1_11.mdx +++ b/website/content/docs/release-notes/v1_11.mdx @@ -18,7 +18,7 @@ To boost stability, Packer no longer loads plugin binaries installed outside of `packer-plugin-` `packer-plugin-_v0.0.1_x5.0_darwin_arm64` -Refer to [Installing Plugins](/packer/docs/plugins/install-plugins) for details about how to load plugins. +Refer to [Installing Plugins](/packer/docs/plugins/install) for details about how to load plugins. ## Deprecations diff --git a/website/redirects.js b/website/redirects.js index 7d56c6e4719..05458574d20 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -86,6 +86,11 @@ module.exports = [ destination: '/packer/docs/templates/hcl_templates/functions', permanent: true, }, + { + source: '/packer/docs/plugins/install-plugins', + destination: '/packer/docs/plugins/install', + permanent: true, + }, /** * END EMPTY PAGE REDIRECTS */ From 5f02f3770587d81cfdb0706a9d79755db297b32c Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Tue, 28 May 2024 15:30:37 +0000 Subject: [PATCH 13/24] backport of commit 3eb6e1ebe50a1fd492c605a9a7ec9a9a7e45e47b --- website/content/docs/commands/init.mdx | 4 ++-- website/content/docs/commands/plugins/install.mdx | 4 ++-- website/content/docs/configure.mdx | 4 ++-- website/content/docs/plugins/index.mdx | 2 +- website/content/docs/release-notes/v1_11.mdx | 6 +++--- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index a49c3d5ca19..85090eecab6 100644 --- a/website/content/docs/commands/init.mdx +++ b/website/content/docs/commands/init.mdx @@ -18,11 +18,11 @@ We recommend running the `packer init` command as the first step when working wi ### Third-party plugin verification -HashiCorp only verifies plugins from GitHub under the`hashicorp/*` namespace. We recommend that you vet and verify any third-party plugins you want to install. +We recommend that you vet and verify any third-party plugins you want to install. ### Installation location -By default, Packer installs plugins into the plugins directory at `$HOME/.config/packer/plugins` on Unix and `%APPDATA%\packer.d\plugins` on Windows, but you can specify a different directory using the `PACKER_PLUGIN_PATH` environment variable. Refer to the [Packer configuration reference](/packer/docs/configure) for additional information. +By default, Packer installs plugins into the plugins directory at `$HOME/.config/packer/plugins` on Unix and `%APPDATA%\packer.d\plugins` on Windows, but you can specify a different directory using the `PACKER_PLUGIN_PATH` environment variable. Refer to the [Packer configuration reference](/packer/docs/configure) for additional information. ## Usage Use the following syntax to run the `packer init` command: diff --git a/website/content/docs/commands/plugins/install.mdx b/website/content/docs/commands/plugins/install.mdx index 6756891b657..f3dafc819df 100644 --- a/website/content/docs/commands/plugins/install.mdx +++ b/website/content/docs/commands/plugins/install.mdx @@ -32,7 +32,7 @@ Specify a version number to install a specific version of the plugin. The follow $ packer plugins install github.com/hashicorp/my-plugin 1.0.0 ``` -Use the `--path` option to specify a local plugin binary. The following example installs `my-plugin` from a local folder: +Use the `--path` option to specify a local plugin binary. The following example installs `my-plugin` from a local binary: ```shell-session $ packer plugins install --path my-plugin github.com/hashicorp/my-plugin @@ -42,7 +42,7 @@ $ packer plugins install --path my-plugin github.com/hashicorp/my-plugin You can pass the following arguments: -- ``: A local or remote source where the plugin binary is available. To download from a remote source, the plugin must be hosted on GitHub. For local binaries, you must also include the `--path` option. Refer to [Installing Plugins](/packer/docs/plugins/install) for additional information about installing plugins. +- ``: A remote source where the plugin binary is available. To remotely download from a source, the plugin must be hosted on GitHub. For locally-sourced binaries, you must also include the `--path` option. Refer to [Installing Plugins](/packer/docs/plugins/install) for additional information about installing plugins. - ``: A specific version of the plugin to download and install. Packer accepts semantic version numbers that follow the `..` format. If omitted, the command installs the latest plugin version. ## Options diff --git a/website/content/docs/configure.mdx b/website/content/docs/configure.mdx index 28917dc64b2..6887453ddf2 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -20,7 +20,7 @@ You can place internal configuration files into Packer's `config` directory. Pac | OS | Path | Notes | | --- | ---| --- | -| Unix | `${HOME}/.config/packer/` | Packer follows the XDG base directory specification by default. As a result, Packer uses `$HOME/.config/packer` as the default directory when the `PACKER_CONFIG_DIR` environment variable is unset or empty. Packer ignores the XDG specification when the `PACKER_CONFIG_DIR` variable is set or when the installation uses `.packer.d`-style directories, for example `$HOME/.packer.d/`. Refer to the [XDG specification](https://specifications.freedesktop.org/basedir-spec/latest/) for additional information. | +| Unix | `${HOME}/.config/packer/` | Packer follows the XDG base directory specification by default. As a result, Packer uses `$HOME/.config/packer` as the default directory when the `PACKER_CONFIG_DIR` environment variable is unset or empty. Packer ignores the XDG specification when the `PACKER_CONFIG_DIR` variable is set or when the installation uses legacy `.packer.d`-style directories, for example `$HOME/.packer.d/`. Refer to the [XDG specification](https://specifications.freedesktop.org/basedir-spec/latest/) for additional information. | | Windows | `%APPDATA%\packer.d\` | | @@ -51,7 +51,7 @@ Use basic JSON to configure the file. You can specify the configuration paramete configuration file. All parameters are optional. None of these are required, since all have defaults. - `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP connections on your local host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. -- `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP connections on your local host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. +- `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP connections on your local Unix host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. - `builders`: Specifies a type of object that installs plugins. Refer to [Builders](/packer/docs/builders) for additional information. - `commands`: Specifies a type of object that installs plugins. - `post-processors`: Specifies a type of object that installs plugins. Refer to [Post-Processors](/packer/docs/post-processors) for additional information. diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index 94d2b142b09..2b73ec6242d 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -10,7 +10,7 @@ This topic provides overview information about installing and loading Packer plu ## Introduction -The Packer binary includes a set of built-in plugins that run automatically, but you also define a list of external plugins in your template for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code. Packer launches one plugin process for each component in the build. +The Packer binary includes a set of built-in plugins that run automatically, but you can also define a list of external plugins in your template for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code. Packer launches one plugin process for each component in the build. ## Workflows diff --git a/website/content/docs/release-notes/v1_11.mdx b/website/content/docs/release-notes/v1_11.mdx index 29449003864..b0eaa7eea31 100644 --- a/website/content/docs/release-notes/v1_11.mdx +++ b/website/content/docs/release-notes/v1_11.mdx @@ -1,5 +1,5 @@ --- -page_title: Packer v1.111 release notes +page_title: Packer v1.11 release notes description: Learn about the changes in Packer v 1.11 --- @@ -13,7 +13,7 @@ This release includes the following updates. ### Predictable plugin loading -To boost stability, Packer no longer loads plugin binaries installed outside of its plugin directory. Additionally, Packer now only loads binaries that have accompanying SHA256SUM files. In previous versions, Packer automatically loads plugins placed in one of the known directories when the file is named according to one of the following naming conventions: +To boost stability, Packer no longer loads plugin binaries installed outside of its plugin directory. Additionally, Packer now only loads binaries that have an accompanying SHA256SUM file. In previous versions, Packer automatically loads plugins placed in one of the known directories when the file is named according to one of the following naming conventions: `packer-plugin-` `packer-plugin-_v0.0.1_x5.0_darwin_arm64` @@ -26,7 +26,7 @@ The following features, workflows, and components are deprecated and are no long ### Legacy single-component plugins -Packer no longer loads single-component plugins, such as legacy plugins that follow the deprecated naming convention of `packer-builder-` or `packer-provisioner--`. Packer only supports multi-component plugins, such as the Docker plugin for Packer. +Packer no longer supports single-component plugins, such as legacy plugins that follow the deprecated naming convention of `packer-builder-` or `packer-provisioner-`. Packer only supports multi-component plugins, such as the Docker plugin for Packer. ### Loading plugin binaries named `packer-plugin-` From 6a05d3c52b6203606392b7801495826f23b5f106 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 28 May 2024 15:32:19 +0000 Subject: [PATCH 14/24] backport of commit 9e7078dbb70002e7751e1a96982d607401710805 --- website/data/docs-nav-data.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index dfff8889c4f..fc1b106d8a4 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -880,7 +880,7 @@ }, { "title": "Installing Plugins", - "path": "plugins/install-plugins" + "path": "plugins/install" }, { "title": "Developing Plugins", From 49ce2399381ff97452bcb0fa1b23376be61e4d0a Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 28 May 2024 15:56:15 +0000 Subject: [PATCH 15/24] backport of commit 8796c74d71e6f4cfddfa86358cccad8ec89d29a8 --- website/content/docs/commands/init.mdx | 2 +- website/content/docs/configure.mdx | 2 +- website/content/docs/upgrade/v1_11.mdx | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index 85090eecab6..0159bd036b4 100644 --- a/website/content/docs/commands/init.mdx +++ b/website/content/docs/commands/init.mdx @@ -10,7 +10,7 @@ The `packer init` command initializes Packer according to an HCL template config ## Description -Use the `packer init` command to download and install plugins according to the `required_plugins` block in Packer templates written in HCL. Refer to [Specifying plugin requirements](docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) in the template configuration reference for additional information about configuring the `required_plugins` block. +Use the `packer init` command to download and install plugins according to the `required_plugins` block in Packer templates written in HCL. Refer to [Specifying plugin requirements](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) in the template configuration reference for additional information about configuring the `required_plugins` block. Legacy JSON templates are not supported. You can convert your JSON template files to HCL using the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) command. diff --git a/website/content/docs/configure.mdx b/website/content/docs/configure.mdx index 6887453ddf2..1b0f8f98b4d 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -10,7 +10,7 @@ This topic describes how to configure Packer. The default configurations are sui ## Overview -You can set Packer-specific environment variables in a configuration file to configure Packer behavior globally. Install configuration files in the Packer configuration directory to implement the configurations. You can also install plugin files and their SHA256SUM files to the plugins subdirectory under the configuration directory. Refer to [Installing Plugins](/plugins/install) for instructions. +You can set Packer-specific environment variables in a configuration file to configure Packer behavior globally. Install configuration files in the Packer configuration directory to implement the configurations. You can also install plugin files and their SHA256SUM files to the plugins subdirectory under the configuration directory. Refer to [Installing Plugins](/packer/docs/plugins/install) for instructions. You can also define Packer settings in a JSON configuration file and add it to the execution path. This configuration method is deprecated. diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx index c6ddc5ac40d..7ad5970c026 100644 --- a/website/content/docs/upgrade/v1_11.mdx +++ b/website/content/docs/upgrade/v1_11.mdx @@ -9,15 +9,15 @@ This topic describes how to upgrade to v1.11. Refer to the [Packer v1.11 release ## Requirements -[comment]: < > (Delete this section if there is no content for it) + ## Upgrade from v1.10 -[comment]: < > (Describe the steps) + ## Upgrade from a version older than v1.10 -[comment]: < > (Delete this section if there is no content for it) + ## Troubleshooting From 848cb913e398dc287a9f6fe5bd1777b9221df99b Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 28 May 2024 16:27:06 +0000 Subject: [PATCH 16/24] backport of commit 05696b6d087cf5e4f5c36bdb2a83567fc608eec3 --- website/content/docs/configure.mdx | 2 +- website/content/docs/plugins/install.mdx | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/configure.mdx b/website/content/docs/configure.mdx index 1b0f8f98b4d..5e4b8aa3a54 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -50,7 +50,7 @@ You use a JSON file to set core Packer settings. Packer checks the following pat Use basic JSON to configure the file. You can specify the configuration parameters for the core configuration file. All parameters are optional. None of these are required, since all have defaults. -- `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP connections on your local host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. +- `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP connections on your local Unix host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. - `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP connections on your local Unix host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. - `builders`: Specifies a type of object that installs plugins. Refer to [Builders](/packer/docs/builders) for additional information. - `commands`: Specifies a type of object that installs plugins. diff --git a/website/content/docs/plugins/install.mdx b/website/content/docs/plugins/install.mdx index f5ee9a9f2bb..cb3d600a92d 100644 --- a/website/content/docs/plugins/install.mdx +++ b/website/content/docs/plugins/install.mdx @@ -50,8 +50,8 @@ If you expect to exceed the request rate limit, you can use a GitHub API token t 1. Specify the name of the plugin and its `version` and `source` parameters. Setting a correct [version constraint string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints) is important for pinning plugin versions for build reproducibility. Refer to the [`packer` block configuration reference](/packer/docs/templates/hcl_templates/blocks/packer) for additional information. - The following example configures Packer to install a plugin called `happycloud`. When the template is initialized, Packer downloads version 2.7.0 or newer of the plugin from GitHub: - + The following example configures Packer to install a plugin called `happycloud`. When the template is initialized, Packer downloads version 2.7.0 or newer of the plugin from GitHub: + ```hcl packer { required_plugins { @@ -97,7 +97,7 @@ Refer to [`packer init` command](/packer/docs/commands/init) for additional info ## Install a plugin under development -You can install and use plugins that are still under development and report as `dev` versions. But if a non-development version of the plugin binary is available, Packer installs the non-development version according to the version constraints configured in the Packer template and uses it in the build. +You can install and use plugins that are still under development and report as `dev` versions. But if a final version of the plugin binary is available, Packer installs the final version according to the version constraints specified in the Packer template and uses it in the build. If a development binary, such as a manually-built binary, is available at the specified source, Packer uses it in the build if it is the highest compatible version installed and if no final plugin version with the same version number is installed alongside it. From 43acf997ecc5adc9e3b9343b0ef57bcb9cf554cc Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Tue, 28 May 2024 22:50:17 +0000 Subject: [PATCH 17/24] backport of commit 6db692bffc7d2e25dba3604b3550cb1b67a44724 --- website/content/docs/release-notes/v1_11.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/release-notes/v1_11.mdx b/website/content/docs/release-notes/v1_11.mdx index b0eaa7eea31..638c9e382c6 100644 --- a/website/content/docs/release-notes/v1_11.mdx +++ b/website/content/docs/release-notes/v1_11.mdx @@ -13,7 +13,7 @@ This release includes the following updates. ### Predictable plugin loading -To boost stability, Packer no longer loads plugin binaries installed outside of its plugin directory. Additionally, Packer now only loads binaries that have an accompanying SHA256SUM file. In previous versions, Packer automatically loads plugins placed in one of the known directories when the file is named according to one of the following naming conventions: +Packer no longer loads plugin binaries installed outside of its plugin directory. Additionally, Packer now only loads binaries that have an accompanying SHA256SUM file. In previous versions, Packer automatically loads plugins placed in one of the known directories when the file is named according to one of the following naming conventions: `packer-plugin-` `packer-plugin-_v0.0.1_x5.0_darwin_arm64` From 71b12eaa4ed12c6519fc54b7774b526eff51adfa Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 29 May 2024 02:02:26 +0000 Subject: [PATCH 18/24] backport of commit e878cac25de5a74db14c6f3e569cd992ba453b1e --- website/content/docs/release-notes/v1_11.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website/content/docs/release-notes/v1_11.mdx b/website/content/docs/release-notes/v1_11.mdx index 638c9e382c6..7f689928013 100644 --- a/website/content/docs/release-notes/v1_11.mdx +++ b/website/content/docs/release-notes/v1_11.mdx @@ -13,10 +13,9 @@ This release includes the following updates. ### Predictable plugin loading -Packer no longer loads plugin binaries installed outside of its plugin directory. Additionally, Packer now only loads binaries that have an accompanying SHA256SUM file. In previous versions, Packer automatically loads plugins placed in one of the known directories when the file is named according to one of the following naming conventions: +We have simplified the way Packer discovers and loads plugins. Packer no longer loads plugin binaries installed outside its plugin directory. Additionally, Packer now only loads binaries that have an accompanying SHA256SUM file. We have also updated the commands for installing plugins so that most installation workflows can proceed without manually modifying the filesystem. We also focused on providing clear instructions so that you can understand the processes and how to address potential errors. -`packer-plugin-` -`packer-plugin-_v0.0.1_x5.0_darwin_arm64` +Previous versions of Packer allowed you to install and load plugins in several locations, resulting in various inconsistencies. For example, configuring the `required_plugins` block in HCL2 templates resulted in limited plugin discoverability. This was not only confusing, the number of alternative paths to support also increased the maintenance burden. Because Packer checked several locations before starting to execute, many commands suffered unnecessary performance issues. Refer to [Installing Plugins](/packer/docs/plugins/install) for details about how to load plugins. From 355de632739ca97edc6dced0cdb0a7a5fb232039 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 29 May 2024 02:05:24 +0000 Subject: [PATCH 19/24] backport of commit 61b2cda4962e358f6d321920b6a4e4f5c363182f --- website/content/docs/upgrade/v1_11.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx index 7ad5970c026..1c1bba6457a 100644 --- a/website/content/docs/upgrade/v1_11.mdx +++ b/website/content/docs/upgrade/v1_11.mdx @@ -14,10 +14,6 @@ This topic describes how to upgrade to v1.11. Refer to the [Packer v1.11 release ## Upgrade from v1.10 - -## Upgrade from a version older than v1.10 - - ## Troubleshooting From 0611a8e8c0052b172aa45fde2d39e38a06b24b4b Mon Sep 17 00:00:00 2001 From: Lucas Bajolet Date: Thu, 30 May 2024 15:38:08 +0000 Subject: [PATCH 20/24] backport of commit a61220a8a6d13a9b05d369719a384af5c1fc9ee9 --- website/content/docs/upgrade/v1_11.mdx | 79 ++++++++++++++++++++++---- 1 file changed, 69 insertions(+), 10 deletions(-) diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx index 1c1bba6457a..7fe009806bb 100644 --- a/website/content/docs/upgrade/v1_11.mdx +++ b/website/content/docs/upgrade/v1_11.mdx @@ -3,23 +3,82 @@ page_title: Upgrade to v1.11 description: Learn how to upgrade your Packer installation to v1.11 --- -# Upgrade to v1.11 +# Upgrade from v1.10 -This topic describes how to upgrade to v1.11. Refer to the [Packer v1.11 release notes](/packer/docs/release-notes/v1_11) for information about changes in v1.11 from the previous release. +Modifications to existing templates are not required between Packer 1.10 and 1.11. -## Requirements +However, plugin management may need to change as we removed support for some alternatives: - +* Single-component plugins (e.g. `packer-builder-hashicups-coffee`) are not supported anymore. + If you are still using those plugins, we urge you to update your dependencies to multi-component plugins (e.g. `packer-plugin-hashicups`) -## Upgrade from v1.10 +* Plugins now all have to be installed in the plugins directory, under a hierarchy that matches the expected source, with a specific naming convention, and with an accompanying sumfile. + This method of installation is now the standard with all commands, including `packer init` and `packer plugins install`. + If you are managing plugin installation outside of Packer's plugin directory, we advise you to revisit your installation process + to work with `packer plugins install` or `packer init` for a consistent plugin management workflow. - +* Version standardization: version management for Packer plugins was permissive in previous versions. + Packer 1.11 standardizes on the use of semantic versioning for plugin versions within `packer init`, + with added support for `-dev` prereleases via the `packer plugins install --path` command. -## Troubleshooting +* Source relaxation: plugins that are available on non-Github hosts may now be installed through the `packer plugins install --path` command. + This will install the plugin in the Packer plugin directory, creating the file hierarchy that matches the supplied source. + This means you will now be able to use `required_plugins` in your templates with non-Github sources, and have Packer discover it as it would with Github sources. + This enables you to add version constraints on those plugins if you so choose. + **Note**: while you can add non-GitHub sources to `required_plugins` for validation purposes, remote installation is still limited to Github-sourced plugins. -This section provides guidance on potential issues you may experience after upgrading +# Troubleshooting -### Missing plugins error +This section provides guidance on potential issues you may experience after upgrading. -Packer may report that you one or more plugins are missing after the upgrade. You may need to reinstall the plugins as described in [Installing Plugins](/packer/docs/plugins/install). +## Missing plugins error +Packer may report that you one or more plugins are missing after the upgrade. +This might happen if you had installed the plugin using one of the now unsupported methods of installation: + +* in the directory Packer is invoked from +* alongside the Packer binary +* under the root of the `PACKER_PLUGIN_PATH` directory + +For any missing components, you may need to reinstall their respective plugins as described in [Installing Plugins](/packer/docs/plugins/install). + +## Plugin local installation + +If you cannot remotely install a plugin for any reason (firewalls, Github blocked, etc.), you can use the local installation methods. +After downloading the plugin binary, you can manually install the plugin binary using `packer plugins install --path` command. +This will place the plugin binary in the location that Packer expects it to be, with the correct naming scheme and sumfile. + +## Using `required_plugins` + +In some cases, Packer will hint at using `required_plugins` block in your template. +With such a block, this opens the possibility to use `packer init` to automatically install plugins, and check that your environment is ready to build your template. +While this is the preferred way to manage the plugins you need in order to build your images, this is not a hard requirement. +You can still install plugins independently of a template by using the `packer plugins install` command variants. + +For details on what each command offers you may refer to their respective command references: +* [`packer init`](https://developer.hashicorp.com/packer/docs/commands/init) +* [`packer plugins install`](https://developer.hashicorp.com/packer/docs/commands/plugins/install). + +**Note**: Legacy JSON users must use `packer plugins install`, as the required_plugins block is only available within HCL templates. + +## Installing plugins outside of namespace directories + +Previously Packer supported the use of plugins as `packer-plugin-` under a single root directory. +In Packer 1.11 this functionality was removed to enhance support for using non-GitHub and development prerelease plugin binaries within required_plugins block. + +If you want to use Packer commands like `packer init` or `packer plugins install`, and customise which root directory manages those plugins, +you can set the `PACKER_PLUGIN_PATH` environment variable so it points to the directory of your choosing. +Once set, Packer will automatically create the subdirectories that match the sources of the plugins you're requiring/using under that directory. + +Note: older versions of Packer supported defining multiple directories for `PACKER_PLUGIN_PATH`, this is no longer the case with Packer 1.11. + +## Remote installation and non-Github sources + +If you are installing plugins from sources that are not Github, you will not be able to automatically install them with `packer init`. +You will still be able to install them with `packer plugins install --path` once you have downloaded a binary from the source. +In cases like those, `required_plugins` have two advantages: + +1. Documentation: this lets users of your template know which plugins they should install in order to build. + This also lets users know where those plugins are found so they can download the expected binary. +2. Validation: because `packer init` checks that the required plugins are installed in the expected versions, this makes sure + you do have the right versions of a plugin installed locally. From 87fdd8233b9d82a4bfaf99578ce188a056478f1c Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Fri, 31 May 2024 15:17:11 +0000 Subject: [PATCH 21/24] backport of commit 187ed85c5c2ee58f5f234da5314e2e42e6bc77df --- website/content/docs/commands/init.mdx | 2 +- website/content/docs/configure.mdx | 2 +- website/content/docs/plugins/install.mdx | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index 0159bd036b4..99b734ca991 100644 --- a/website/content/docs/commands/init.mdx +++ b/website/content/docs/commands/init.mdx @@ -1,6 +1,6 @@ --- description: | - Reference information about the `packer init` command, which downloads and installs Packer one or more plugin binaries specified in a Packer template written in HCL. + Reference information about the `packer init` command, which downloads and installs one or more plugin binaries specified in a Packer template written in HCL. page_title: packer init command line reference --- diff --git a/website/content/docs/configure.mdx b/website/content/docs/configure.mdx index 5e4b8aa3a54..d71d08d7e24 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -50,7 +50,7 @@ You use a JSON file to set core Packer settings. Packer checks the following pat Use basic JSON to configure the file. You can specify the configuration parameters for the core configuration file. All parameters are optional. None of these are required, since all have defaults. -- `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP connections on your local Unix host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. +- `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP or Unix sockets on your local host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. - `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP connections on your local Unix host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. - `builders`: Specifies a type of object that installs plugins. Refer to [Builders](/packer/docs/builders) for additional information. - `commands`: Specifies a type of object that installs plugins. diff --git a/website/content/docs/plugins/install.mdx b/website/content/docs/plugins/install.mdx index cb3d600a92d..ad35927c00f 100644 --- a/website/content/docs/plugins/install.mdx +++ b/website/content/docs/plugins/install.mdx @@ -95,9 +95,8 @@ $ packer init --upgrade . Refer to [`packer init` command](/packer/docs/commands/init) for additional information. -## Install a plugin under development +## Use a plugin under development -You can install and use plugins that are still under development and report as `dev` versions. But if a final version of the plugin binary is available, Packer installs the final version according to the version constraints specified in the Packer template and uses it in the build. If a development binary, such as a manually-built binary, is available at the specified source, Packer uses it in the build if it is the highest compatible version installed and if no final plugin version with the same version number is installed alongside it. @@ -143,7 +142,6 @@ When a non-development version of 1.1.1 becomes available, the binary takes prec └── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64_SHA256SUM ``` -Refer to the documentation in the [Packer plugin scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding?tab=readme-ov-file#build-from-source) for additional information. ### Example Docker plugin @@ -184,6 +182,8 @@ Complete the following steps to build and install a custom version of the Docker For convenience, the makefile in the Packer plugin scaffolding repository builds and installs development binaries using `make dev`. +Refer to the documentation in the [Packer plugin scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding?tab=readme-ov-file#build-from-source) for additional information. + ## Authenticate requests to the GitHub API You can set the `PACKER_GITHUB_API_TOKEN` environment variable to send more requests per hour than the limits imposed by the GitHub API: From 2fb88caf0ae20b5861b8ec15d5d77692c4ac7c24 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 31 May 2024 17:57:40 +0000 Subject: [PATCH 22/24] backport of commit b5618bf82ff0391666c56ecc47c4da64d3117064 --- website/content/docs/release-notes/v1_11.mdx | 5 +- website/content/docs/upgrade/v1_11.mdx | 97 +++++++++----------- 2 files changed, 48 insertions(+), 54 deletions(-) diff --git a/website/content/docs/release-notes/v1_11.mdx b/website/content/docs/release-notes/v1_11.mdx index 7f689928013..fe4c3c401a2 100644 --- a/website/content/docs/release-notes/v1_11.mdx +++ b/website/content/docs/release-notes/v1_11.mdx @@ -17,7 +17,10 @@ We have simplified the way Packer discovers and loads plugins. Packer no longer Previous versions of Packer allowed you to install and load plugins in several locations, resulting in various inconsistencies. For example, configuring the `required_plugins` block in HCL2 templates resulted in limited plugin discoverability. This was not only confusing, the number of alternative paths to support also increased the maintenance burden. Because Packer checked several locations before starting to execute, many commands suffered unnecessary performance issues. -Refer to [Installing Plugins](/packer/docs/plugins/install) for details about how to load plugins. +Refer to the following topics for additional information: + +- [Installing Plugins](/packer/docs/plugins/install) for details about how to load plugins. +- [Upgrade to v1.11](/packer/docs/upgrade/v1_11) for information about how these changes may affect your existing workflows. ## Deprecations diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx index 7fe009806bb..fcbc351d261 100644 --- a/website/content/docs/upgrade/v1_11.mdx +++ b/website/content/docs/upgrade/v1_11.mdx @@ -3,82 +3,73 @@ page_title: Upgrade to v1.11 description: Learn how to upgrade your Packer installation to v1.11 --- -# Upgrade from v1.10 +# Upgrade to v1.11 -Modifications to existing templates are not required between Packer 1.10 and 1.11. +This topic describes upgrade considerations for Packer v1.11. Refer to the [v1.11 release notes](/packer/docs/release-notes/v1_11) for details about changes in v1.11. -However, plugin management may need to change as we removed support for some alternatives: +## Overview -* Single-component plugins (e.g. `packer-builder-hashicups-coffee`) are not supported anymore. - If you are still using those plugins, we urge you to update your dependencies to multi-component plugins (e.g. `packer-plugin-hashicups`) +You can use the upgrade command for the package manage you installed Packer with or download and replace the existing binary to upgrade Packer. Refer to [Install Packer](/packer/install) for instructions -* Plugins now all have to be installed in the plugins directory, under a hierarchy that matches the expected source, with a specific naming convention, and with an accompanying sumfile. - This method of installation is now the standard with all commands, including `packer init` and `packer plugins install`. - If you are managing plugin installation outside of Packer's plugin directory, we advise you to revisit your installation process - to work with `packer plugins install` or `packer init` for a consistent plugin management workflow. +## Upgrade from 1.10 -* Version standardization: version management for Packer plugins was permissive in previous versions. - Packer 1.11 standardizes on the use of semantic versioning for plugin versions within `packer init`, - with added support for `-dev` prereleases via the `packer plugins install --path` command. +Take the following actions as a result of changes between v1.10 and v1.11. -* Source relaxation: plugins that are available on non-Github hosts may now be installed through the `packer plugins install --path` command. - This will install the plugin in the Packer plugin directory, creating the file hierarchy that matches the supplied source. - This means you will now be able to use `required_plugins` in your templates with non-Github sources, and have Packer discover it as it would with Github sources. - This enables you to add version constraints on those plugins if you so choose. - **Note**: while you can add non-GitHub sources to `required_plugins` for validation purposes, remote installation is still limited to Github-sourced plugins. +### Review templates -# Troubleshooting +Packer v1.11 supports existing v1.10 templates. No action is required. + +### Review plugin management processes + +Because we have made the following changes to how Packer manages plugins, you should review your plugin management processes and make changes accordingly: + +* Single-component plugins are no longer supported. Update your dependencies to multi-component plugins. For example, update `packer-builder-hashicups-coffee` to `packer-plugin-hashicups`. + +* Packer requires all plugins to be installed in the plugins directory. Plugins must follow the hierarchy that matches the expected source. Plugins must follow the `packer-plugin-` naming convention. Plugins must be accompanied by a `SHA256SUM` file. If you manage plugin installations outside of Packer's plugin directory, modify your installation processes to meet these requirements. Refer to [Install Plugins](/packer/docs/plugins/install) for additional information. + +* Packer requires semantic versioning for plugins installed from Packer HCL2 templates. Refer to [Requirements](/packer/docs/plugins/install#requiremets) in the Packer plugin installation documentation for additional information. + +* You can use `-dev` pre-release versions of plugins in your builds using the `packer plugins install --path` command. Refer to [Use a plugin under development](/packer/docs/plugins/install#use-a-plugin-under-development). + +* You can use the `packer plugins install --path` command to install plugins from non-Github hosts. This command installs the plugin in the Packer plugin directory and creates the file hierarchy that matches the supplied source. As result, Packer is able to discover non-Github sources specified in the `required_plugins` blocks. This enables you to add version constraints on those plugins if you so choose. + Although you can add non-GitHub sources to `required_plugins` for validation purposes, remote installation is still limited to Github-sourced plugins. Refer to [Define plugin source](/packer/docs/templates/hcl_templates/blocks/packer#define-plugin-source) in the `required_plugins` reference documentation for additional information. + +## Troubleshooting This section provides guidance on potential issues you may experience after upgrading. -## Missing plugins error +### Missing plugins error Packer may report that you one or more plugins are missing after the upgrade. -This might happen if you had installed the plugin using one of the now unsupported methods of installation: +This may occur if you had used one of the following plugin installation methods that are longer supported: -* in the directory Packer is invoked from -* alongside the Packer binary -* under the root of the `PACKER_PLUGIN_PATH` directory +* Installed the plugin to the directory Packer is invoked from. +* Installed the plugin alongside the Packer binary. +* Installed the plugin under the root of the `PACKER_PLUGIN_PATH` directory. For any missing components, you may need to reinstall their respective plugins as described in [Installing Plugins](/packer/docs/plugins/install). -## Plugin local installation +### Use `required_plugins` message -If you cannot remotely install a plugin for any reason (firewalls, Github blocked, etc.), you can use the local installation methods. -After downloading the plugin binary, you can manually install the plugin binary using `packer plugins install --path` command. -This will place the plugin binary in the location that Packer expects it to be, with the correct naming scheme and sumfile. +Packer may print a message directing you to specify plugins in the `required_plugins` block in your template and install them using the `packer init` command. +This is the preferred way to manage the plugins, but it is not required. You can still install plugins manually using the `packer plugins install` command. Refer to [Installing Plugins](/packer/docs/plugins/install) -## Using `required_plugins` +### Blocked remote access to plugin -In some cases, Packer will hint at using `required_plugins` block in your template. -With such a block, this opens the possibility to use `packer init` to automatically install plugins, and check that your environment is ready to build your template. -While this is the preferred way to manage the plugins you need in order to build your images, this is not a hard requirement. -You can still install plugins independently of a template by using the `packer plugins install` command variants. +If you cannot remotely install a plugin for any reason, such as a firewall configuration or GitHub is blocking access, you can use the local installation methods. Refer to [Installing Plugins](/packer/docs/plugins/install) -For details on what each command offers you may refer to their respective command references: -* [`packer init`](https://developer.hashicorp.com/packer/docs/commands/init) -* [`packer plugins install`](https://developer.hashicorp.com/packer/docs/commands/plugins/install). +### Install plugins from legacy JSON template -**Note**: Legacy JSON users must use `packer plugins install`, as the required_plugins block is only available within HCL templates. +The `required_plugins` block is only available within HCL templates. Legacy JSON users must use `packer plugins install` ## Installing plugins outside of namespace directories -Previously Packer supported the use of plugins as `packer-plugin-` under a single root directory. -In Packer 1.11 this functionality was removed to enhance support for using non-GitHub and development prerelease plugin binaries within required_plugins block. - -If you want to use Packer commands like `packer init` or `packer plugins install`, and customise which root directory manages those plugins, -you can set the `PACKER_PLUGIN_PATH` environment variable so it points to the directory of your choosing. -Once set, Packer will automatically create the subdirectories that match the sources of the plugins you're requiring/using under that directory. +Packer no longer supports installing plugins that are named `packer-plugin-` under a single root directory. +You can still use Packer CLI commands to install plugins and customise which root directory manages those plugins by setting the `PACKER_PLUGIN_PATH` environment variable so that it points to the custom directory. +Once set, Packer automatically creates the subdirectories that match the sources of the plugins under that directory. -Note: older versions of Packer supported defining multiple directories for `PACKER_PLUGIN_PATH`, this is no longer the case with Packer 1.11. +## Reference -## Remote installation and non-Github sources - -If you are installing plugins from sources that are not Github, you will not be able to automatically install them with `packer init`. -You will still be able to install them with `packer plugins install --path` once you have downloaded a binary from the source. -In cases like those, `required_plugins` have two advantages: - -1. Documentation: this lets users of your template know which plugins they should install in order to build. - This also lets users know where those plugins are found so they can download the expected binary. -2. Validation: because `packer init` checks that the required plugins are installed in the expected versions, this makes sure - you do have the right versions of a plugin installed locally. +Refer to the following topics for additional information about using the Packer CLI to install plugins: +* [`packer init`](https://developer.hashicorp.com/packer/docs/commands/init) +* [`packer plugins install`](https://developer.hashicorp.com/packer/docs/commands/plugins/install). \ No newline at end of file From 62897e95719f4c90456573f2f5046df48fdec610 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Fri, 31 May 2024 18:40:36 +0000 Subject: [PATCH 23/24] backport of commit f7e9ed4732d2ed3d87264c5250dd13c1f605c62e --- website/content/docs/upgrade/v1_11.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx index fcbc351d261..77270c4ee33 100644 --- a/website/content/docs/upgrade/v1_11.mdx +++ b/website/content/docs/upgrade/v1_11.mdx @@ -9,7 +9,7 @@ This topic describes upgrade considerations for Packer v1.11. Refer to the [v1.1 ## Overview -You can use the upgrade command for the package manage you installed Packer with or download and replace the existing binary to upgrade Packer. Refer to [Install Packer](/packer/install) for instructions +You can use the upgrade command for the package manager you installed Packer with or download and replace the existing binary to upgrade Packer. Refer to [Install Packer](/packer/install) for instructions ## Upgrade from 1.10 From 4ee3ed64a7f9b85b3fc71ffb2c5e0fb010833a27 Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Fri, 31 May 2024 18:49:56 +0000 Subject: [PATCH 24/24] backport of commit 47a92575d3006b909dd466299d56b2090993652d --- website/content/docs/commands/plugins/install.mdx | 2 +- website/content/docs/configure.mdx | 6 +----- website/content/docs/plugins/index.mdx | 2 +- 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/website/content/docs/commands/plugins/install.mdx b/website/content/docs/commands/plugins/install.mdx index f3dafc819df..82bda2e0dcd 100644 --- a/website/content/docs/commands/plugins/install.mdx +++ b/website/content/docs/commands/plugins/install.mdx @@ -29,7 +29,7 @@ Use the following syntax to run the `packer plugins install` command: Specify a version number to install a specific version of the plugin. The following example installs the version `1.0.1` of `my-plugin` from a remote source: ```shell-session -$ packer plugins install github.com/hashicorp/my-plugin 1.0.0 +$ packer plugins install github.com/hashicorp/my-plugin 1.0.1 ``` Use the `--path` option to specify a local plugin binary. The following example installs `my-plugin` from a local binary: diff --git a/website/content/docs/configure.mdx b/website/content/docs/configure.mdx index d71d08d7e24..e01eef0dc8e 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -52,17 +52,13 @@ configuration file. All parameters are optional. None of these are required, sin - `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP or Unix sockets on your local host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. - `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP connections on your local Unix host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run. -- `builders`: Specifies a type of object that installs plugins. Refer to [Builders](/packer/docs/builders) for additional information. -- `commands`: Specifies a type of object that installs plugins. -- `post-processors`: Specifies a type of object that installs plugins. Refer to [Post-Processors](/packer/docs/post-processors) for additional information. -- `provisioners`: Specifies a type of object that installs plugins. Refer to [Provisioners](/packer/docs/provisioners) for additional information. The [`packer init`](/packer/docs/commands/init) command takes precedence over JSON-configure settings when installing plugins. ## Configure the cache directory -Packer uses a cache directory to download large files and for logistics around large file download. By default, Packer caches files in the `./packer_cache/` folder of the current directory. Use the `PACKER_CACHE_DIR` environment variable to configure the cache directory. Refer to [`PACKER_CACHE_DIR`](/packer/docs/configure#packer_config_dir) for details. +Packer uses a cache directory to download large files and for logistics around large file download. By default, Packer caches files in the `.packer_cache` folder of the current directory. Use the `PACKER_CACHE_DIR` environment variable to configure the cache directory. Refer to [`PACKER_CACHE_DIR`](/packer/docs/configure#packer_config_dir) for details. We recommend using the same Packer cache directory across your builds if multiple builds perform similar actions. This is to avoid downloading the same large file, such as an ISO, multiple times. diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index 2b73ec6242d..81a1df03bd0 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -10,7 +10,7 @@ This topic provides overview information about installing and loading Packer plu ## Introduction -The Packer binary includes a set of built-in plugins that run automatically, but you can also define a list of external plugins in your template for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code. Packer launches one plugin process for each component in the build. +The Packer binary includes a set of built-in components that are automatically usable. You can also install external plugins for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code. Packer launches one plugin process for each component in the build. ## Workflows