diff --git a/website/content/docs/commands/init.mdx b/website/content/docs/commands/init.mdx index 61858f54273..99b734ca991 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 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](/packer/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. +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. diff --git a/website/content/docs/commands/plugins/install.mdx b/website/content/docs/commands/plugins/install.mdx index 0793aeb20d8..82bda2e0dcd 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.1 ``` -## Related +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 +``` + +## Arguments + +You can pass the following arguments: + +- ``: 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 + +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. 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/configure.mdx b/website/content/docs/configure.mdx index fb0c247c91a..e01eef0dc8e 100644 --- a/website/content/docs/configure.mdx +++ b/website/content/docs/configure.mdx @@ -1,87 +1,69 @@ --- 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](/packer/docs/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 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\` | | + + +### 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 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. -- `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: 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/index.mdx b/website/content/docs/plugins/index.mdx index 4a11840d1b9..81a1df03bd0 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 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. -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. diff --git a/website/content/docs/plugins/install-plugins.mdx b/website/content/docs/plugins/install-plugins.mdx deleted file mode 100644 index 93032676b99..00000000000 --- a/website/content/docs/plugins/install-plugins.mdx +++ /dev/null @@ -1,239 +0,0 @@ ---- -description: | - Install external Packer plugins that extend Packer functionality. -page_title: Install Plugins ---- - -# Installing Plugins - -Packer plugins are separate, standalone applications that perform tasks during each build. - -This page explains how to install external plugins. Refer to [Integrations](/packer/integrations) for a list of available plugins and their documentation. - -Depending on the template type you're using (HCL2 or legacy JSON), the methods for installing plugins may differ. - -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. - -`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. - -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: - -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. - -Refer to the [Installation Guides](#installation-guides) section of this page for information about -each method, including usage examples. - -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. - -## 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. - -Source addresses are a URL, without a scheme (e.g. `"https://"`), query (e.g. `?arg=val`), or -fragment (e.g. `#anchor`). - -Example: `github.com/hashicorp/happycloud` - -#### Github sources - -Github sources all follow this convention: `//`. - -- **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 maintains 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 `happycloud` plugin could belong to the -`hashicorp` namespace on `github.com`, so its `source` could be -`github.com/hashicorp/happycloud`, - --> 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. - -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. - -### 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. - -In order for the binaries installed in this directory to be discovered and used -by Packer, they must follow this set of rules: - -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: - - a. The plugin version must match the name - - b. The API version must match the name's - -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. - -## Plugin Discovery Workflow - -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. - -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: [...] -``` - -Once this discovery step has finished, each discovered plugin will be ready to use -by Packer, on the highest available version. - -Example: - -```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 -``` - -In this example, the `happycloud` plugin will be the one and used to serve -happycloud-related components, in version 1.2.8. - -### HCL2 and `required_plugins` - -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. - -Example: - -```hcl2 -packer{ - required_plugins { - happycloud = { - source = "github.com/hashicorp/happycloud" - version = "= 1.1.8" - } - } -} -``` - -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. - -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 - --> 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. - -In order to use `packer init` for managing installation of your plugins, there are -two steps required. - -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). - -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). - -Here is an example `required_plugins` block: - -```hcl -packer { - required_plugins { - myawesomecloud = { - version = ">= 2.7.0" - source = "github.com/hashicorp/myawesomecloud" - } - happycloud = { - version = ">= 1.1.3" - source = "github.com/hashicorp/happycloud" - } - } -} -``` - -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`. - --> 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. - -### Packer plugins install - -Plugin installation via `packer plugins install` works similar to that of the `packer init` command, but -no `required_plugins` block are required. - -```shell -packer plugins install github.com/hashicorp/vagrant -``` - --> 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"` - -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). - -#### Using packer plugins install to install a local copy of a binary - -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. - -Example: - -```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 -``` - --> Note: the version does not need to be specified, Packer will automatically - determine which version to install based on the plugin's `describe` output. diff --git a/website/content/docs/plugins/install.mdx b/website/content/docs/plugins/install.mdx new file mode 100644 index 00000000000..ad35927c00f --- /dev/null +++ b/website/content/docs/plugins/install.mdx @@ -0,0 +1,197 @@ +--- +description: | + Install external Packer plugins that extend Packer functionality. +page_title: Install Plugins +--- + +# Installing Plugins + +This topic describes how to install external plugins for Packer. Refer to [Packer Plugins Overview](/packer/docs/plugins) for additional information about plugins. + +## Overview + +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. + +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. + +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. + +### Manual installation method + +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. + +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. + +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. + + +### 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. + +## Requirements + +To install a plugin from a remote source, the plugin must meet the following requirements: + +- 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. + +### GitHub API token + +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. + +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. + +## Install a plugin + +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 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 { + happycloud = { + version = ">= 2.7.0" + source = "github.com/hashicorp/happycloud" + } + } + } + + ``` + +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. + +## Manually install plugins using the CLI + +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: + +```shell-session +$ packer plugins install --path // +``` + +The following example installs the `happycloud` plugin from GitHub: + +```shell-session +$ packer plugins install --path happycloud github.com/hashicorp/happycloud +``` + +Refer to the [`packer plugins install`](/packer/docs/commands/plugins/install) reference for additional information. + + +## Upgrade plugins + +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. + +The following example upgrades plugins according to the template in the current directory: + +```shell-session +$ packer init --upgrade . +``` + +Refer to [`packer init` command](/packer/docs/commands/init) for additional information. + +## Use a plugin under development + + +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. + +In the following example, version `1.1.0` or newer is required: + +```hcl +packer = { + required_plugins = { + amazon = { + source = "github.com/hashicorp/amazon" + version = ">= 1.1.0" + } + } + +. . . + +} +``` + +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 +``` + +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 +``` + + +### Example Docker plugin + +Complete the following steps to build and install a custom version of the Docker plugin as an example: + +1. Clone the plugin's GitHub repository. + + ```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. + + ```shell-session + $ cd packer-plugin-docker + $ go build -ldflags="-X github.com/hashicorp/packer-plugin-docker/version.VersionPrerelease=dev" -o packer-plugin-docker-dev + ``` + +1. Validate the release version. + + ```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":[]} + ``` + +1. Use the `packer plugins install` command to install the development binary. + + ```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 + ``` + +1. Run a `packer build` with the newly installed plugin. + + ```shell-session + $ packer build . + ``` + +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: + +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: + + ```shell-session + $ export PACKER_GITHUB_API_TOKEN= + ``` \ No newline at end of file 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..fe4c3c401a2 --- /dev/null +++ b/website/content/docs/release-notes/v1_11.mdx @@ -0,0 +1,39 @@ +--- +page_title: Packer v1.11 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 + +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. + +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 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 + +The following features, workflows, and components are deprecated and are no longer supported. + +### Legacy single-component plugins + +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-` + +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 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 diff --git a/website/content/docs/upgrade/v1_11.mdx b/website/content/docs/upgrade/v1_11.mdx new file mode 100644 index 00000000000..77270c4ee33 --- /dev/null +++ b/website/content/docs/upgrade/v1_11.mdx @@ -0,0 +1,75 @@ +--- +page_title: Upgrade to v1.11 +description: Learn how to upgrade your Packer installation to v1.11 +--- + +# Upgrade to v1.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. + +## Overview + +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 + +Take the following actions as a result of changes between v1.10 and v1.11. + +### Review templates + +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 + +Packer may report that you one or more plugins are missing after the upgrade. +This may occur if you had used one of the following plugin installation methods that are longer supported: + +* 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). + +### Use `required_plugins` message + +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) + +### Blocked remote access to plugin + +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) + +### Install plugins from legacy JSON template + +The `required_plugins` block is only available within HCL templates. Legacy JSON users must use `packer plugins install` + +## Installing plugins outside of namespace directories + +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. + +## Reference + +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 diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 396ee9010e3..fc1b106d8a4 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -850,6 +850,24 @@ "title": "Configuring Packer", "path": "configure" }, + { + "title": "Release notes", + "routes": [ + { + "title": "v1.11", + "path": "release-notes/v1_11" + } + ] + }, + { + "title": "Upgrades", + "routes": [ + { + "title": "Upgrade to v1.11", + "path": "upgrade/v1_11" + } + ] + }, { "divider": true }, @@ -862,7 +880,7 @@ }, { "title": "Installing Plugins", - "path": "plugins/install-plugins" + "path": "plugins/install" }, { "title": "Developing Plugins", 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 */