upstream/packer
1
0
Fork 0
mirror of https://github.com/hashicorp/packer.git synced 2026-06-13 18:50:11 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Update plugins install docs for v1.11.0 (#12995)

Browse source 
* IPE-727 first commit, adds release notes

* content for the 1.11 release notes

* updates to init CLI reference

* updates to install plugins CLI reference

* updates to source information on the packer block configuration reference

* updated Packer configuration page

* updated plugins installation overview page

* updated plugins installation usage page

* added Upgrades section

* added outline for an upgrade page for this version

* added comments for upgrade page outline

* renamed install plugins mdx and added redirects

* Apply suggestions from code review

Co-authored-by: Lucas Bajolet <105649352+lbajolet-hashicorp@users.noreply.github.com>

* fix nav

* fix bad links

* applying additional feedback

* Apply suggestions from code review

Co-authored-by: Lucas Bajolet <105649352+lbajolet-hashicorp@users.noreply.github.com>

* integrated rationale into release notes

* removed 'upgrade from older version' section in the upgrade instructions

* docs: fill-in the upgrade/1.11 document

* Apply suggestions from code review

Co-authored-by: Wilken Rivera <wilken@hashicorp.com>

* edits to upgrade 1.11 and release note

* Apply suggestions from code review

Co-authored-by: Lucas Bajolet <105649352+lbajolet-hashicorp@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Lucas Bajolet <105649352+lbajolet-hashicorp@users.noreply.github.com>

---------

Co-authored-by: Lucas Bajolet <105649352+lbajolet-hashicorp@users.noreply.github.com>
Co-authored-by: Lucas Bajolet <lucas.bajolet@hashicorp.com>
Co-authored-by: Wilken Rivera <wilken@hashicorp.com>
This commit is contained in:
trujillo-adam 2024-05-31 11:52:47 -07:00 committed by GitHub
parent 766c3d7fef
commit d75975821f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 494 additions and 462 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

103
website/content/docs/commands/init.mdx
View file

@ -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.
## Usage
Use the following syntax to run the `packer init` command:
```shell-session
$ packer init <path-to-template>
```
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.
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.
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.
## Examples
`packer init` will list all installed plugins then download the latest versions
for the ones that are missing.
The following example installs the plugins specified in a template named `template.pkr.hcl`:
`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"
}
}
}
```shell-session
$ packer init template.pkr.hcl
```
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.
## Arguments
## Plugin Selection
You can pass the following arguments:
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.
- Packer template: Specify the path to either an HCL2 template or a directory containing at least one valid HCL2 template and related dependencies.
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.
`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.
Refer to [Installing Plugins](/packer/docs/plugins#installing-plugins) for more information on how plugin installation works.
## 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.
- `-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.

70
website/content/docs/commands/plugins/install.mdx
View file

@ -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...] <plugin> [<version constraint>]
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 <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:
- `<plugin-binary-source>`: 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.
- `<plugin version>`: A specific version of the plugin to download and install. Packer accepts semantic version numbers that follow the `<major>.<minor>.<patch>` 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.

2
website/content/docs/community-tools.mdx
View file

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

86
website/content/docs/configure.mdx
View file

@ -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.
<a id="packer-s-config-file"></a>
## Packer's config file (deprecated)
## Install a JSON configuration file
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:
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.
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
Below is the list of all available configuration parameters for the core
configuration file. None of these are required, since all have defaults.
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` 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.
- `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`, `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.
The [`packer init`](/packer/docs/commands/init) command takes precedence over JSON-configure settings when installing plugins.
## Packer's plugin directory
@include "plugins/plugin-location.mdx"
## Configure the cache directory
## Packer's 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 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.
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.
## Environment Variables usable for Packer
## Configuration reference
Packer uses a variety of environmental variables. A listing and description of
each can be found below:

2
website/content/docs/plugins/creation/custom-builders.mdx
View file

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

2
website/content/docs/plugins/creation/index.mdx
View file

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

49
website/content/docs/plugins/index.mdx
View file

@ -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)
## 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.

239
website/content/docs/plugins/install-plugins.mdx
View file

@ -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>/<namespace>/<type>`.
- **Hostname:** The hostname of the location/service that distributes the plugin.
- **Namespace:** An organizational namespace within the specified host.
This often is the organization that 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-<name>_<version>_x<api_version>_<os>_<arch>(.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
<packer_plugin_dir>
└── 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.

197
website/content/docs/plugins/install.mdx Normal file
View file

@ -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-<name>`.
- The project must have semantic version tags per the following format: `v<major>.<minor>.<patch>`.
- 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 <path-to-downloaded-extracted-binary> <hostname>/<namespace>/<plugin-name>
```
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=<token>
```

39
website/content/docs/release-notes/v1_11.mdx Normal file
View file

@ -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-<name>` or `packer-provisioner-<name>`. Packer only supports multi-component plugins, such as the Docker plugin for Packer.
### Loading plugin binaries named `packer-plugin-<name>`
Packer no longer loads plugin binaries following the naming convention of `packer-plugin-<name>`. 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`.

67
website/content/docs/templates/hcl_templates/blocks/packer.mdx vendored
View file

@ -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.
`<HOSTNAME>/[SUBFOLDER/]<NAMESPACE>/<TYPE>`
At minimum source addresses consist of three parts delimited by slashes (`/`), as
follows:
- `<Hostname>`: 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)
- `<Subfolder>`: 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.
- `<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.
-> **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>/<NAMESPACE>/<TYPE>`
- **Hostname:** The hostname of the location/service that
distributes the plugin.
- **Namespace:** An organizational namespace within the specified host.
This often is the organization that publishes the plugin.
- **Type:** A short name for the platform or system the plugin manages. The
type is usually the plugin's preferred local name.
For example, the fictional `myawesomecloud` plugin could belong to the
`hashicorp` namespace on `github.com`, so its `source` could be
`github.com/hashicorp/myawesomecloud`,
-> Note: the actual _repository_ that myawesomecloud comes from must always have
the name format `github.com/hashicorp/packer-plugin-myawesomecloud`, but the
`required_plugins` block omits the redundant `packer-plugin-` repository prefix
for brevity.
The source address with all components given explicitly is called the
plugin's _fully-qualified address_. You will see fully-qualified address in
various outputs, like error messages.
### 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

75
website/content/docs/upgrade/v1_11.mdx Normal file
View file

@ -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-<name>` 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-<name>` 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).

20
website/data/docs-nav-data.json
View file

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

5
website/redirects.js
View file

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