plugin

Documentation

Overview

The plugin package exposes functions and helpers for communicating to Terraform plugins which are implemented as standalone binary applications.

plugin.Client fully manages the lifecycle of executing the application, connecting to it, and returning the RPC client and service names for connecting to it using the terraform/rpc package.

plugin.Serve fully manages listeners to expose an RPC server from a binary that plugin.Client can connect to.

Index

• Constants
• Variables
• func CleanupClients()
• func Serve(opts *ServeOpts)
• type Client
  • func NewClient(config *ClientConfig) (c *Client)
  • func (c *Client) Client() (*tfrpc.Client, error)
  • func (c *Client) Exited() bool
  • func (c *Client) Kill()
  • func (c *Client) Start() (addr net.Addr, err error)
• type ClientConfig
• type ServeOpts

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 = "TF_PLUGIN_MAGIC_COOKIE"

The "magic cookie" is used to verify that the user intended to actually run this binary. If this cookie isn't present as an environmental variable, then we bail out early with an error.

const MagicCookieValue = "d602bf8f470bc67ca7faa0386276bbdd4330efaf76d1a219cb4d6991ca9872b2"

Variables

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 Serve

func Serve(opts *ServeOpts)

Serve serves the plugins given by ServeOpts.

Serve doesn't return until the plugin is done being executed. Any errors will be outputted to the log.

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 Terraform 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) Client

func (c *Client) Client() (*tfrpc.Client, error)

Client returns an RPC client for the plugin.

Subsequent calls to this will return the same RPC client.

func (*Client) Exited

func (c *Client) Exited() bool

Tells whether or not the underlying process has exited.

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) 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.

type ServeOpts

type ServeOpts struct {
	ProviderFunc    tfrpc.ProviderFunc
	ProvisionerFunc tfrpc.ProvisionerFunc
}

ServeOpts configures what sorts of plugins are served.