Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4767 from dvdksn/refresh-plugin-docs 

docs(plugins): fix typos and formatting
This commit is contained in:
Sebastiaan van Stijn 2024-01-17 14:28:58 +01:00 committed by GitHub
parent 33b00e5185 3df149545e
commit d161a2a470
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 266 additions and 340 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
docs/extend/config.md
View File

@ -1,192 +1,185 @@
--- ---
description: "How to develop and use a plugin with the managed plugin system" description: "How to develop and use a plugin with the managed plugin system"
keywords: "API, Usage, plugins, documentation, developer" keywords: "API, Usage, plugins, documentation, developer"
title: Plugin Config Version 1 of Plugin V2
--- ---
<!-- This file is maintained within the docker/cli GitHub
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Plugin Config Version 1 of Plugin V2
This document outlines the format of the V0 plugin configuration. This document outlines the format of the V0 plugin configuration.
Plugin configs describe the various constituents of a docker plugin. Plugin Plugin configs describe the various constituents of a Docker engine plugin.
configs can be serialized to JSON format with the following media types: Plugin configs can be serialized to JSON format with the following media types:
| Config Type | Media Type | | 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 Config provides the base accessible fields for working with V0 plugin format in
in the registry. 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. 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`. 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** - `mounts` PluginMount array
- **host**
- **none**
- **`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. Access to host ipc namespace.
- **`pidhost`** *boolean*
Access to host pid namespace.
- **`propagatedMount`** *string* - `pidhost` Boolean
path to be mounted as rshared, so that mounts under that path are visible to docker. This is useful for volume plugins. Access to host PID namespace.
This path will be bind-mounted outside of the plugin rootfs so it's contents
are preserved on upgrade.
- **`env`** *PluginEnv array* - `propagatedMount` string
env of the plugin, struct consisting of the following fields 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.
- **`name`** *string* - `env` PluginEnv array
name of the env. Environment variables of the plugin, struct consisting of the following fields:
- **`description`** *string* - `name` string
description of the env. Name of the environment variable.
- **`value`** *string* - `description` string
value of the env. Description of the environment variable.
- **`args`** *PluginArgs* - `value` string
args of the plugin, struct consisting of the following fields Value of the environment variable.
- **`name`** *string* - `args` PluginArgs
name of the args. Arguments of the plugin, struct consisting of the following fields:
- **`description`** *string* - `name` string
description of the args. Name of the arguments.
- **`value`** *string array* - `description` string
values of the args. Description of the arguments.
- **`linux`** *PluginLinux* - `value` string array
- **`capabilities`** *string array* Values of the arguments.
capabilities of the plugin (*Linux only*), see list [`here`](https://github.com/opencontainers/runc/blob/master/libcontainer/SPEC.md#security) - `linux` PluginLinux
- **`allowAllDevices`** *boolean* - `capabilities` string array
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. Capabilities of the plugin (Linux only), see list [`here`](https://github.com/opencontainers/runc/blob/master/libcontainer/SPEC.md#security)
- **`devices`** *PluginDevice array* - `allowAllDevices` Boolean
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) 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.
- **`name`** *string* - `devices` PluginDevice array
name of the device. 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).
- **`description`** *string* - `name` string
description of the device. Name of the device.
- **`path`** *string* - `description` string
path of the device. Description of the device.
- `path` string
Path of the device.
## Example Config ## Example Config
*Example showing the 'tiborvass/sample-volume-plugin' plugin config.* The following example shows the 'tiborvass/sample-volume-plugin' plugin config.
```json ```json
{ {

127
docs/extend/index.md
View File

@ -1,24 +1,14 @@
--- ---
title: Docker Engine managed plugin system
description: Develop and use a plugin with the managed plugin system description: Develop and use a plugin with the managed plugin system
keywords: "API, Usage, plugins, documentation, developer" keywords: "API, Usage, plugins, documentation, developer"
--- ---
<!-- This file is maintained within the docker/cli GitHub
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Docker Engine managed plugin system
- [Installing and using a plugin](index.md#installing-and-using-a-plugin) - [Installing and using a plugin](index.md#installing-and-using-a-plugin)
- [Developing a plugin](index.md#developing-a-plugin) - [Developing a plugin](index.md#developing-a-plugin)
- [Debugging plugins](index.md#debugging-plugins) - [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. plugins using Docker Engine.
For information about legacy (non-managed) plugins, refer to For information about legacy (non-managed) plugins, refer to
@ -49,78 +39,78 @@ enabled, and use it to create a volume.
> **Note** > **Note**
> >
> This example is intended for instructional purposes only. Once the volume is > 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 > created, your SSH password to the remote host is exposed as plaintext when
> when inspecting the volume. You should delete the volume as soon as you are > inspecting the volume. Delete the volume as soon as you are done with the
> done with the example. > example.
1. Install the `sshfs` plugin. 1. Install the `sshfs` plugin.
```console ```console
$ docker plugin install vieux/sshfs $ docker plugin install vieux/sshfs
Plugin "vieux/sshfs" is requesting the following privileges: Plugin "vieux/sshfs" is requesting the following privileges:
- network: [host] - network: [host]
- capabilities: [CAP_SYS_ADMIN] - capabilities: [CAP_SYS_ADMIN]
Do you grant the above permissions? [y/N] y 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 access to the `host` network.
- It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run - It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run
the `mount` command. 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 ```console
$ docker plugin ls $ docker plugin ls
ID NAME TAG DESCRIPTION ENABLED ID NAME TAG DESCRIPTION ENABLED
69553ca1d789 vieux/sshfs latest the `sshfs` plugin true 69553ca1d789 vieux/sshfs latest the `sshfs` plugin true
``` ```
3. Create a volume using the plugin. 3. Create a volume using the plugin.
This example mounts the `/remote` directory on host `1.2.3.4` into a This example mounts the `/remote` directory on host `1.2.3.4` into a
volume named `sshvolume`. volume named `sshvolume`.
This volume can now be mounted into containers. This volume can now be mounted into containers.
```console ```console
$ docker volume create \ $ docker volume create \
-d vieux/sshfs \ -d vieux/sshfs \
--name sshvolume \ --name sshvolume \
-o sshcmd=user@1.2.3.4:/remote \ -o sshcmd=user@1.2.3.4:/remote \
-o password=$(cat file_containing_password_for_remote_host) -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 ```console
$ docker volume ls $ docker volume ls
DRIVER NAME DRIVER NAME
vieux/sshfs sshvolume vieux/sshfs sshvolume
``` ```
5. Start a container that uses the volume `sshvolume`. 5. Start a container that uses the volume `sshvolume`.
```console ```console
$ docker run --rm -v sshvolume:/data busybox ls /data $ docker run --rm -v sshvolume:/data busybox ls /data
<content of /remote on machine 1.2.3.4> <content of /remote on machine 1.2.3.4>
``` ```
6. Remove the volume `sshvolume` 6. Remove the volume `sshvolume`
```console ```console
$ docker volume rm sshvolume $ docker volume rm sshvolume
sshvolume sshvolume
``` ```
To disable a plugin, use the `docker plugin disable` command. To completely To disable a plugin, use the `docker plugin disable` command. To completely
remove it, use the `docker plugin remove` command. For other available 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 The `rootfs` directory represents the root filesystem of the plugin. In this
example, it was created from a Dockerfile: example, it was created from a Dockerfile:
> **Note:** The `/run/docker/plugins` directory is mandatory inside of the > **Note**
> plugin's filesystem for docker to communicate with the plugin. >
> The `/run/docker/plugins` directory is mandatory inside of the
> plugin's filesystem for Docker to communicate with the plugin.
```console ```console
$ git clone https://github.com/vieux/docker-volume-sshfs $ 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 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 Use `runc`, the default docker container runtime, for debugging plugins by
plugins. This is specifically useful to collect plugin logs if they are collecting plugin logs redirected to a file.
redirected to a file.
```console ```console
$ sudo runc --root /run/docker/runtime-runc/plugins.moby list $ sudo runc --root /run/docker/runtime-runc/plugins.moby list

16
docs/extend/legacy_plugins.md
View File

@ -1,21 +1,11 @@
--- ---
title: Use Docker Engine plugins
aliases: aliases:
- "/engine/extend/plugins/" - "/engine/extend/plugins/"
description: "How to add additional functionality to Docker with plugins extensions" description: "How to add additional functionality to Docker with plugins extensions"
keywords: "Examples, Usage, plugins, docker, documentation, user guide" keywords: "Examples, Usage, plugins, docker, documentation, user guide"
--- ---
<!-- This file is maintained within the docker/cli GitHub
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Use Docker Engine plugins
This document describes the Docker Engine plugins generally available in Docker This document describes the Docker Engine plugins generally available in Docker
Engine. To view information on plugins managed by Docker, Engine. To view information on plugins managed by Docker,
refer to [Docker Engine plugin system](index.md). refer to [Docker Engine plugin system](index.md).
@ -40,7 +30,7 @@ Follow the instructions in the plugin's documentation.
## Finding a plugin ## 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 ### Network plugins
@ -97,4 +87,4 @@ of the plugin for help. The Docker team may not be able to assist you.
## Writing a plugin ## Writing a plugin
If you are interested in writing a plugin for Docker, or seeing how they work 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).

41
docs/extend/plugin_api.md
View File

@ -1,19 +1,9 @@
--- ---
title: Docker Plugin API
description: "How to write Docker plugins extensions " description: "How to write Docker plugins extensions "
keywords: "API, Usage, plugins, documentation, developer" keywords: "API, Usage, plugins, documentation, developer"
--- ---
<!-- This file is maintained within the docker/cli GitHub
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Docker Plugin API
Docker plugins are out-of-process extensions which add capabilities to the Docker plugins are out-of-process extensions which add capabilities to the
Docker Engine. Docker Engine.
@ -26,8 +16,8 @@ If you just want to learn about or use Docker plugins, look
## What plugins are ## What plugins are
A plugin is a process running on the same or a different host as the docker daemon, 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 which registers itself by placing a file on the daemon host in one of the plugin
directories described in [Plugin discovery](#plugin-discovery). directories described in [Plugin discovery](#plugin-discovery).
Plugins have human-readable names, which are short, lowercase strings. For 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. 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`. * `.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. * `.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 Unix domain socket files must run on the same host as the Docker daemon.
plugins with spec or json files can run on a different host if a remote URL is specified. 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`. 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. 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`. `/run/docker/plugins/flocker.sock`.
You can define each plugin into a separated subdirectory if you want to isolate definitions from each other. 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 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. 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 `/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. 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 ## 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 example, when packaging a plugin for a platform which supports `systemd`, you
might use [`systemd` dependencies]( might use [`systemd` dependencies](
https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to 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 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. 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. they are activated only lazily, or on-demand, when they are needed.
## Systemd socket activation ## 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. 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 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 implement an HTTP server and bind this to the Unix socket mentioned in the
"plugin discovery" section. "plugin discovery" section.
All requests are HTTP `POST` requests. All requests are HTTP `POST` requests.
@ -164,9 +154,9 @@ Plugins are activated via the following "handshake" API call.
### /Plugin.Activate ### /Plugin.Activate
**Request:** empty body Request: empty body
**Response:** Response:
```json ```json
{ {
@ -183,7 +173,6 @@ Possible values are:
* [`NetworkDriver`](plugins_network.md) * [`NetworkDriver`](plugins_network.md)
* [`VolumeDriver`](plugins_volume.md) * [`VolumeDriver`](plugins_volume.md)
## Plugin retries ## Plugin retries
Attempts to call a method on a plugin are retried with an exponential backoff Attempts to call a method on a plugin are retried with an exponential backoff

31
docs/extend/plugins_authorization.md
View File

@ -1,22 +1,12 @@
--- ---
title: Access authorization plugin
description: "How to create authorization plugins to manage access control to your Docker daemon." description: "How to create authorization plugins to manage access control to your Docker daemon."
keywords: "security, authorization, authentication, docker, documentation, plugin, extend" keywords: "security, authorization, authentication, docker, documentation, plugin, extend"
aliases: aliases:
- "/engine/extend/authorization/" - "/engine/extend/authorization/"
--- ---
<!-- This file is maintained within the docker/cli GitHub This document describes the Docker Engine plugins available in Docker
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Access authorization plugin
This document describes the Docker Engine plugins generally available in Docker
Engine. To view information on plugins managed by Docker Engine, Engine. To view information on plugins managed by Docker Engine,
refer to [Docker Engine plugin system](index.md). 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. was built using this mechanism.
Using this subsystem, you don't need to rebuild the Docker daemon to add an 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. need to restart the Docker daemon to add a new plugin.
An authorization plugin approves or denies requests to the Docker daemon based An authorization plugin approves or denies requests to the Docker daemon based
@ -158,7 +148,7 @@ should implement the following two methods:
#### /AuthZPlugin.AuthZReq #### /AuthZPlugin.AuthZReq
**Request**: Request
```json ```json
{ {
@ -171,7 +161,7 @@ should implement the following two methods:
} }
``` ```
**Response**: Response
```json ```json
{ {
@ -183,7 +173,7 @@ should implement the following two methods:
#### /AuthZPlugin.AuthZRes #### /AuthZPlugin.AuthZRes
**Request**: Request:
```json ```json
{ {
@ -199,7 +189,7 @@ should implement the following two methods:
} }
``` ```
**Response**: Response:
```json ```json
{ {
@ -224,7 +214,6 @@ Request URI | string | The HTTP request URI including API
Request headers | map[string]string | Request headers as key value pairs (without the authorization header) Request headers | map[string]string | Request headers as key value pairs (without the authorization header)
Request body | []byte | Raw request body Request body | []byte | Raw request body
#### Plugin -> Daemon #### Plugin -> Daemon
Name | Type | Description Name | Type | Description
@ -239,7 +228,6 @@ The plugin must support two authorization messages formats, one from the daemon
#### Daemon -> Plugin #### Daemon -> Plugin
Name | Type | Description Name | Type | Description
----------------------- |------------------ |---------------------------------------------------- ----------------------- |------------------ |----------------------------------------------------
User | string | The user identification User | string | The user identification
@ -248,10 +236,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 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 headers | map[string]string | Request headers as key value pairs (without the authorization header)
Request body | []byte | Raw request body 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 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 #### Plugin -> Daemon

67
docs/extend/plugins_logging.md
View File

@ -1,19 +1,9 @@
--- ---
title: Docker log driver plugins
description: "Log driver plugins." description: "Log driver plugins."
keywords: "Examples, Usage, plugins, docker, documentation, user guide, logging" keywords: "Examples, Usage, plugins, docker, documentation, user guide, logging"
--- ---
<!-- This file is maintained within the docker/cli GitHub
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Docker log driver plugins
This document describes logging driver plugins for Docker. This document describes logging driver plugins for Docker.
Logging drivers enables users to forward container logs to another service for Logging drivers enables users to forward container logs to another service for
@ -46,20 +36,21 @@ receiving logs for.
Logs will be streamed over the defined file in the request. On Linux this file 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. is a FIFO. Logging plugins are not currently supported on Windows.
**Request**: Request:
```json ```json
{ {
"File": "/path/to/file/stream", "File": "/path/to/file/stream",
"Info": { "Info": {
"ContainerID": "123456" "ContainerID": "123456"
} }
} }
``` ```
`File` is the path to the log stream that needs to be consumed. Each call to `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 `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 that the plugin has already received logs for prior. The file is created by
docker with a randomly generated name. Docker with a randomly generated name.
`Info` is details about the container that's being logged. This is fairly `Info` is details about the container that's being logged. This is fairly
free-form, but is defined by the following struct definition: free-form, but is defined by the following struct definition:
@ -81,14 +72,14 @@ type Info struct {
} }
``` ```
`ContainerID` will always be supplied with this struct, but other fields may be `ContainerID` will always be supplied with this struct, but other fields may be
empty or missing. empty or missing.
**Response** Response:
```json ```json
{ {
"Err": "" "Err": ""
} }
``` ```
@ -102,12 +93,12 @@ write to its stdio streams.
Log stream messages are encoded as protocol buffers. The protobuf definitions are Log stream messages are encoded as protocol buffers. The protobuf definitions are
in the in the
[docker repository](https://github.com/docker/docker/blob/master/api/types/plugins/logdriver/entry.proto). [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 Since protocol buffers are not self-delimited you must decode them from the stream
using the following stream format: using the following stream format:
``` ```text
[size][message] [size][message]
``` ```
@ -127,17 +118,19 @@ losing log data.
Requests on this endpoint does not mean that the container has been removed Requests on this endpoint does not mean that the container has been removed
only that it has stopped. only that it has stopped.
**Request**: Request:
```json ```json
{ {
"File": "/path/to/file/stream" "File": "/path/to/file/stream"
} }
``` ```
**Response**: Response:
```json ```json
{ {
"Err": "" "Err": ""
} }
``` ```
@ -154,15 +147,17 @@ Logging plugins can implement two extra logging endpoints:
Defines the capabilities of the log driver. You must implement this endpoint for 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. Docker to be able to take advantage of any of the defined capabilities.
**Request**: Request:
```json ```json
{} {}
``` ```
**Response**: Response:
```json ```json
{ {
"ReadLogs": true "ReadLogs": true
} }
``` ```
@ -180,14 +175,14 @@ called.
In order for Docker to use this endpoint, the plugin must specify as much when In order for Docker to use this endpoint, the plugin must specify as much when
`/LogDriver.Capabilities` is called. `/LogDriver.Capabilities` is called.
Request:
**Request**:
```json ```json
{ {
"ReadConfig": {}, "ReadConfig": {},
"Info": { "Info": {
"ContainerID": "123456" "ContainerID": "123456"
} }
} }
``` ```
@ -210,9 +205,9 @@ as they come in once the existing logs have been read.
`Info` is the same type defined in `/LogDriver.StartLogging`. It should be used `Info` is the same type defined in `/LogDriver.StartLogging`. It should be used
to determine what set of logs to read. to determine what set of logs to read.
**Response**: Response:
``` ```text
{{ log stream }} {{ log stream }}
``` ```

34
docs/extend/plugins_metrics.md
View File

@ -1,20 +1,10 @@
--- ---
title: Docker metrics collector plugins
description: "Metrics plugins." description: "Metrics plugins."
keywords: "Examples, Usage, plugins, docker, documentation, user guide, metrics" keywords: "Examples, Usage, plugins, docker, documentation, user guide, metrics"
--- ---
<!-- This file is maintained within the docker/cli GitHub Docker exposes internal metrics based on the Prometheus format. Metrics plugins
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Docker metrics collector plugins
Docker exposes internal metrics based on the prometheus format. Metrics plugins
enable accessing these metrics in a consistent way by providing a Unix enable accessing these metrics in a consistent way by providing a Unix
socket at a predefined path where the plugin can scrape the metrics. socket at a predefined path where the plugin can scrape the metrics.
@ -44,17 +34,19 @@ plugin's rootfs.
Signals to the plugin that the metrics socket is now available for scraping Signals to the plugin that the metrics socket is now available for scraping
**Request** Request:
```json ```json
{} {}
``` ```
The request has no playload. The request has no payload.
Response:
**Response**
```json ```json
{ {
"Err": "" "Err": ""
} }
``` ```
@ -67,17 +59,19 @@ or an empty value for the `Err` field. Errors will only be logged.
Signals to the plugin that the metrics socket is no longer available. Signals to the plugin that the metrics socket is no longer available.
This may happen when the daemon is shutting down. This may happen when the daemon is shutting down.
**Request** Request:
```json ```json
{} {}
``` ```
The request has no playload. The request has no payload.
Response:
**Response**
```json ```json
{ {
"Err": "" "Err": ""
} }
``` ```

21
docs/extend/plugins_network.md
View File

@ -1,19 +1,9 @@
--- ---
title: Docker network driver plugins
description: "Network driver plugins." description: "Network driver plugins."
keywords: "Examples, Usage, plugins, docker, documentation, user guide" keywords: "Examples, Usage, plugins, docker, documentation, user guide"
--- ---
<!-- This file is maintained within the docker/cli GitHub
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Docker network driver plugins
This document describes Docker Engine network driver plugins generally This document describes Docker Engine network driver plugins generally
available in Docker Engine. To view information on plugins available in Docker Engine. To view information on plugins
managed by Docker Engine, refer to [Docker Engine plugin system](index.md). 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 driver plugins are activated in the same way as other plugins, and use the same
kind of protocol. 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, [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 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. long as they are installed on each Swarm worker node.
## Use network driver plugins ## Use network driver plugins
@ -55,7 +45,6 @@ referring to that network will be sent to the plugin,
$ docker run --network=mynet busybox top $ docker run --network=mynet busybox top
``` ```
## Find network plugins ## Find network plugins
Network plugins are written by third parties, and are published by those Network plugins are written by third parties, and are published by those

78
docs/extend/plugins_volume.md
View File

@ -1,19 +1,9 @@
--- ---
title: Docker volume plugins
description: "How to manage data with external volume plugins" description: "How to manage data with external volume plugins"
keywords: "Examples, Usage, volume, docker, data, volumes, plugin, api" keywords: "Examples, Usage, volume, docker, data, volumes, plugin, api"
--- ---
<!-- This file is maintained within the docker/cli GitHub
repository at https://github.com/docker/cli/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
# Docker volume plugins
Docker Engine volume plugins enable Engine deployments to be integrated with Docker Engine volume plugins enable Engine deployments to be integrated with
external storage systems such as Amazon EBS, and enable data volumes to persist external storage systems such as Amazon EBS, and enable data volumes to persist
beyond the lifetime of a single Docker host. See the 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 ## Command-line changes
To give a container access to a volume, use the `--volume` and `--volume-driver` 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 volume name and path on the host, and the `--volume-driver` flag
accepts a driver type. accepts a driver type.
@ -98,7 +88,8 @@ the volumes available by bind-mounting the provided paths into the containers.
### `/VolumeDriver.Create` ### `/VolumeDriver.Create`
**Request**: Request:
```json ```json
{ {
"Name": "volume_name", "Name": "volume_name",
@ -111,18 +102,20 @@ specified volume name. The plugin does not need to actually manifest the
volume on the filesystem yet (until `Mount` is called). volume on the filesystem yet (until `Mount` is called).
`Opts` is a map of driver specific options passed through from the user request. `Opts` is a map of driver specific options passed through from the user request.
**Response**: Response:
```json ```json
{ {
"Err": "" "Err": ""
} }
``` ```
Respond with a string error if an error occurred. Respond with a string error if an error occurred.
### `/VolumeDriver.Remove` ### `/VolumeDriver.Remove`
**Request**: Request:
```json ```json
{ {
"Name": "volume_name" "Name": "volume_name"
@ -132,7 +125,8 @@ Respond with a string error if an error occurred.
Delete the specified volume from disk. This request is issued when a user Delete the specified volume from disk. This request is issued when a user
invokes `docker rm -v` to remove volumes associated with a container. invokes `docker rm -v` to remove volumes associated with a container.
**Response**: Response:
```json ```json
{ {
"Err": "" "Err": ""
@ -143,7 +137,8 @@ Respond with a string error if an error occurred.
### `/VolumeDriver.Mount` ### `/VolumeDriver.Mount`
**Request**: Request:
```json ```json
{ {
"Name": "volume_name", "Name": "volume_name",
@ -158,9 +153,9 @@ at the first mount request and deprovision at the last corresponding unmount req
`ID` is a unique ID for the caller that is requesting the mount. `ID` is a unique ID for the caller that is requesting the mount.
**Response**: Response:
- **v1**: - v1
```json ```json
{ {
@ -169,7 +164,7 @@ at the first mount request and deprovision at the last corresponding unmount req
} }
``` ```
- **v2**: - v2
```json ```json
{ {
@ -185,7 +180,7 @@ has been made available.
### `/VolumeDriver.Path` ### `/VolumeDriver.Path`
**Request**: Request:
```json ```json
{ {
@ -195,9 +190,9 @@ has been made available.
Request the path to the volume with the given `volume_name`. Request the path to the volume with the given `volume_name`.
**Response**: Response:
- **v1**: - v1
```json ```json
{ {
@ -206,7 +201,7 @@ Request the path to the volume with the given `volume_name`.
} }
``` ```
- **v2**: - v2
```json ```json
{ {
@ -223,7 +218,8 @@ is not provided.
### `/VolumeDriver.Unmount` ### `/VolumeDriver.Unmount`
**Request**: Request:
```json ```json
{ {
"Name": "volume_name", "Name": "volume_name",
@ -237,7 +233,8 @@ this point.
`ID` is a unique ID for the caller that is requesting the mount. `ID` is a unique ID for the caller that is requesting the mount.
**Response**: Response:
```json ```json
{ {
"Err": "" "Err": ""
@ -246,10 +243,10 @@ this point.
Respond with a string error if an error occurred. Respond with a string error if an error occurred.
### `/VolumeDriver.Get` ### `/VolumeDriver.Get`
**Request**: Request:
```json ```json
{ {
"Name": "volume_name" "Name": "volume_name"
@ -258,10 +255,9 @@ Respond with a string error if an error occurred.
Get info about `volume_name`. Get info about `volume_name`.
Response:
**Response**: - v1
- **v1**:
```json ```json
{ {
@ -274,7 +270,7 @@ Get info about `volume_name`.
} }
``` ```
- **v2**: - v2
```json ```json
{ {
@ -293,16 +289,17 @@ optional.
### /VolumeDriver.List ### /VolumeDriver.List
**Request**: Request:
```json ```json
{} {}
``` ```
Get the list of volumes registered with the plugin. Get the list of volumes registered with the plugin.
**Response**: Response:
- **v1**: - v1
```json ```json
{ {
@ -316,7 +313,7 @@ Get the list of volumes registered with the plugin.
} }
``` ```
- **v2**: - v2
```json ```json
{ {
@ -330,12 +327,12 @@ Get the list of volumes registered with the plugin.
} }
``` ```
Respond with a string error if an error occurred. `Mountpoint` is optional. Respond with a string error if an error occurred. `Mountpoint` is optional.
### /VolumeDriver.Capabilities ### /VolumeDriver.Capabilities
**Request**: Request:
```json ```json
{} {}
``` ```
@ -345,7 +342,8 @@ Get the list of capabilities the driver supports.
The driver is not required to implement `Capabilities`. If it is not The driver is not required to implement `Capabilities`. If it is not
implemented, the default values are used. implemented, the default values are used.
**Response**: Response:
```json ```json
{ {
"Capabilities": { "Capabilities": {