mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00

Brian Goff 0e8e8f0f31 Add support for metrics plugins

Allows for a plugin type that can be used to scrape metrics.
This is useful because metrics are not neccessarily at a standard
location... `--metrics-addr` must be set, and must currently be a TCP
socket.
Even if metrics are done via a unix socket, there's no guarentee where
the socket may be located on the system, making bind-mounting such a
socket into a container difficult (and racey, failure-prone on daemon
restart).

Metrics plugins side-step this issue by always listening on a unix
socket and then bind-mounting that into a known path in the plugin
container.

Note there has been similar work in the past (and ultimately punted at
the time) for consistent access to the Docker API from within a
container.

Why not add metrics to the Docker API and just provide a plugin with
access to the Docker API? Certainly this can be useful, but gives a lot
of control/access to a plugin that may only need the metrics. We can
look at supporting API plugins separately for this reason.

Signed-off-by: Brian Goff <cpuguy83@gmail.com>

2017-05-12 00:30:09 -04:00

6 KiB

Raw Blame History

title	description	keywords
Plugin config	How develop and use a plugin with the managed plugin system	API, Usage, plugins, documentation, developer

Plugin Config Version 1 of Plugin V2

This document outlines the format of the V0 plugin configuration. The plugin config described herein was introduced in the Docker daemon in the v1.12.0 release.

Plugin configs describe the various constituents of a docker plugin. Plugin configs can be serialized to JSON format with the following media types:

Config Type	Media Type
config	"application/vnd.docker.plugin.v1+json"

Config Field Descriptions

Config provides the base accessible fields for working with V0 plugin format in the registry.

description string

description of the plugin
documentation string

link to the documentation about the plugin
interface PluginInterface

interface implemented by the plugins, struct consisting of the following fields
- types string array
  
  types indicate what interface(s) the plugin currently implements.
  
  currently supported:
  - docker.volumedriver/1.0
  - docker.networkdriver/1.0
  - docker.ipamdriver/1.0
  - docker.authz/1.0
  - docker.logdriver/1.0
  - docker.metricscollector/1.0
- socket string
  
  socket is the name of the socket the engine should use to communicate with the plugins. the socket will be created in /run/docker/plugins.
entrypoint string array

entrypoint of the plugin, see ENTRYPOINT
workdir string

workdir of the plugin, see WORKDIR
network PluginNetwork

network of the plugin, struct consisting of the following fields
- type string
  
  network type.
  
  currently supported:
  
  - bridge - host - none
mounts PluginMount array

mount of the plugin, struct consisting of the following fields, see MOUNTS
- name string
  
  name of the mount.
- description string
  
  description of the mount.
- source string
  
  source of the mount.
- destination string
  
  destination of the mount.
- type string
  
  mount type.
- options string array
  
  options of the mount.
ipchost boolean Access to host ipc namespace.
pidhost boolean Access to host pid namespace.
propagatedMount string

path to be mounted as rshared, so that mounts under that path are visible to docker. This is useful for volume plugins. This path will be bind-mounted outisde of the plugin rootfs so it's contents are preserved on upgrade.
env PluginEnv array

env of the plugin, struct consisting of the following fields
- name string
  
  name of the env.
- description string
  
  description of the env.
- value string
  
  value of the env.
args PluginArgs

args of the plugin, struct consisting of the following fields
- name string
  
  name of the args.
- description string
  
  description of the args.
- value string array
  
  values of the args.
linux PluginLinux
- capabilities string array
  
  capabilities of the plugin (Linux only), see list here
- allowAllDevices boolean
  
  If /dev is bind mounted from the host, and allowAllDevices is set to true, the plugin will have rwm access to all devices on the host.
- devices PluginDevice array
  
  device of the plugin, (Linux only), struct consisting of the following fields, see DEVICES
  - name string
    
    name of the device.
  - description string
    
    description of the device.
  - path string
    
    path of the device.

Example Config

Example showing the 'tiborvass/sample-volume-plugin' plugin config.

{
            "Args": {
                "Description": "",
                "Name": "",
                "Settable": null,
                "Value": null
            },
            "Description": "A sample volume plugin for Docker",
            "Documentation": "https://docs.docker.com/engine/extend/plugins/",
            "Entrypoint": [
                "/usr/bin/sample-volume-plugin",
                "/data"
            ],
            "Env": [
                {
                    "Description": "",
                    "Name": "DEBUG",
                    "Settable": [
                        "value"
                    ],
                    "Value": "0"
                }
            ],
            "Interface": {
                "Socket": "plugin.sock",
                "Types": [
                    "docker.volumedriver/1.0"
                ]
            },
            "Linux": {
                "Capabilities": null,
                "AllowAllDevices": false,
                "Devices": null
            },
            "Mounts": null,
            "Network": {
                "Type": ""
            },
            "PropagatedMount": "/data",
            "User": {},
            "Workdir": ""
}

6 KiB Raw Blame History

Plugin Config Version 1 of Plugin V2

Config Field Descriptions

Example Config

6 KiB

Raw Blame History