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.
120 lines
4.9 KiB
120 lines
4.9 KiB
---
|
|
description: >
|
|
Provisioners install and configure software prior to turning a machine into an image. Learn how to create custom provisioners that extend Packer functionality.
|
|
|
|
page_title: Create custom provisioners
|
|
---
|
|
|
|
# Create Custom Provisioners
|
|
|
|
Packer provisioners install and configure software into a running machine prior to turning that machine into an image. For example, the [shell provisioner](/packer/docs/provisioners/shell) runs shell scripts within machines.
|
|
|
|
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 that requires strong knowledge of Packer and Packer plugins.
|
|
|
|
## Before You Begin
|
|
|
|
We recommend reviewing the following resources before you begin development:
|
|
- [Developing Plugins - Overview](/packer/docs/plugins/creation)
|
|
- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language.
|
|
|
|
## The Interface
|
|
|
|
The interface that must be implemented for a provisioner is the
|
|
[`packer.Provisioner`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#Provisioner) interface. It is reproduced below for reference. The
|
|
actual interface in the source code contains some basic documentation as well
|
|
explaining what each method should do.
|
|
|
|
```go
|
|
type Provisioner interface {
|
|
ConfigSpec() hcldec.ObjectSpec
|
|
Prepare(...interface{}) error
|
|
Provision(context.Context, Ui, Communicator, map[string]interface{}) error
|
|
}
|
|
```
|
|
|
|
### The `Prepare` Method
|
|
|
|
The `Prepare` method for each provisioner is called prior to any runs with the
|
|
configuration that was given in the template. This is passed in as an array of
|
|
`interface{}` types, but is generally `map[string]interface{}`. The prepare
|
|
method is responsible for translating this configuration into an internal
|
|
structure, validating it, and returning any errors.
|
|
|
|
For multiple parameters, they should be merged together into the final
|
|
configuration, with later parameters overwriting any previous configuration.
|
|
The exact semantics of the merge are left to the builder author.
|
|
|
|
For decoding the `interface{}` into a meaningful structure, the
|
|
[mapstructure](https://github.com/mitchellh/mapstructure) library is
|
|
recommended. Mapstructure will take an `interface{}` and decode it into an
|
|
arbitrarily complex struct. If there are any errors, it generates very human
|
|
friendly errors that can be returned directly from the prepare method.
|
|
|
|
While it is not actively enforced, **no side effects** should occur from
|
|
running the `Prepare` method. Specifically, don't create files, don't launch
|
|
virtual machines, etc. Prepare's purpose is solely to configure the builder and
|
|
validate the configuration.
|
|
|
|
The `Prepare` method is called very early in the build process so that errors
|
|
may be displayed to the user before anything actually happens.
|
|
|
|
### The `ConfigSpec` Method
|
|
|
|
This method returns a `hcldec.ObjectSpec`, which is a spec necessary for using
|
|
HCL2 templates with Packer. For information on how to use and implement this
|
|
function, check our
|
|
[object spec docs](/packer/guides/hcl/component-object-spec)
|
|
|
|
### The `Provision` Method
|
|
|
|
The `Provision` method is called when a machine is running and ready to be
|
|
provisioned. The provisioner should do its real work here.
|
|
|
|
The method takes two parameters: a `packer.Ui` and a `packer.Communicator`. The
|
|
UI can be used to communicate with the user what is going on. The communicator
|
|
is used to communicate with the running machine, and is guaranteed to be
|
|
connected at this point.
|
|
|
|
The provision method should not return until provisioning is complete.
|
|
|
|
The map[string]interface{} provides users with build-specific information,
|
|
like host and IP, provided by the `build` template engine. Provisioners may use
|
|
this information however they please, or not use it.
|
|
|
|
## Using the Communicator
|
|
|
|
The `packer.Communicator` parameter and interface is used to communicate with
|
|
running machine. The machine may be local (in a virtual machine or container of
|
|
some sort) or it may be remote (in a cloud). The communicator interface
|
|
abstracts this away so that communication is the same overall.
|
|
|
|
The documentation around the [code
|
|
itself](https://godoc.org/github.com/hashicorp/packer-plugin-sdk/packer#Communicator)
|
|
is really great as an overview of how to use the interface. You should begin by
|
|
reading this. Once you have read it, you can see some example usage below:
|
|
|
|
```go
|
|
// Build the remote command.
|
|
var cmd packer.RemoteCmd
|
|
cmd.Command = "echo foo"
|
|
|
|
// We care about stdout, so lets collect that into a buffer. Since
|
|
// we don't set stderr, that will just be discarded.
|
|
var stdout bytes.Buffer
|
|
cmd.Stdout = &stdout
|
|
|
|
// Start the command
|
|
if err := comm.Start(&cmd); err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
// Wait for it to complete
|
|
cmd.Wait()
|
|
|
|
// Read the stdout!
|
|
fmt.Printf("Command output: %s", stdout.String())
|
|
```
|