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 CleanupClients()
• func Server() (*packrpc.Server, error)
• type Client
  • func NewClient(config *ClientConfig) (c *Client)
  • func (c *Client) Builder() (packer.Builder, error)
  • func (c *Client) Command() (packer.Command, error)
  • func (c *Client) Exited() bool
  • func (c *Client) Hook() (packer.Hook, error)
  • func (c *Client) Kill()
  • func (c *Client) PostProcessor() (packer.PostProcessor, error)
  • func (c *Client) Provisioner() (packer.Provisioner, error)
  • func (c *Client) Start() (addr net.Addr, err error)
• type ClientConfig

Constants

const APIVersion = "2"

The APIVersion is 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.

const MagicCookieKey = "PACKER_PLUGIN_MAGIC_COOKIE"

const MagicCookieValue = "d602bf8f470bc67ca7faa0386276bbdd4330efaf76d1a219cb4d6991ca9872b2"

Variables

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.

var Killed = false

If this is true, then the "unexpected EOF" panic will not be raised throughout the clients.

Functions

func CleanupClients

func CleanupClients()

This makes sure all the managed subprocesses are killed and properly logged. This should be called before the parent process running the plugins exits.

This must only be called _once_.

func Server

func Server() (*packrpc.Server, 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 Client

type Client struct {
	// contains filtered or unexported fields
}

Client handles the lifecycle of a plugin application, determining its RPC address, and returning various types of packer interface implementations across the multi-process communication layer.

func NewClient

func NewClient(config *ClientConfig) (c *Client)

Creates a new plugin client which manages the lifecycle of an external plugin and gets the address for the RPC connection.

The client must be cleaned up at some point by calling Kill(). If the client is a managed client (created with NewManagedClient) you can just call CleanupClients at the end of your program and they will be properly cleaned.

func (*Client) Builder

func (c *Client) Builder() (packer.Builder, error)

Returns a builder implementation that is communicating over this client. If the client hasn't been started, this will start it.

func (*Client) Command

func (c *Client) Command() (packer.Command, error)

Returns a command implementation that is communicating over this client. If the client hasn't been started, this will start it.

func (*Client) Exited

func (c *Client) Exited() bool

Tells whether or not the underlying process has exited.

func (*Client) Hook

func (c *Client) Hook() (packer.Hook, error)

Returns a hook implementation that is communicating over this client. If the client hasn't been started, this will start it.

func (*Client) Kill

func (c *Client) Kill()

End the executing subprocess (if it is running) and perform any cleanup tasks necessary such as capturing any remaining logs and so on.

This method blocks until the process successfully exits.

This method can safely be called multiple times.

func (*Client) PostProcessor

func (c *Client) PostProcessor() (packer.PostProcessor, error)

Returns a post-processor implementation that is communicating over this client. If the client hasn't been started, this will start it.

func (*Client) Provisioner

func (c *Client) Provisioner() (packer.Provisioner, error)

Returns a provisioner implementation that is communicating over this client. If the client hasn't been started, this will start it.

func (*Client) Start

func (c *Client) Start() (addr net.Addr, err error)

Starts the underlying subprocess, communicating with it to negotiate a port for RPC connections, and returning the address to connect via RPC.

This method is safe to call multiple times. Subsequent calls have no effect. Once a client has been started once, it cannot be started again, even if it was killed.

type ClientConfig

type ClientConfig struct {
	// The unstarted subprocess for starting the plugin.
	Cmd *exec.Cmd

	// Managed represents if the client should be managed by the
	// plugin package or not. If true, then by calling CleanupClients,
	// it will automatically be cleaned up. Otherwise, the client
	// user is fully responsible for making sure to Kill all plugin
	// clients. By default the client is _not_ managed.
	Managed bool

	// The minimum and maximum port to use for communicating with
	// the subprocess. If not set, this defaults to 10,000 and 25,000
	// respectively.
	MinPort, MaxPort uint

	// StartTimeout is the timeout to wait for the plugin to say it
	// has started successfully.
	StartTimeout time.Duration

	// If non-nil, then the stderr of the client will be written to here
	// (as well as the log).
	Stderr io.Writer
}

ClientConfig is the configuration used to initialize a new plugin client. After being used to initialize a plugin client, that configuration must not be modified again.