mirror of https://github.com/hashicorp/packer
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
267 lines
9.5 KiB
267 lines
9.5 KiB
---
|
|
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.
|
|
|
|
You do not need to install the builder, provisioner, or
|
|
post-processor components that ship with the Packer binary. Packer automatically knows how to find and launch these built-in plugins.
|
|
|
|
This page explains how to install custom external plugins. Refer to [External Plugins](/packer/plugins) for a list of available plugins and their documentation.
|
|
|
|
## Installation Guides
|
|
|
|
Choose the tab that corresponds to the type of plugin you want to install. If you are not sure, check the plugin's name.
|
|
- Multi-component plugin names have the prefix `packer-plugin-`.
|
|
- Single-component plugin names have a prefix containing the component type, like `packer-provisioner-` or `packer-builder`.
|
|
|
|
<Tabs>
|
|
<Tab heading="Packer init (recommended from Packer v1.7.0)">
|
|
|
|
~> **Note**: Only _multi-component plugin binaries_ -- that is plugins named
|
|
packer-plugin-\*, like the `packer-plugin-amazon` -- are expected to work with
|
|
Packer init. The legacy `builder`, `post-processor` and `provisioner` plugin
|
|
types will keep on being detected but Packer cannot install them automatically.
|
|
If a plugin you use has not been upgraded to use the multi-component plugin
|
|
architecture, contact your maintainer to request an upgrade.
|
|
|
|
## Create a required_plugins block
|
|
|
|
1. 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/azr/myawesomecloud"
|
|
}
|
|
happycloud = {
|
|
version = ">= 1.1.3"
|
|
source = "github.com/azr/happycloud"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
2. Run [`packer init`](/packer/docs/commands/init) from your project directory (the
|
|
directory containing your Packer templates) to install all missing plugin
|
|
binaries. Given the above example, Packer will try to look for a GitHub
|
|
repository owned by user or organization `azr` named
|
|
`packer-plugin-myawesomecloud` and `packer-plugin-happycloud`.
|
|
|
|
## Names and Addresses
|
|
|
|
Each plugin has two identifiers:
|
|
|
|
- A `source` address, which is only necessary when requiring a plugin outside the HashiCorp domain.
|
|
- A unique **local name**, which is used everywhere else in a Packer
|
|
configuration.
|
|
|
|
## Local Names
|
|
|
|
Local names allow you to access the components of a plugin and must be unique
|
|
per configuration.
|
|
|
|
This is best explained using an example. In the above `required_plugins` block,
|
|
we declared the local name "myawesomecloud" for the plugin `azr/myawesomecloud`.
|
|
If the "myawesomecloud" plugin contains both an "ebs" builder and an "import"
|
|
post-processor, then the builder will be accessed in a source block by using:
|
|
|
|
```hcl
|
|
source "myawesomecloud-ebs" "example" {
|
|
// builder configuration...
|
|
}
|
|
```
|
|
|
|
similarly, the import post-processor would be accessed by declaring the
|
|
post-processor block:
|
|
|
|
```hcl
|
|
post-processor "myawesomecloud-import" {
|
|
// post-processor configuration...
|
|
}
|
|
```
|
|
|
|
If we change the required_plugins block to use a different local name "foo":
|
|
|
|
```hcl
|
|
required_plugins {
|
|
foo = {
|
|
version = ">= 2.7.0"
|
|
source = "github.com/azr/myawesomecloud"
|
|
}
|
|
}
|
|
```
|
|
|
|
Then we'd instead access that builder using the source:
|
|
|
|
```hcl
|
|
source "foo-ebs" "example" {
|
|
// builder configuration...
|
|
}
|
|
```
|
|
|
|
## Source Addresses
|
|
|
|
A plugin's source address is its global identifier. It also tells Packer where
|
|
to download it.
|
|
|
|
Source addresses consist of three parts delimited by slashes (`/`), as
|
|
follows:
|
|
|
|
`<HOSTNAME>/<NAMESPACE>/<TYPE>`
|
|
|
|
- **Hostname:** The hostname of the location/service that
|
|
distributes the plugin. Currently, the only valid "hostname" is github.com,
|
|
but we plan to eventually support plugins downloaded from other domains.
|
|
|
|
- **Namespace:** An organizational namespace within the specified host.
|
|
This often is the organization that publishes the plugin.
|
|
|
|
- **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 three components given explicitly is called the
|
|
plugin's _fully-qualified address_. You will see fully-qualified address in
|
|
various outputs, like error messages.
|
|
|
|
## Plugin location
|
|
|
|
@include "plugins/plugin-location.mdx"
|
|
|
|
## Implicit Github urls
|
|
|
|
Using the following example :
|
|
|
|
```hcl
|
|
required_plugins {
|
|
happycloud = {
|
|
version = ">= 2.7.0"
|
|
source = "github.com/azr/happycloud"
|
|
}
|
|
}
|
|
```
|
|
|
|
The plugin getter will look for plugins located at:
|
|
|
|
- github.com/azr/packer-plugin-happycloud
|
|
|
|
Packer will error if you set the `packer-plugin-` prefix in a `source`. This
|
|
will avoid conflicting with other plugins for other tools, like Terraform.
|
|
|
|
</Tab>
|
|
<Tab heading="manually (multi-component plugin)">
|
|
|
|
-> The [`packer plugins`](/packer/docs/commands/plugins) command allows to install plugins without going through
|
|
`init`. For manual installation of plugin binaries, without the `packer plugins` command, please continue reading.
|
|
|
|
The easiest way to manually install a plugin is to name it correctly, then place
|
|
it in the proper directory. To name a plugin correctly, make sure the binary is
|
|
named `packer-plugin-NAME`. For example, `packer-plugin-amazon` for a "plugin"
|
|
binary named "amazon". This binary will make one or more components available to
|
|
use. Valid types for plugins are down this page.
|
|
|
|
Once the plugin is named properly, Packer automatically discovers plugins in
|
|
the following directories in the given order. If a conflicting plugin is found
|
|
later, it will take precedence over one found earlier.
|
|
|
|
1. The directory where `packer` is, or the executable directory.
|
|
|
|
2. The `$HOME/.packer.d/plugins` directory, if `$HOME` is defined (Unix)
|
|
|
|
3. The `%APPDATA%/packer.d/plugins` if `%APPDATA%` is defined (Windows)
|
|
|
|
4. The `%USERPROFILE%/packer.d/plugins` if `%USERPROFILE%` is defined
|
|
(Windows)
|
|
|
|
5. The current working directory.
|
|
|
|
6. The directory defined in the env var `PACKER_PLUGIN_PATH`. There can be more
|
|
than one directory defined; for example, `~/custom-dir-1:~/custom-dir-2`.
|
|
Separate directories in the PATH string using a colon (`:`) on POSIX systems and
|
|
a semicolon (`;`) on Windows systems. The above example path would be able to
|
|
find a provisioner named `packer-provisioner-foo` in either
|
|
`~/custom-dir-1/packer-provisioner-foo` or
|
|
`~/custom-dir-2/packer-provisioner-foo`.
|
|
|
|
The valid types for plugins are:
|
|
|
|
- `plugin` - A plugin binary that can contain one or more of each Packer component
|
|
type.
|
|
|
|
- `builder` - Plugins responsible for building images for a specific
|
|
platform.
|
|
|
|
- `post-processor` - A post-processor responsible for taking an artifact from
|
|
a builder and turning it into something else.
|
|
|
|
- `provisioner` - A provisioner to install software on images created by a
|
|
builder.
|
|
|
|
</Tab>
|
|
<Tab heading="manually (single-component plugin)">
|
|
|
|
The easiest way to manually install a plugin is to name it correctly, then place
|
|
it in the proper directory. To name a plugin correctly, make sure the binary is
|
|
named `packer-COMPONENT-NAME`. For example, `packer-provisioner-comment` for a "plugin"
|
|
binary named "comment". This binary will make a single provisioner named `comment` available to
|
|
use. Valid types for plugins are down this page.
|
|
|
|
Once the plugin is named properly, Packer automatically discovers plugins in
|
|
the following directories in the given order. If a conflicting plugin is found
|
|
later, it will take precedence over one found earlier.
|
|
|
|
1. The directory where `packer` is, or the executable directory.
|
|
|
|
2. The `$HOME/.packer.d/plugins` directory, if `$HOME` is defined (Unix)
|
|
|
|
3. The `%APPDATA%/packer.d/plugins` if `%APPDATA%` is defined (Windows)
|
|
|
|
4. The `%USERPROFILE%/packer.d/plugins` if `%USERPROFILE%` is defined
|
|
(Windows)
|
|
|
|
5. The current working directory.
|
|
|
|
6. The directory defined in the env var `PACKER_PLUGIN_PATH`. There can be more
|
|
than one directory defined; for example, `~/custom-dir-1:~/custom-dir-2`.
|
|
Separate directories in the PATH string using a colon (`:`) on POSIX systems and
|
|
a semicolon (`;`) on Windows systems. The above example path would be able to
|
|
find a provisioner named `packer-provisioner-foo` in either
|
|
`~/custom-dir-1/packer-provisioner-foo` or
|
|
`~/custom-dir-2/packer-provisioner-foo`.
|
|
|
|
The valid types for plugins are:
|
|
|
|
- `plugin` - A plugin binary that can contain one or more of each Packer component
|
|
type.
|
|
|
|
- `builder` - Plugins responsible for building images for a specific
|
|
platform.
|
|
|
|
- `post-processor` - A post-processor responsible for taking an artifact from
|
|
a builder and turning it into something else.
|
|
|
|
- `provisioner` - A provisioner to install software on images created by a
|
|
builder.
|
|
|
|
</Tab>
|
|
</Tabs> |