plugin

Documentation

Overview

The plugin package provides the functionality to both expose a Packer plugin binary and to connect to an existing Packer plugin binary.

Packer supports plugins in the form of self-contained external static Go binaries. These binaries behave in a certain way (enforced by this package) and are connected to in a certain way (also enforced by this package).

Index

• Constants
• Variables
• func Server() (*packrpc.PluginServer, error)
• type Set
  • func NewSet() *Set
  • func (i *Set) RegisterBuilder(name string, builder packersdk.Builder)
  • func (i *Set) RegisterDatasource(name string, datasource packersdk.Datasource)
  • func (i *Set) RegisterPostProcessor(name string, postProcessor packersdk.PostProcessor)
  • func (i *Set) RegisterProvisioner(name string, provisioner packersdk.Provisioner)
  • func (i *Set) Run() error
  • func (i *Set) RunCommand(args ...string) error
  • func (i *Set) SetVersion(version *pluginVersion.PluginVersion)
• type SetDescription

Constants

const (
	// APIVersionMajor and APIVersionMinor are outputted along with the RPC
	// address. The plugin client validates this API version and will show an
	// error if it doesn't know how to speak it. Bumping APIVersionMajor, means
	// some endpoint was removed or an api was changed. It would be best if that
	// number never changed. Usually only APIVersionMinor should change when for
	// example we introduce a new plugin type, plugins that don't use that new
	// entrypoint don't need to update the SDK, but Packer will need to be
	// updated in order to communicate with these. Example Matrix:
	//   | Api Version \ Can Read  | old plugin-type                | datasources | new plugin type |
	//   |-------------------------|--------------------------------|-------------|-----------------|
	//   | 4                       | yes                            | No          | No              |
	//   | 5.0                     | yes                            | yes         | No              |
	//   | 5.1                     | yes                            | yes         | yes             |
	//   | 6.0                     | no (deprecated, so major bump) | yes         | yes             |
	//
	// Api version 4 did not have the notion of a minor version, so Packer will
	// error with a weird error message.
	APIVersionMajor, APIVersionMinor = "5", "0"
)

const DEFAULT_NAME = "-packer-default-plugin-name-"

Use this name to make the name of the plugin in the packer template match the multiplugin suffix, instead of requiring a second part. For example, calling :

pps.RegisterProvisioner(plugin.DEFAULT_NAME, new(CommentProvisioner))

On a plugin named `packer-plugin-foo`, will make the `foo` provisioner available with your CommentProvisioner doing that. There can only be one unnamed plugin per plugin type.

const MagicCookieKey = "PACKER_PLUGIN_MAGIC_COOKIE"

const MagicCookieValue = "d602bf8f470bc67ca7faa0386276bbdd4330efaf76d1a219cb4d6991ca9872b2"

const ProtocolVersion2 = "v2"

ProtocolVersion2 serves as a compatibility argument to the SetDescription so plugins can report whether or not they support protobuf/msgpack for serialising some of their entities (typically ObjectSpec) to protobuf.

If absent from the SetDescription, it means only gob is supported, and both Packer and the plugins should use that for communication.

Variables

var ErrManuallyStartedPlugin = errors.New(
	"Please do not execute plugins directly. Packer will execute these for you.")

var Interrupts int32 = 0

This is a count of the number of interrupts the process has received. This is updated with sync/atomic whenever a SIGINT is received and can be checked by the plugin safely to take action.

Functions

func Server

func Server() (*packrpc.PluginServer, error)

Server waits for a connection to this plugin and returns a Packer RPC server that you can use to register components and serve them.

Types

type Set

type Set struct {
	Builders       map[string]packersdk.Builder
	PostProcessors map[string]packersdk.PostProcessor
	Provisioners   map[string]packersdk.Provisioner
	Datasources    map[string]packersdk.Datasource
	// contains filtered or unexported fields
}

Set is a plugin set. It's API is meant to be very close to what is returned by plugin.Server It can describe itself or run a single plugin using the CLI arguments.

func NewSet

func NewSet() *Set

func (*Set) RegisterBuilder

func (i *Set) RegisterBuilder(name string, builder packersdk.Builder)

func (*Set) RegisterDatasource

func (i *Set) RegisterDatasource(name string, datasource packersdk.Datasource)

func (*Set) RegisterPostProcessor

func (i *Set) RegisterPostProcessor(name string, postProcessor packersdk.PostProcessor)

func (*Set) RegisterProvisioner

func (i *Set) RegisterProvisioner(name string, provisioner packersdk.Provisioner)

func (*Set) Run

func (i *Set) Run() error

Run takes the os Args and runs a packer plugin command from it.

• "describe" command makes the plugin set describe itself.
• "start builder builder-name" starts the builder "builder-name"
• "start post-processor example" starts the post-processor "example"

func (*Set) RunCommand

func (i *Set) RunCommand(args ...string) error

func (*Set) SetVersion

func (i *Set) SetVersion(version *pluginVersion.PluginVersion)

type SetDescription

type SetDescription struct {
	Version         string   `json:"version"`
	SDKVersion      string   `json:"sdk_version"`
	APIVersion      string   `json:"api_version"`
	Builders        []string `json:"builders"`
	PostProcessors  []string `json:"post_processors"`
	Provisioners    []string `json:"provisioners"`
	Datasources     []string `json:"datasources"`
	ProtocolVersion string   `json:"protocol_version"`
}

SetDescription describes a Set.