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 ¶
const APIVersion = "1"
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 ResourceProviderFactory ¶
func ResourceProviderFactory(cmd *exec.Cmd) terraform.ResourceProviderFactory
ResourceProviderFactory returns a Terraform ResourceProviderFactory that executes a plugin and connects to it.
func ResourceProvisionerFactory ¶
func ResourceProvisionerFactory(cmd *exec.Cmd) terraform.ResourceProvisionerFactory
ResourceProvisionerFactory returns a Terraform ResourceProvisionerFactory that executes a plugin and connects to it.
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 ¶
Client returns an RPC client for the plugin.
Subsequent calls to this will return the same RPC client.
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 ¶
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.
Source Files