Packer Builders are the components of Packer responsible for creating a
virtual machine, bringing it to a point where it can be provisioned, and then
turning that provisioned virtual machine into a machine image. Several builders
are officially maintained and distributed by the HashiCorp Packer team -- among
these are builders for creating images on Amazon EC2, VMware, Google
Compute Engine, and many more. You can find documentation for how to use these
official builders [here](/docs/builders). It is also possible to write custom
builders using the Packer plugin interface, and this page documents how to do
that.
Prior to reading this page, you should read the page on [plugin development
basics](/docs/extending/plugins).
~> **Warning!** This is an advanced topic. If you're new to Packer, we
recommend getting comfortable with using Packer and its officially maintained
plugins before you dive into writing plugins of your own.
Custom plugins are written in [Go](https://go.dev/), so this guide
assumes that you have some familiarity with that programming language.
Packer builders are responsible for creating a virtual machine, setting the virtual machine up for provisioning, and then turning that provisioned virtual machine into a machine image. We officially maintain and distribute several builders, including builders to create images on Amazon EC2, VMware, Google
Compute Engine, and many more. Refer to the [Builders](/docs/builders) documentation for details.
This page explains how to use the Packer plugin interface to write custom builders. If you want your builder to support HashiCorp Cloud Platform (HCP) Packer, you should also review the [HCP Packer Support](/docs/plugins/creation/hcp-support) documentation.
~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
## Before You Begin
We recommend reviewing the following resources before you begin development:
@ -7,18 +7,18 @@ page_title: Custom Data Sources - Extending
# Custom Data Sources
Packer Data Sources are the components of Packer that allow data to be fetched for use within the configuration.
Use of data sources allows a build to use information defined outside of Packer. An example of
data source is the [amazon-ami data source](/docs/datasources/amazon/ami), which outputs the data of a fetched Amazon AMI.
Prior to reading this page, it is assumed you have read the page on [plugin
development basics](/docs/plugins).
Packer data sources let Packer fetch data to use within the configuration, including information defined outside of Packer. For example, the [amazon-ami data source](/docs/datasources/amazon/ami), outputs the data from an Amazon AMI.
Data Source plugins implement the `packersdk.Datasource` interface and are registered within a plugin Set
with `set.RegisterDatasource(...)` function and served using the `set.Run()`.
~> **Warning!** This is an advanced topic. If you're new to Packer, we
recommend getting a bit more comfortable before you dive into writing plugins.
~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
## Before You Begin
We recommend reviewing the following resources before you begin development:
Packer Post-processors are the components of Packer that transform one artifact
into another, for example by compressing files, or uploading them.
Packer post-processors transform one artifact into another. For example, a post-processor might compress or upload files.
In the compression example, the transformation would be taking an artifact with
a set of files, compressing those files, and returning a new artifact with only
@ -18,14 +17,18 @@ a single file (the compressed archive). For the upload example, the
transformation would be taking an artifact with some set of files, uploading
those files, and returning an artifact with a single ID: the URL of the upload.
Prior to reading this page, it is assumed you have read the page on [plugin
development basics](/docs/extending/plugins).
Post-processor plugins implement the [`packer.PostProcessor`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#PostProcessor) interface and are
served using the `plugin.ServePostProcessor` function.
~> **Warning!** This is an advanced topic. If you're new to Packer, we
recommend getting a bit more comfortable before you dive into writing plugins.
This page explains how to implement and serve custom post-processors. If you want your post-processor to support HashiCorp Cloud Platform (HCP) Packer, you should also review the [HCP Packer Support](/docs/plugins/creation/hcp-support) documentation.
~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
## Before You Begin
We recommend reviewing the following resources before you begin development:
Packer Provisioners are the components of Packer that install and configure
software into a running machine prior to turning that machine into an image. An
example of a provisioner is the [shell
Packer provisioners install and configure software into a running machine prior to turning that machine into an image. For example, the [shell
provisioner](/docs/provisioners/shell), which runs shell scripts within
the machines.
Prior to reading this page, it is assumed you have read the page on [plugin
development basics](/docs/extending/plugins).
Provisioner plugins implement the [`packer.Provisioner`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#Provisioner) interface and are served
using the `plugin.ServeProvisioner` function.
~> **Warning!** This is an advanced topic. If you're new to Packer, we
recommend getting a bit more comfortable before you dive into writing plugins.
~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
## Before You Begin
We recommend reviewing the following resources before you begin development:
This page explains how to update a custom plugin so that it can publish image metadata to the [HCP Packer registry](https://cloud.hashicorp.com/docs/packer). Refer to [Custom Builders](/docs/plugins/creation/custom-builders) and [Custom Post-Processors](/docs/plugins/creation/custom-post-processors) for details about creating an external Packer plugin.
HCP Packer support allows for the management of image metadata that can be stored in a HCP Packer registry.
Before pushing metadata to the HCP Packer registry, Packer will use the [`par.artifact.metadata` key](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-constants)
to query a builder artifact for the Image metadata that a particular component would like to have stored in the registry.
Before pushing metadata to the HCP Packer registry, Packer uses the [`par.artifact.metadata` key](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-constants)
to query a builder artifact for the image metadata that a particular component would like to have stored in the registry.
For details and usage examples on management of image metadata, see the [Documentation](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image).
For details and examples of how to manage image metadata, refer to the [HCP Packer GitHub documentation](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image).
Packer is designed to be extensible, and supports plugins that allow you to
create and use custom builders, provisioners, post-processors, and data sources.
To learn more about developing these different types of components, please
choose a link from the sidebar. To learn more about the general plugin
architecture, stay on this page.
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](/docs/plugins/install-plugins).
## Developing Plugins
~> **Warning** This is an advanced topic. You should have strong knowledge of Packer before you start writing plugins.
This page will document how you can develop your own Packer plugins. Prior to
reading this, you should be comfortable with Packer and know the
basics of [how plugins work from a user standpoint](/docs/plugins).
## Language Requirements
Packer plugins must be written in [Go](https://go.dev/), so you should also
be familiar with the language.
You must write Packer plugins in [Go](https://go.dev/).
~> **Warning!** This is an advanced topic. If you're new to Packer, we
recommend getting a bit more comfortable before you dive into writing plugins.
### Plugin System Architecture
## Plugin System Architecture
A Packer plugin is just a Go binary. Instead of loading plugins directly into a
running application, Packer runs each plugin as a _separate application_.
@ -34,7 +26,7 @@ The multiple separate Packer plugin processes communicate with the Core using
an RPC defined in the packer-plugin SDK. The Packer core itself is responsible
launching and cleaning up the plugin processes.
### Plugin Development Basics
## Plugin Development Basics
The components that can be created and used in a Packer plugin are builders,
provisioners, post-processors, and data sources.
@ -163,7 +155,7 @@ the Packer codebase will continue to improve, potentially breaking APIs along
the way until there is a stable release. By locking your dependencies, your
plugins will continue to work with the version of Packer you lock to.
### Logging and Debugging
## Logging and Debugging
Plugins can use the standard Go `log` package to log. Anything logged using
this will be available in the Packer log files automatically. The Packer log is
@ -222,7 +214,7 @@ Here's what you need to create releases using GitHub Actions:
to install a plugin using `packer init`, see the
[init docs](/docs/commands/init).
### Registering Plugin Documentation
## Registering Plugin Documentation
~> Note: Registering a remote plugin's plugin documentation requires the use of [Packer's plugin docs configuration](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs).
@ -277,7 +269,7 @@ If a plugin maintainer wishes to only include a specific version of released doc
The `"sourceBranch"` key in the above configuration ensures potential contributors can link back to source files in the plugin repository from the Packer docs site. If a `"sourceBranch"` value is not present, it will default to `"main"`.
#### Testing Plugin Documentation
### Testing Plugin Documentation
Before publishing the `docs.zip` file, you might want to preview your documentation changes.
We provide a mechanism that allows to preview how the docs will look like within
@ -304,9 +296,9 @@ Follow the next steps to get the Packer website running and preview the document
In the website README, follow the steps to [run the website with node](https://github.com/hashicorp/packer/tree/main/website#with-node).
- Once the website is up and running, the plugin documentation should be available in `http://localhost:3000/docs`.
### Plugin Development Tips and FAQs
## Plugin Development Tips and FAQs
#### Working Examples
### Working Examples
Here's a non-exhaustive list of Packer plugins that you can check out:
@ -316,7 +308,7 @@ Here's a non-exhaustive list of Packer plugins that you can check out:
Looking at their code will give you good examples.
#### Naming Conventions
### Naming Conventions
It is standard practice to name the resulting plugin application in the format
of `packer-plugin-NAME`. For example, if you're building a new builder for
@ -324,7 +316,7 @@ CustomCloud, it would be standard practice to name the resulting plugin
`packer-plugin-customcloud`. This naming convention helps users identify the
scope of a plugin.
#### Testing Plugins
### Testing Plugins
Making your unpublished plugin available to Packer is possible by either:
@ -337,7 +329,7 @@ builder or source without needing to have a `required_plugin` block.
This is extremely useful during development.
#### Distributing Plugins
### Distributing Plugins
We recommend that you use a tool like the GoReleaser in order to cross-compile
your plugin for every platform that Packer supports, since Go applications are
Packer Plugins allow new functionality to be added to Packer without modifying
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.
page_title: Plugins
@ -8,22 +8,14 @@ page_title: Plugins
# Packer Plugins
Packer Plugins allow new functionality to be added to Packer without modifying
the core source code. **Packer plugins** are able to add new components to
Packer, such as **builders**, **provisioners**, **post-processors**, and **data
sources**.
Packer plugins are separate, standalone applications that perform tasks during each build.
This page documents how to install plugins. You can find a list of available
plugins in the [Plugins section](/plugins).
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.
If you're interested in developing plugins, see the [developing
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.
If you're a plugin maintainer interested in supporting HCP Packer, see the [HCP
- **Built-in Plugins:** Use [builders](/docs/builders) to create machines and images, [data sources](/docs/datasources) to fetch data, [provisioners](/docs/provisioners) to install and configure machine images, and [post-processors](/docs/post-processors) to perform additional tasks after provisioning
- **External Plugins:** Review the documentation for [available external plugins](/plugins) not included with the Packer binary
- **Installing Plugins:** [Installation Guides](/docs/plugins/install-plugins) to add external plugins to your Packer template and install the binaries
- **Developing Plugins:** Get started [creating custom external plugins](/docs/plugins/creation)
Install external Packer plugins that extend Packer functionality.
page_title: Install Plugins
---
Currently, you do not need to install plugins for builder, provisioner, or
post-processor components documented on the Packer website; these components
ship with the Packer core and Packer automatically knows how to find and launch
them. These instructions are for installing custom components that are not
bundled with the Packer core.
# Installing Plugins
The below tabs reference "multi-component" and "single-component" plugins. If
you are not sure what kind of plugin you are trying to install, the easiest way
to find out is to check the name. If the name starts with `packer-plugin-`, then
it is a multi-component plugin. If the name starts with a prefix that actually
says the component type (e.g. `packer-provisioner-` or `packer-builder`), then
it is a single-component plugin.
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](/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)">
@ -23,7 +29,7 @@ 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.
Packer Plugins allow new functionality to be added to Packer without modifying
the core source code. Packer plugins are able to add new components to Packer,
such as builders, provisioners, post-processors, and data sources.
External Packer plugins are standalone applications that extend Packer functionality without modifying the core source code. Plugins can add new components to Packer, such as builders, provisioners, post-processors, and data sources. Refer to [Packer Plugins](/docs/plugins) for details about installing and developing external plugins.
This page documents how to use plugins.
If you're interested in developing plugins, see the [developing
HashiBot
4 years ago
committed by
GitHub