diff --git a/docs/extend/config.md b/docs/extend/config.md index 6af92c55b451..1f96d3e00930 100644 --- a/docs/extend/config.md +++ b/docs/extend/config.md @@ -1,192 +1,185 @@ --- description: "How to develop and use a plugin with the managed plugin system" keywords: "API, Usage, plugins, documentation, developer" +title: Plugin Config Version 1 of Plugin V2 --- - - - -# Plugin Config Version 1 of Plugin V2 - This document outlines the format of the V0 plugin configuration. -Plugin configs describe the various constituents of a docker plugin. Plugin -configs can be serialized to JSON format with the following media types: +Plugin configs describe the various constituents of a Docker engine 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 | `application/vnd.docker.plugin.v1+json` | -## *Config* Field Descriptions +## Config Field Descriptions -Config provides the base accessible fields for working with V0 plugin format - in the registry. +Config provides the base accessible fields for working with V0 plugin format in +the registry. -- **`description`** *string* +- `description` string - description of the plugin + Description of the plugin -- **`documentation`** *string* +- `documentation` string - link to the documentation about the plugin + Link to the documentation about the plugin -- **`interface`** *PluginInterface* +- `interface` PluginInterface - interface implemented by the plugins, struct consisting of the following fields + Interface implemented by the plugins, struct consisting of the following fields: - - **`types`** *string array* + - `types` string array - types indicate what interface(s) the plugin currently implements. + Types indicate what interface(s) the plugin currently implements. - currently supported: + Supported types: - - **docker.volumedriver/1.0** + - `docker.volumedriver/1.0` - - **docker.networkdriver/1.0** + - `docker.networkdriver/1.0` - - **docker.ipamdriver/1.0** + - `docker.ipamdriver/1.0` - - **docker.authz/1.0** + - `docker.authz/1.0` - - **docker.logdriver/1.0** + - `docker.logdriver/1.0` - - **docker.metricscollector/1.0** + - `docker.metricscollector/1.0` - - **`socket`** *string* + - `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`. + 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`** *string array* + Entrypoint of the plugin, see [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) - entrypoint of the plugin, see [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) +- `workdir` string -- **`workdir`** *string* + Working directory of the plugin, see [`WORKDIR`](https://docs.docker.com/engine/reference/builder/#workdir) - workdir of the plugin, see [`WORKDIR`](https://docs.docker.com/engine/reference/builder/#workdir) +- `network` PluginNetwork -- **`network`** *PluginNetwork* + Network of the plugin, struct consisting of the following fields: - network of the plugin, struct consisting of the following fields + - `type` string - - **`type`** *string* + Network type. - network type. + Supported types: - currently supported: + - `bridge` + - `host` + - `none` - - **bridge** - - **host** - - **none** +- `mounts` PluginMount array -- **`mounts`** *PluginMount array* + Mount of the plugin, struct consisting of the following fields. + See [`MOUNTS`](https://github.com/opencontainers/runtime-spec/blob/master/config.md#mounts). - mount of the plugin, struct consisting of the following fields, see [`MOUNTS`](https://github.com/opencontainers/runtime-spec/blob/master/config.md#mounts) + - `name` string - - **`name`** *string* + Name of the mount. - name of the mount. + - `description` string - - **`description`** *string* + Description of the mount. - description of the mount. + - `source` string - - **`source`** *string* + Source of the mount. - source of the mount. + - `destination` string - - **`destination`** *string* + Destination of the mount. - destination of the mount. + - `type` string - - **`type`** *string* + Mount type. - mount type. + - `options` string array - - **`options`** *string array* + Options of the mount. - options of the mount. +- `ipchost` Boolean -- **`ipchost`** *boolean* Access to host ipc namespace. -- **`pidhost`** *boolean* - Access to host pid namespace. -- **`propagatedMount`** *string* +- `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 outside of the plugin rootfs so it's contents - are preserved on upgrade. + 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 + outside of the plugin rootfs so it's contents are preserved on upgrade. -- **`env`** *PluginEnv array* +- `env` PluginEnv array - env of the plugin, struct consisting of the following fields + Environment variables of the plugin, struct consisting of the following fields: - - **`name`** *string* + - `name` string - name of the env. + Name of the environment variable. - - **`description`** *string* + - `description` string - description of the env. + Description of the environment variable. - - **`value`** *string* + - `value` string - value of the env. + Value of the environment variable. -- **`args`** *PluginArgs* +- `args` PluginArgs - args of the plugin, struct consisting of the following fields + Arguments of the plugin, struct consisting of the following fields: - - **`name`** *string* + - `name` string - name of the args. + Name of the arguments. - - **`description`** *string* + - `description` string - description of the args. + Description of the arguments. - - **`value`** *string array* + - `value` string array - values of the args. + Values of the arguments. -- **`linux`** *PluginLinux* +- `linux` PluginLinux - - **`capabilities`** *string array* + - `capabilities` string array - capabilities of the plugin (*Linux only*), see list [`here`](https://github.com/opencontainers/runc/blob/master/libcontainer/SPEC.md#security) + Capabilities of the plugin (Linux only), see list [`here`](https://github.com/opencontainers/runc/blob/master/libcontainer/SPEC.md#security) - - **`allowAllDevices`** *boolean* + - `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. + 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* + - `devices` PluginDevice array - device of the plugin, (*Linux only*), struct consisting of the following fields, see [`DEVICES`](https://github.com/opencontainers/runtime-spec/blob/master/config-linux.md#devices) + Device of the plugin, (Linux only), struct consisting of the following fields. + See [`DEVICES`](https://github.com/opencontainers/runtime-spec/blob/master/config-linux.md#devices). - - **`name`** *string* + - `name` string - name of the device. + Name of the device. - - **`description`** *string* + - `description` string - description of the device. + Description of the device. - - **`path`** *string* + - `path` string - path of the device. + Path of the device. ## Example Config -*Example showing the 'tiborvass/sample-volume-plugin' plugin config.* +The following example shows the 'tiborvass/sample-volume-plugin' plugin config. ```json { diff --git a/docs/extend/index.md b/docs/extend/index.md index b0c2f29589fb..22ab0f3f3066 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -1,24 +1,14 @@ --- +title: Docker Engine managed plugin system description: Develop and use a plugin with the managed plugin system keywords: "API, Usage, plugins, documentation, developer" --- - - -# Docker Engine managed plugin system - - [Installing and using a plugin](index.md#installing-and-using-a-plugin) - [Developing a plugin](index.md#developing-a-plugin) - [Debugging plugins](index.md#debugging-plugins) -Docker Engine's plugin system allows you to install, start, stop, and remove +Docker Engine's plugin system lets you install, start, stop, and remove plugins using Docker Engine. For information about legacy (non-managed) plugins, refer to @@ -49,78 +39,78 @@ enabled, and use it to create a volume. > **Note** > > This example is intended for instructional purposes only. Once the volume is -> created, your SSH password to the remote host will be exposed as plaintext -> when inspecting the volume. You should delete the volume as soon as you are -> done with the example. +> created, your SSH password to the remote host is exposed as plaintext when +> inspecting the volume. Delete the volume as soon as you are done with the +> example. -1. Install the `sshfs` plugin. +1. Install the `sshfs` plugin. - ```console - $ docker plugin install vieux/sshfs + ```console + $ docker plugin install vieux/sshfs - Plugin "vieux/sshfs" is requesting the following privileges: - - network: [host] - - capabilities: [CAP_SYS_ADMIN] - Do you grant the above permissions? [y/N] y + Plugin "vieux/sshfs" is requesting the following privileges: + - network: [host] + - capabilities: [CAP_SYS_ADMIN] + Do you grant the above permissions? [y/N] y - vieux/sshfs - ``` + vieux/sshfs + ``` - The plugin requests 2 privileges: + The plugin requests 2 privileges: - - It needs access to the `host` network. - - It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run - the `mount` command. + - It needs access to the `host` network. + - It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run + the `mount` command. -2. Check that the plugin is enabled in the output of `docker plugin ls`. +2. Check that the plugin is enabled in the output of `docker plugin ls`. - ```console - $ docker plugin ls + ```console + $ docker plugin ls - ID NAME TAG DESCRIPTION ENABLED - 69553ca1d789 vieux/sshfs latest the `sshfs` plugin true - ``` + ID NAME TAG DESCRIPTION ENABLED + 69553ca1d789 vieux/sshfs latest the `sshfs` plugin true + ``` -3. Create a volume using the plugin. - This example mounts the `/remote` directory on host `1.2.3.4` into a - volume named `sshvolume`. +3. Create a volume using the plugin. + This example mounts the `/remote` directory on host `1.2.3.4` into a + volume named `sshvolume`. - This volume can now be mounted into containers. + This volume can now be mounted into containers. - ```console - $ docker volume create \ - -d vieux/sshfs \ - --name sshvolume \ - -o sshcmd=user@1.2.3.4:/remote \ - -o password=$(cat file_containing_password_for_remote_host) + ```console + $ docker volume create \ + -d vieux/sshfs \ + --name sshvolume \ + -o sshcmd=user@1.2.3.4:/remote \ + -o password=$(cat file_containing_password_for_remote_host) - sshvolume - ``` + sshvolume + ``` -4. Verify that the volume was created successfully. +4. Verify that the volume was created successfully. - ```console - $ docker volume ls + ```console + $ docker volume ls - DRIVER NAME - vieux/sshfs sshvolume - ``` + DRIVER NAME + vieux/sshfs sshvolume + ``` -5. Start a container that uses the volume `sshvolume`. +5. Start a container that uses the volume `sshvolume`. - ```console - $ docker run --rm -v sshvolume:/data busybox ls /data + ```console + $ docker run --rm -v sshvolume:/data busybox ls /data - - ``` + + ``` -6. Remove the volume `sshvolume` +6. Remove the volume `sshvolume` - ```console - $ docker volume rm sshvolume + ```console + $ docker volume rm sshvolume - sshvolume - ``` + sshvolume + ``` To disable a plugin, use the `docker plugin disable` command. To completely remove it, use the `docker plugin remove` command. For other available @@ -134,8 +124,10 @@ commands and options, see the The `rootfs` directory represents the root filesystem of the plugin. In this example, it was created from a Dockerfile: -> **Note:** The `/run/docker/plugins` directory is mandatory inside of the -> plugin's filesystem for docker to communicate with the plugin. +> **Note** +> +> The `/run/docker/plugins` directory is mandatory inside of the +> plugin's filesystem for Docker to communicate with the plugin. ```console $ git clone https://github.com/vieux/docker-volume-sshfs @@ -219,11 +211,10 @@ INFO[0421] Path Called... Returned path /data/samplevol plugin=f52a3df433b9a INFO[0421] Unmount Called... Unmounted samplevol plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 ``` -#### Using docker-runc to obtain logfiles and shell into the plugin. +#### Using runc to obtain logfiles and shell into the plugin. -`docker-runc`, the default docker container runtime can be used for debugging -plugins. This is specifically useful to collect plugin logs if they are -redirected to a file. +Use `runc`, the default docker container runtime, for debugging plugins by +collecting plugin logs redirected to a file. ```console $ sudo runc --root /run/docker/runtime-runc/plugins.moby list diff --git a/docs/extend/legacy_plugins.md b/docs/extend/legacy_plugins.md index 31a8a655fba9..0086761c1929 100644 --- a/docs/extend/legacy_plugins.md +++ b/docs/extend/legacy_plugins.md @@ -1,21 +1,11 @@ --- +title: Use Docker Engine plugins aliases: - "/engine/extend/plugins/" description: "How to add additional functionality to Docker with plugins extensions" keywords: "Examples, Usage, plugins, docker, documentation, user guide" --- - - -# Use Docker Engine plugins - This document describes the Docker Engine plugins generally available in Docker Engine. To view information on plugins managed by Docker, refer to [Docker Engine plugin system](index.md). @@ -40,7 +30,7 @@ Follow the instructions in the plugin's documentation. ## Finding a plugin -The sections below provide an inexhaustive overview of available plugins. +The sections below provide an overview of available third-party plugins. ### Network plugins @@ -97,4 +87,4 @@ of the plugin for help. The Docker team may not be able to assist you. ## Writing a plugin If you are interested in writing a plugin for Docker, or seeing how they work -under the hood, see the [docker plugins reference](plugin_api.md). +under the hood, see the [Docker plugins reference](plugin_api.md). diff --git a/docs/extend/plugin_api.md b/docs/extend/plugin_api.md index 812b465085bf..66a7bb0e21c5 100644 --- a/docs/extend/plugin_api.md +++ b/docs/extend/plugin_api.md @@ -1,19 +1,9 @@ --- +title: Docker Plugin API description: "How to write Docker plugins extensions " keywords: "API, Usage, plugins, documentation, developer" --- - - -# Docker Plugin API - Docker plugins are out-of-process extensions which add capabilities to the Docker Engine. @@ -26,8 +16,8 @@ If you just want to learn about or use Docker plugins, look ## What plugins are -A plugin is a process running on the same or a different host as the docker daemon, -which registers itself by placing a file on the same docker host in one of the plugin +A plugin is a process running on the same or a different host as the Docker daemon, +which registers itself by placing a file on the same Docker host in one of the plugin directories described in [Plugin discovery](#plugin-discovery). Plugins have human-readable names, which are short, lowercase strings. For @@ -43,26 +33,26 @@ user or container tries to use one by name. There are three types of files which can be put in the plugin directory. -* `.sock` files are UNIX domain sockets. +* `.sock` files are Unix domain sockets. * `.spec` files are text files containing a URL, such as `unix:///other.sock` or `tcp://localhost:8080`. * `.json` files are text files containing a full json specification for the plugin. -Plugins with UNIX domain socket files must run on the same docker host, whereas -plugins with spec or json files can run on a different host if a remote URL is specified. +Plugins with Unix domain socket files must run on the same Docker host. +Plugins with `.spec` or `.json` files can run on a different host if you specify a remote URL. -UNIX domain socket files must be located under `/run/docker/plugins`, whereas +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`. The name of the file (excluding the extension) determines the plugin name. -For example, the `flocker` plugin might create a UNIX socket at +For example, the `flocker` plugin might create a Unix socket at `/run/docker/plugins/flocker.sock`. You can define each plugin into a separated subdirectory if you want to isolate definitions from each other. For example, you can create the `flocker` socket under `/run/docker/plugins/flocker/flocker.sock` and only mount `/run/docker/plugins/flocker` inside the `flocker` container. -Docker always searches for unix sockets in `/run/docker/plugins` first. It checks for spec or json files under +Docker always searches for Unix sockets in `/run/docker/plugins` first. It checks for spec or json files under `/etc/docker/plugins` and `/usr/lib/docker/plugins` if the socket doesn't exist. The directory scan stops as soon as it finds the first plugin definition with the given name. @@ -87,7 +77,7 @@ The `TLSConfig` field is optional and TLS will only be verified if this configur ## Plugin lifecycle -Plugins should be started before Docker, and stopped after Docker. For +Plugins should be started before Docker, and stopped after Docker. For example, when packaging a plugin for a platform which supports `systemd`, you might use [`systemd` dependencies]( https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to @@ -103,7 +93,7 @@ When a plugin is first referred to -- either by a user referring to it by name use a plugin being started -- Docker looks for the named plugin in the plugin directory and activates it with a handshake. See Handshake API below. -Plugins are *not* activated automatically at Docker daemon startup. Rather, +Plugins are not activated automatically at Docker daemon startup. Rather, they are activated only lazily, or on-demand, when they are needed. ## Systemd socket activation @@ -149,8 +139,8 @@ or if one of the plugin goes down accidentally). The Plugin API is RPC-style JSON over HTTP, much like webhooks. -Requests flow *from* the Docker daemon *to* the plugin. So the plugin needs to -implement an HTTP server and bind this to the UNIX socket mentioned in the +Requests flow from the Docker daemon to the plugin. The plugin needs to +implement an HTTP server and bind this to the Unix socket mentioned in the "plugin discovery" section. All requests are HTTP `POST` requests. diff --git a/docs/extend/plugins_authorization.md b/docs/extend/plugins_authorization.md index 203c1bf2e23b..ad6f6dfa6ba2 100644 --- a/docs/extend/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -1,22 +1,12 @@ --- +title: Access authorization plugin description: "How to create authorization plugins to manage access control to your Docker daemon." keywords: "security, authorization, authentication, docker, documentation, plugin, extend" aliases: - "/engine/extend/authorization/" --- - - -# Access authorization plugin - -This document describes the Docker Engine plugins generally available in Docker +This document describes the Docker Engine plugins available in Docker Engine. To view information on plugins managed by Docker Engine, refer to [Docker Engine plugin system](index.md). @@ -41,7 +31,7 @@ third-party components using a generic API. The access authorization subsystem was built using this mechanism. Using this subsystem, you don't need to rebuild the Docker daemon to add an -authorization plugin. You can add a plugin to an installed Docker daemon. You do +authorization plugin. You can add a plugin to an installed Docker daemon. You do need to restart the Docker daemon to add a new plugin. An authorization plugin approves or denies requests to the Docker daemon based @@ -158,56 +148,56 @@ should implement the following two methods: #### /AuthZPlugin.AuthZReq -**Request**: - -```json -{ - "User": "The user identification", - "UserAuthNMethod": "The authentication method used", - "RequestMethod": "The HTTP method", - "RequestURI": "The HTTP request URI", - "RequestBody": "Byte array containing the raw HTTP request body", - "RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string " -} -``` - -**Response**: - -```json -{ - "Allow": "Determined whether the user is allowed or not", - "Msg": "The authorization message", - "Err": "The error message if things go wrong" -} -``` +- Request + + ```json + { + "User": "The user identification", + "UserAuthNMethod": "The authentication method used", + "RequestMethod": "The HTTP method", + "RequestURI": "The HTTP request URI", + "RequestBody": "Byte array containing the raw HTTP request body", + "RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string " + } + ``` + +- Response + + ```json + { + "Allow": "Determined whether the user is allowed or not", + "Msg": "The authorization message", + "Err": "The error message if things go wrong" + } + ``` #### /AuthZPlugin.AuthZRes -**Request**: - -```json -{ - "User": "The user identification", - "UserAuthNMethod": "The authentication method used", - "RequestMethod": "The HTTP method", - "RequestURI": "The HTTP request URI", - "RequestBody": "Byte array containing the raw HTTP request body", - "RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string", - "ResponseBody": "Byte array containing the raw HTTP response body", - "ResponseHeader": "Byte array containing the raw HTTP response header as a map[string][]string", - "ResponseStatusCode":"Response status code" -} -``` - -**Response**: - -```json -{ - "Allow": "Determined whether the user is allowed or not", - "Msg": "The authorization message", - "Err": "The error message if things go wrong" -} -``` +- Request: + + ```json + { + "User": "The user identification", + "UserAuthNMethod": "The authentication method used", + "RequestMethod": "The HTTP method", + "RequestURI": "The HTTP request URI", + "RequestBody": "Byte array containing the raw HTTP request body", + "RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string", + "ResponseBody": "Byte array containing the raw HTTP response body", + "ResponseHeader": "Byte array containing the raw HTTP response header as a map[string][]string", + "ResponseStatusCode":"Response status code" + } + ``` + +- Response: + + ```json + { + "Allow": "Determined whether the user is allowed or not", + "Msg": "The authorization message", + "Err": "The error message if things go wrong" + } + ``` ### Request authorization @@ -248,9 +238,9 @@ Request method | string | The HTTP method (GET/DELETE/POST) Request URI | string | The HTTP request URI including API version (e.g., v.1.17/containers/json) Request headers | map[string]string | Request headers as key value pairs (without the authorization header) Request body | []byte | Raw request body -Response status code | int | Status code from the docker daemon +Response status code | int | Status code from the Docker daemon Response headers | map[string]string | Response headers as key value pairs -Response body | []byte | Raw docker daemon response body +Response body | []byte | Raw Docker daemon response body #### Plugin -> Daemon diff --git a/docs/extend/plugins_logging.md b/docs/extend/plugins_logging.md index d6ce96cfb380..254fb585b476 100644 --- a/docs/extend/plugins_logging.md +++ b/docs/extend/plugins_logging.md @@ -1,19 +1,9 @@ --- +title: Docker log driver plugins description: "Log driver plugins." keywords: "Examples, Usage, plugins, docker, documentation, user guide, logging" --- - - -# Docker log driver plugins - This document describes logging driver plugins for Docker. Logging drivers enables users to forward container logs to another service for @@ -46,76 +36,77 @@ receiving logs for. Logs will be streamed over the defined file in the request. On Linux this file is a FIFO. Logging plugins are not currently supported on Windows. -**Request**: -```json -{ - "File": "/path/to/file/stream", - "Info": { - "ContainerID": "123456" - } -} -``` - -`File` is the path to the log stream that needs to be consumed. Each call to -`StartLogging` should provide a different file path, even if it's a container -that the plugin has already received logs for prior. The file is created by -docker with a randomly generated name. - -`Info` is details about the container that's being logged. This is fairly -free-form, but is defined by the following struct definition: - -```go -type Info struct { - Config map[string]string - ContainerID string - ContainerName string - ContainerEntrypoint string - ContainerArgs []string - ContainerImageID string - ContainerImageName string - ContainerCreated time.Time - ContainerEnv []string - ContainerLabels map[string]string - LogPath string - DaemonName string -} -``` - - -`ContainerID` will always be supplied with this struct, but other fields may be -empty or missing. - -**Response** -```json -{ - "Err": "" -} -``` - -If an error occurred during this request, add an error message to the `Err` field -in the response. If no error then you can either send an empty response (`{}`) -or an empty value for the `Err` field. - -The driver should at this point be consuming log messages from the passed in file. -If messages are unconsumed, it may cause the container to block while trying to -write to its stdio streams. - -Log stream messages are encoded as protocol buffers. The protobuf definitions are -in the -[docker repository](https://github.com/docker/docker/blob/master/api/types/plugins/logdriver/entry.proto). - -Since protocol buffers are not self-delimited you must decode them from the stream -using the following stream format: - -``` -[size][message] -``` - -Where `size` is a 4-byte big endian binary encoded uint32. `size` in this case -defines the size of the next message. `message` is the actual log entry. - -A reference golang implementation of a stream encoder/decoder can be found -[here](https://github.com/docker/docker/blob/master/api/types/plugins/logdriver/io.go) +- Request + + ```json + { + "File": "/path/to/file/stream", + "Info": { + "ContainerID": "123456" + } + } + ``` + + `File` is the path to the log stream that needs to be consumed. Each call to + `StartLogging` should provide a different file path, even if it's a container + that the plugin has already received logs for prior. The file is created by + Docker with a randomly generated name. + + `Info` is details about the container that's being logged. This is fairly + free-form, but is defined by the following struct definition: + + ```go + type Info struct { + Config map[string]string + ContainerID string + ContainerName string + ContainerEntrypoint string + ContainerArgs []string + ContainerImageID string + ContainerImageName string + ContainerCreated time.Time + ContainerEnv []string + ContainerLabels map[string]string + LogPath string + DaemonName string + } + ``` + + `ContainerID` will always be supplied with this struct, but other fields may be + empty or missing. + +- Response + + ```json + { + "Err": "" + } + ``` + + If an error occurred during this request, add an error message to the `Err` field + in the response. If no error then you can either send an empty response (`{}`) + or an empty value for the `Err` field. + + The driver should at this point be consuming log messages from the passed in file. + If messages are unconsumed, it may cause the container to block while trying to + write to its stdio streams. + + Log stream messages are encoded as protocol buffers. The protobuf definitions are + in the + [moby repository](https://github.com/moby/moby/blob/master/api/types/plugins/logdriver/entry.proto). + + Since protocol buffers are not self-delimited you must decode them from the stream + using the following stream format: + + ```text + [size][message] + ``` + + Where `size` is a 4-byte big endian binary encoded uint32. `size` in this case + defines the size of the next message. `message` is the actual log entry. + + A reference golang implementation of a stream encoder/decoder can be found + [here](https://github.com/docker/docker/blob/master/api/types/plugins/logdriver/io.go) ### `/LogDriver.StopLogging` @@ -127,23 +118,25 @@ losing log data. Requests on this endpoint does not mean that the container has been removed only that it has stopped. -**Request**: -```json -{ - "File": "/path/to/file/stream" -} -``` +- Request + + ```json + { + "File": "/path/to/file/stream" + } + ``` -**Response**: -```json -{ - "Err": "" -} -``` +- Response -If an error occurred during this request, add an error message to the `Err` field -in the response. If no error then you can either send an empty response (`{}`) -or an empty value for the `Err` field. + ```json + { + "Err": "" + } + ``` + + If an error occurred during this request, add an error message to the `Err` field + in the response. If no error then you can either send an empty response (`{}`) + or an empty value for the `Err` field. ## Optional endpoints @@ -154,17 +147,19 @@ Logging plugins can implement two extra logging endpoints: Defines the capabilities of the log driver. You must implement this endpoint for Docker to be able to take advantage of any of the defined capabilities. -**Request**: -```json -{} -``` +- Request + + ```json + {} + ``` + +- Response -**Response**: -```json -{ - "ReadLogs": true -} -``` + ```json + { + "ReadLogs": true + } + ``` Supported capabilities: @@ -180,41 +175,41 @@ called. In order for Docker to use this endpoint, the plugin must specify as much when `/LogDriver.Capabilities` is called. +- Request -**Request**: -```json -{ - "ReadConfig": {}, - "Info": { - "ContainerID": "123456" - } -} -``` + ```json + { + "ReadConfig": {}, + "Info": { + "ContainerID": "123456" + } + } + ``` -`ReadConfig` is the list of options for reading, it is defined with the following -golang struct: + `ReadConfig` is the list of options for reading, it is defined with the following + golang struct: -```go -type ReadConfig struct { - Since time.Time - Tail int - Follow bool -} -``` + ```go + type ReadConfig struct { + Since time.Time + Tail int + Follow bool + } + ``` -- `Since` defines the oldest log that should be sent. -- `Tail` defines the number of lines to read (e.g. like the command `tail -n 10`) -- `Follow` signals that the client wants to stay attached to receive new log messages -as they come in once the existing logs have been read. + - `Since` defines the oldest log that should be sent. + - `Tail` defines the number of lines to read (e.g. like the command `tail -n 10`) + - `Follow` signals that the client wants to stay attached to receive new log messages + as they come in once the existing logs have been read. -`Info` is the same type defined in `/LogDriver.StartLogging`. It should be used -to determine what set of logs to read. + `Info` is the same type defined in `/LogDriver.StartLogging`. It should be used + to determine what set of logs to read. -**Response**: +- Response -``` -{{ log stream }} -``` + ```text + {{ log stream }} + ``` -The response should be the encoded log message using the same format as the -messages that the plugin consumed from Docker. + The response should be the encoded log message using the same format as the + messages that the plugin consumed from Docker. diff --git a/docs/extend/plugins_metrics.md b/docs/extend/plugins_metrics.md index c698a5a13774..f1ea158475ba 100644 --- a/docs/extend/plugins_metrics.md +++ b/docs/extend/plugins_metrics.md @@ -1,20 +1,10 @@ --- +title: Docker metrics collector plugins description: "Metrics plugins." keywords: "Examples, Usage, plugins, docker, documentation, user guide, metrics" --- - - -# Docker metrics collector plugins - -Docker exposes internal metrics based on the prometheus format. Metrics plugins +Docker exposes internal metrics based on the Prometheus format. Metrics plugins enable accessing these metrics in a consistent way by providing a Unix socket at a predefined path where the plugin can scrape the metrics. @@ -44,43 +34,47 @@ plugin's rootfs. Signals to the plugin that the metrics socket is now available for scraping -**Request** -```json -{} -``` +- Request + + ```json + {} + ``` -The request has no playload. + The request has no payload. -**Response** -```json -{ - "Err": "" -} -``` +- Response -If an error occurred during this request, add an error message to the `Err` field -in the response. If no error then you can either send an empty response (`{}`) -or an empty value for the `Err` field. Errors will only be logged. + ```json + { + "Err": "" + } + ``` + + If an error occurred during this request, add an error message to the `Err` field + in the response. If no error then you can either send an empty response (`{}`) + or an empty value for the `Err` field. Errors will only be logged. ### `MetricsCollector.StopMetrics` Signals to the plugin that the metrics socket is no longer available. This may happen when the daemon is shutting down. -**Request** -```json -{} -``` +- Request + + ```json + {} + ``` + + The request has no payload. -The request has no playload. +- Response -**Response** -```json -{ - "Err": "" -} -``` + ```json + { + "Err": "" + } + ``` -If an error occurred during this request, add an error message to the `Err` field -in the response. If no error then you can either send an empty response (`{}`) -or an empty value for the `Err` field. Errors will only be logged. + If an error occurred during this request, add an error message to the `Err` field + in the response. If no error then you can either send an empty response (`{}`) + or an empty value for the `Err` field. Errors will only be logged. diff --git a/docs/extend/plugins_network.md b/docs/extend/plugins_network.md index 46075e573442..eaa9d5f08aba 100644 --- a/docs/extend/plugins_network.md +++ b/docs/extend/plugins_network.md @@ -1,19 +1,9 @@ --- +title: Docker network driver plugins description: "Network driver plugins." keywords: "Examples, Usage, plugins, docker, documentation, user guide" --- - - -# Docker network driver plugins - This document describes Docker Engine network driver plugins generally available in Docker Engine. To view information on plugins managed by Docker Engine, refer to [Docker Engine plugin system](index.md). @@ -26,11 +16,11 @@ LibNetwork, which shares plugin infrastructure with Engine. Effectively, network driver plugins are activated in the same way as other plugins, and use the same kind of protocol. -## Network plugins and swarm mode +## Network plugins and Swarm mode -[Legacy plugins](legacy_plugins.md) do not work in swarm mode. However, -plugins written using the [v2 plugin system](index.md) do work in swarm mode, as -long as they are installed on each swarm worker node. +[Legacy plugins](legacy_plugins.md) do not work in Swarm mode. However, +plugins written using the [v2 plugin system](index.md) do work in Swarm mode, as +long as they are installed on each Swarm worker node. ## Use network driver plugins diff --git a/docs/extend/plugins_volume.md b/docs/extend/plugins_volume.md index 23e7cddf9e94..f77b26f092e2 100644 --- a/docs/extend/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -1,19 +1,9 @@ --- +title: Docker volume plugins description: "How to manage data with external volume plugins" keywords: "Examples, Usage, volume, docker, data, volumes, plugin, api" --- - - -# Docker volume plugins - Docker Engine volume plugins enable Engine deployments to be integrated with external storage systems such as Amazon EBS, and enable data volumes to persist beyond the lifetime of a single Docker host. See the @@ -50,7 +40,7 @@ beyond the lifetime of a single Docker host. See the ## Command-line changes To give a container access to a volume, use the `--volume` and `--volume-driver` -flags on the `docker container run` command. The `--volume` (or `-v`) flag +flags on the `docker container run` command. The `--volume` (or `-v`) flag accepts a volume name and path on the host, and the `--volume-driver` flag accepts a driver type. @@ -98,264 +88,272 @@ the volumes available by bind-mounting the provided paths into the containers. ### `/VolumeDriver.Create` -**Request**: -```json -{ - "Name": "volume_name", - "Opts": {} -} -``` - -Instruct the plugin that the user wants to create a volume, given a user -specified volume name. The plugin does not need to actually manifest the -volume on the filesystem yet (until `Mount` is called). -`Opts` is a map of driver specific options passed through from the user request. - -**Response**: -```json -{ - "Err": "" -} -``` - -Respond with a string error if an error occurred. - -### `/VolumeDriver.Remove` - -**Request**: -```json -{ - "Name": "volume_name" -} -``` - -Delete the specified volume from disk. This request is issued when a user -invokes `docker rm -v` to remove volumes associated with a container. - -**Response**: -```json -{ - "Err": "" -} -``` - -Respond with a string error if an error occurred. - -### `/VolumeDriver.Mount` - -**Request**: -```json -{ - "Name": "volume_name", - "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" -} -``` - -Docker requires the plugin to provide a volume, given a user specified volume -name. `Mount` is called once per container start. If the same `volume_name` is requested -more than once, the plugin may need to keep track of each new mount request and provision -at the first mount request and deprovision at the last corresponding unmount request. - -`ID` is a unique ID for the caller that is requesting the mount. - -**Response**: - -- **v1**: +- Request ```json { - "Mountpoint": "/path/to/directory/on/host", - "Err": "" + "Name": "volume_name", + "Opts": {} } ``` -- **v2**: + Instruct the plugin that the user wants to create a volume, given a user + specified volume name. The plugin does not need to actually manifest the + volume on the filesystem yet (until `Mount` is called). + `Opts` is a map of driver specific options passed through from the user request. + +- Response ```json { - "Mountpoint": "/path/under/PropagatedMount", "Err": "" } ``` -`Mountpoint` is the path on the host (v1) or in the plugin (v2) where the volume -has been made available. - -`Err` is either empty or contains an error string. - -### `/VolumeDriver.Path` + Respond with a string error if an error occurred. -**Request**: +### `/VolumeDriver.Remove` -```json -{ - "Name": "volume_name" -} -``` +- Request -Request the path to the volume with the given `volume_name`. + ```json + { + "Name": "volume_name" + } + ``` -**Response**: + Delete the specified volume from disk. This request is issued when a user + invokes `docker rm -v` to remove volumes associated with a container. -- **v1**: +- Response ```json { - "Mountpoint": "/path/to/directory/on/host", "Err": "" } ``` -- **v2**: + Respond with a string error if an error occurred. + +### `/VolumeDriver.Mount` + +- Request ```json { - "Mountpoint": "/path/under/PropagatedMount", - "Err": "" + "Name": "volume_name", + "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" } ``` -Respond with the path on the host (v1) or inside the plugin (v2) where the -volume has been made available, and/or a string error if an error occurred. - -`Mountpoint` is optional. However, the plugin may be queried again later if one -is not provided. + Docker requires the plugin to provide a volume, given a user specified volume + name. `Mount` is called once per container start. If the same `volume_name` is requested + more than once, the plugin may need to keep track of each new mount request and provision + at the first mount request and deprovision at the last corresponding unmount request. + + `ID` is a unique ID for the caller that is requesting the mount. + +- Response + + - v1 + + ```json + { + "Mountpoint": "/path/to/directory/on/host", + "Err": "" + } + ``` + + - v2 + + ```json + { + "Mountpoint": "/path/under/PropagatedMount", + "Err": "" + } + ``` + + `Mountpoint` is the path on the host (v1) or in the plugin (v2) where the volume + has been made available. + + `Err` is either empty or contains an error string. -### `/VolumeDriver.Unmount` +### `/VolumeDriver.Path` -**Request**: -```json -{ - "Name": "volume_name", - "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" -} -``` +- Request -Docker is no longer using the named volume. `Unmount` is called once per -container stop. Plugin may deduce that it is safe to deprovision the volume at -this point. + ```json + { + "Name": "volume_name" + } + ``` -`ID` is a unique ID for the caller that is requesting the mount. + Request the path to the volume with the given `volume_name`. -**Response**: -```json -{ - "Err": "" -} -``` +- Response -Respond with a string error if an error occurred. + - v1 + ```json + { + "Mountpoint": "/path/to/directory/on/host", + "Err": "" + } + ``` -### `/VolumeDriver.Get` + - v2 -**Request**: -```json -{ - "Name": "volume_name" -} -``` + ```json + { + "Mountpoint": "/path/under/PropagatedMount", + "Err": "" + } + ``` -Get info about `volume_name`. + Respond with the path on the host (v1) or inside the plugin (v2) where the + volume has been made available, and/or a string error if an error occurred. + `Mountpoint` is optional. However, the plugin may be queried again later if one + is not provided. -**Response**: +### `/VolumeDriver.Unmount` -- **v1**: +- Request ```json { - "Volume": { "Name": "volume_name", - "Mountpoint": "/path/to/directory/on/host", - "Status": {} - }, - "Err": "" + "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" } ``` -- **v2**: + Docker is no longer using the named volume. `Unmount` is called once per + container stop. Plugin may deduce that it is safe to deprovision the volume at + this point. + + `ID` is a unique ID for the caller that is requesting the mount. + +- Response ```json { - "Volume": { - "Name": "volume_name", - "Mountpoint": "/path/under/PropagatedMount", - "Status": {} - }, - "Err": "" + "Err": "" } ``` -Respond with a string error if an error occurred. `Mountpoint` and `Status` are -optional. + Respond with a string error if an error occurred. +### `/VolumeDriver.Get` -### /VolumeDriver.List +- Request -**Request**: -```json -{} -``` + ```json + { + "Name": "volume_name" + } + ``` -Get the list of volumes registered with the plugin. + Get info about `volume_name`. -**Response**: +- Response -- **v1**: + - v1 - ```json - { - "Volumes": [ - { + ```json + { + "Volume": { "Name": "volume_name", - "Mountpoint": "/path/to/directory/on/host" - } - ], - "Err": "" - } - ``` + "Mountpoint": "/path/to/directory/on/host", + "Status": {} + }, + "Err": "" + } + ``` -- **v2**: + - v2 - ```json - { - "Volumes": [ - { + ```json + { + "Volume": { "Name": "volume_name", - "Mountpoint": "/path/under/PropagatedMount" - } - ], - "Err": "" - } + "Mountpoint": "/path/under/PropagatedMount", + "Status": {} + }, + "Err": "" + } + ``` + + Respond with a string error if an error occurred. `Mountpoint` and `Status` are + optional. + + +### /VolumeDriver.List + +- Request + + ```json + {} ``` + Get the list of volumes registered with the plugin. -Respond with a string error if an error occurred. `Mountpoint` is optional. +- Response + + - v1 + + ```json + { + "Volumes": [ + { + "Name": "volume_name", + "Mountpoint": "/path/to/directory/on/host" + } + ], + "Err": "" + } + ``` + + - v2 + + ```json + { + "Volumes": [ + { + "Name": "volume_name", + "Mountpoint": "/path/under/PropagatedMount" + } + ], + "Err": "" + } + ``` + + Respond with a string error if an error occurred. `Mountpoint` is optional. ### /VolumeDriver.Capabilities -**Request**: -```json -{} -``` +- Request + + ```json + {} + ``` -Get the list of capabilities the driver supports. + Get the list of capabilities the driver supports. -The driver is not required to implement `Capabilities`. If it is not -implemented, the default values are used. + The driver is not required to implement `Capabilities`. If it is not + implemented, the default values are used. -**Response**: -```json -{ - "Capabilities": { - "Scope": "global" +- Response + + ```json + { + "Capabilities": { + "Scope": "global" + } } -} -``` + ``` -Supported scopes are `global` and `local`. Any other value in `Scope` will be -ignored, and `local` is used. `Scope` allows cluster managers to handle the -volume in different ways. For instance, a scope of `global`, signals to the -cluster manager that it only needs to create the volume once instead of on each -Docker host. More capabilities may be added in the future. + Supported scopes are `global` and `local`. Any other value in `Scope` will be + ignored, and `local` is used. `Scope` allows cluster managers to handle the + volume in different ways. For instance, a scope of `global`, signals to the + cluster manager that it only needs to create the volume once instead of on each + Docker host. More capabilities may be added in the future.