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

• Constants
• Variables
• func Handle(iface string, fn func(string, *Client))
• func IsNotFound(err error) bool
• func SpecsPaths() []string
• func WithRequestTimeout(t time.Duration) func(*RequestOpts)
• type Client
  • func NewClient(addr string, tlsConfig *tlsconfig.Options) (*Client, error)
  • func NewClientWithTimeout(addr string, tlsConfig *tlsconfig.Options, timeout time.Duration) (*Client, error)
  • func (c *Client) Call(serviceMethod string, args, ret interface{}) error
  • func (c *Client) CallWithOptions(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 NewLocalRegistry() LocalRegistry
  • func (l *LocalRegistry) GetAll(imp string) ([]*Plugin, error)
  • func (l *LocalRegistry) Plugin(name string) (*Plugin, error)
  • func (l *LocalRegistry) Scan() ([]string, error)
• type Manifest
• type Plugin
  • func Get(name, imp string) (*Plugin, error)
  • func NewLocalPlugin(name, addr string) *Plugin
  • func (p *Plugin) Client() *Client
  • func (p *Plugin) IsV1() bool
  • func (p *Plugin) Name() string
  • func (p *Plugin) Protocol() string
  • func (p *Plugin) ScopedPath(s string) string
• type RequestOpts

Constants

const ProtocolSchemeHTTPV1 = "moby.plugins.http/v1"

ProtocolSchemeHTTPV1 is the name of the protocol used for interacting with plugins using this package.

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.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound indicates if the passed in error is from an http.StatusNotFound from the plugin

func SpecsPaths

func SpecsPaths() []string

SpecsPaths returns { "%programdata%\docker\plugins" } on Windows, { "/etc/docker/plugins", "/usr/lib/docker/plugins" } on Unix in non-rootless mode, { "$XDG_CONFIG_HOME/docker/plugins", "$HOME/.local/lib/docker/plugins" } on Unix in rootless mode with fallback to the corresponding path in non-rootless mode if $XDG_CONFIG_HOME or $HOME is not set.

func WithRequestTimeout

func WithRequestTimeout(t time.Duration) func(*RequestOpts)

WithRequestTimeout sets a timeout duration for plugin requests

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 NewClientWithTimeout

func NewClientWithTimeout(addr string, tlsConfig *tlsconfig.Options, timeout time.Duration) (*Client, error)

NewClientWithTimeout creates a new plugin client (http).

func (*Client) Call

func (c *Client) Call(serviceMethod string, args, 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) CallWithOptions

func (c *Client) CallWithOptions(serviceMethod string, args interface{}, ret interface{}, opts ...func(*RequestOpts)) error

CallWithOptions is just like call except it takes options

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 {
	SpecsPaths func() []string
}

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

func NewLocalRegistry

func NewLocalRegistry() LocalRegistry

func (*LocalRegistry) GetAll

func (l *LocalRegistry) GetAll(imp string) ([]*Plugin, error)

GetAll returns all the plugins for the specified implementation

func (*LocalRegistry) Plugin

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

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

func (*LocalRegistry) Scan

func (l *LocalRegistry) Scan() ([]string, error)

Scan scans all the plugin paths and returns all the names it found

type Manifest

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

Manifest lists what a plugin implements.

type Plugin

type Plugin struct {

	// Address of the plugin
	Addr string
	// TLS configuration of the plugin
	TLSConfig *tlsconfig.Options

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

func NewLocalPlugin

func NewLocalPlugin(name, addr string) *Plugin

NewLocalPlugin creates a new local plugin.

func (*Plugin) Client

func (p *Plugin) Client() *Client

Client returns a ready-to-use plugin client that can be used to communicate with the plugin.

func (*Plugin) IsV1

func (p *Plugin) IsV1() bool

IsV1 returns true for V1 plugins and false otherwise.

func (*Plugin) Name

func (p *Plugin) Name() string

Name returns the name of the plugin.

func (*Plugin) Protocol

func (p *Plugin) Protocol() string

Protocol returns the protocol name/version used for plugins in this package.

func (*Plugin) ScopedPath

func (p *Plugin) ScopedPath(s string) string

ScopedPath returns the path scoped to the plugin's rootfs. For v1 plugins, this always returns the path unchanged as v1 plugins run directly on the host.

type RequestOpts

type RequestOpts struct {
	Timeout time.Duration
}

RequestOpts is the set of options that can be passed into a request