-
Notifications
You must be signed in to change notification settings - Fork 3.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #13012 from hashicorp/backport/docs/install-plugin…
…s-1.11-ga/radically-leading-muskrat This pull request was automerged via backport-assistant
- Loading branch information
Showing
14 changed files
with
496 additions
and
464 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <path-to-template> | ||
| ``` | ||
|
|
||
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.