plugins

Documentation

Overview

Package plugins provides structures and helper functions to manage Docker plugins.

Docker discovers plugins by looking for them in the plugin directory whenever a user or container tries to use one by name. UNIX domain socket files must be located under /run/docker/plugins, whereas spec files can be located either under /etc/docker/plugins or /usr/lib/docker/plugins. This is handled by the Registry interface, which lets you list all plugins or get a plugin by its name if it exists.

The plugins need to implement an HTTP server and bind this to the UNIX socket or the address specified in the spec files. A handshake is send at /Plugin.Activate, and plugins are expected to return a Manifest with a list of of Docker subsystems which this plugin implements.

In order to use a plugins, you can use the “Get“ with the name of the plugin and the subsystem it implements.

plugin, err := plugins.Get("example", "VolumeDriver")
if err != nil {
	return fmt.Errorf("Error looking up volume plugin example: %v", err)
}

Index

• Variables
• func Handle(iface string, fn func(string, *Client))
• type Client
  • func NewClient(addr string, tlsConfig tlsconfig.Options) (*Client, error)
  • func (c *Client) Call(serviceMethod string, args interface{}, ret interface{}) error
  • func (c *Client) SendFile(serviceMethod string, data io.Reader, ret interface{}) error
  • func (c *Client) Stream(serviceMethod string, args interface{}) (io.ReadCloser, error)
• type LocalRegistry
  • func (l *LocalRegistry) Plugin(name string) (*Plugin, error)
• type Manifest
• type Plugin
  • func Get(name, imp string) (*Plugin, error)
• type Registry

Variables

var (
	// ErrNotFound plugin not found
	ErrNotFound = errors.New("Plugin not found")
)

var (
	// ErrNotImplements is returned if the plugin does not implement the requested driver.
	ErrNotImplements = errors.New("Plugin does not implement the requested driver")
)

Functions

func Handle

func Handle(iface string, fn func(string, *Client))

Handle adds the specified function to the extpointHandlers.

Types

type Client

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

Client represents a plugin client.

func NewClient

func NewClient(addr string, tlsConfig tlsconfig.Options) (*Client, error)

NewClient creates a new plugin client (http).

func (*Client) Call

func (c *Client) Call(serviceMethod string, args interface{}, ret interface{}) error

Call calls the specified method with the specified arguments for the plugin. It will retry for 30 seconds if a failure occurs when calling.

func (*Client) SendFile

func (c *Client) SendFile(serviceMethod string, data io.Reader, ret interface{}) error

SendFile calls the specified method, and passes through the IO stream

func (*Client) Stream

func (c *Client) Stream(serviceMethod string, args interface{}) (io.ReadCloser, error)

Stream calls the specified method with the specified arguments for the plugin and returns the response body

type LocalRegistry

type LocalRegistry struct{}

LocalRegistry defines a registry that is local (using unix socket).

func (*LocalRegistry) Plugin

func (l *LocalRegistry) Plugin(name string) (*Plugin, error)

Plugin returns the plugin registered with the given name (or returns an error).

type Manifest

type Manifest struct {
	// List of subsystem the plugin implements.
	Implements []string
}

Manifest lists what a plugin implements.

type Plugin

type Plugin struct {
	// Name of the plugin
	Name string `json:"-"`
	// Address of the plugin
	Addr string
	// TLS configuration of the plugin
	TLSConfig tlsconfig.Options
	// Client attached to the plugin
	Client *Client `json:"-"`
	// Manifest of the plugin (see above)
	Manifest *Manifest `json:"-"`
	// contains filtered or unexported fields
}

Plugin is the definition of a docker plugin.

func Get

func Get(name, imp string) (*Plugin, error)

Get returns the plugin given the specified name and requested implementation.

type Registry

type Registry interface {
	// Plugins lists all plugins.
	Plugins() ([]*Plugin, error)
	// Plugin returns the plugin registered with the given name (or returns an error).
	Plugin(name string) (*Plugin, error)
}

Registry defines behavior of a registry of plugins.