mirror of https://github.com/docker/cli.git
Merge pull request #4767 from dvdksn/refresh-plugin-docs
docs(plugins): fix typos and formatting
This commit is contained in:
commit
d161a2a470
|
@ -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
|
||||
---
|
||||
|
||||
<!-- 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.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
Access to host PID namespace.
|
||||
|
||||
- **`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 showing the 'tiborvass/sample-volume-plugin' plugin config.*
|
||||
The following example shows the 'tiborvass/sample-volume-plugin' plugin config.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
|
@ -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"
|
||||
---
|
||||
|
||||
<!-- 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)
|
||||
- [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
|
||||
|
||||
<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
|
||||
$ 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
|
||||
|
|
|
@ -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"
|
||||
---
|
||||
|
||||
<!-- 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
|
||||
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).
|
||||
|
|
|
@ -1,19 +1,9 @@
|
|||
---
|
||||
title: Docker Plugin API
|
||||
description: "How to write Docker plugins extensions "
|
||||
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 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 daemon 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 host as the Docker daemon.
|
||||
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.
|
||||
|
@ -164,9 +154,9 @@ Plugins are activated via the following "handshake" API call.
|
|||
|
||||
### /Plugin.Activate
|
||||
|
||||
**Request:** empty body
|
||||
Request: empty body
|
||||
|
||||
**Response:**
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -183,7 +173,6 @@ Possible values are:
|
|||
* [`NetworkDriver`](plugins_network.md)
|
||||
* [`VolumeDriver`](plugins_volume.md)
|
||||
|
||||
|
||||
## Plugin retries
|
||||
|
||||
Attempts to call a method on a plugin are retried with an exponential backoff
|
||||
|
|
|
@ -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/"
|
||||
---
|
||||
|
||||
<!-- 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.
|
||||
-->
|
||||
|
||||
# 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,7 +148,7 @@ should implement the following two methods:
|
|||
|
||||
#### /AuthZPlugin.AuthZReq
|
||||
|
||||
**Request**:
|
||||
Request
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -171,7 +161,7 @@ should implement the following two methods:
|
|||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
Response
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -183,7 +173,7 @@ should implement the following two methods:
|
|||
|
||||
#### /AuthZPlugin.AuthZRes
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -199,7 +189,7 @@ should implement the following two methods:
|
|||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```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 body | []byte | Raw request body
|
||||
|
||||
|
||||
#### Plugin -> Daemon
|
||||
|
||||
Name | Type | Description
|
||||
|
@ -239,7 +228,6 @@ The plugin must support two authorization messages formats, one from the daemon
|
|||
|
||||
#### Daemon -> Plugin
|
||||
|
||||
|
||||
Name | Type | Description
|
||||
----------------------- |------------------ |----------------------------------------------------
|
||||
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 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
|
||||
|
||||
|
|
|
@ -1,19 +1,9 @@
|
|||
---
|
||||
title: Docker log driver plugins
|
||||
description: "Log driver plugins."
|
||||
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.
|
||||
|
||||
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
|
||||
is a FIFO. Logging plugins are not currently supported on Windows.
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"File": "/path/to/file/stream",
|
||||
"Info": {
|
||||
"ContainerID": "123456"
|
||||
}
|
||||
"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.
|
||||
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:
|
||||
|
@ -81,14 +72,14 @@ type Info struct {
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
`ContainerID` will always be supplied with this struct, but other fields may be
|
||||
empty or missing.
|
||||
|
||||
**Response**
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"Err": ""
|
||||
"Err": ""
|
||||
}
|
||||
```
|
||||
|
||||
|
@ -102,12 +93,12 @@ 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).
|
||||
[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]
|
||||
```
|
||||
|
||||
|
@ -127,17 +118,19 @@ losing log data.
|
|||
Requests on this endpoint does not mean that the container has been removed
|
||||
only that it has stopped.
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"File": "/path/to/file/stream"
|
||||
"File": "/path/to/file/stream"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```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
|
||||
Docker to be able to take advantage of any of the defined capabilities.
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```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
|
||||
`/LogDriver.Capabilities` is called.
|
||||
|
||||
Request:
|
||||
|
||||
**Request**:
|
||||
```json
|
||||
{
|
||||
"ReadConfig": {},
|
||||
"Info": {
|
||||
"ContainerID": "123456"
|
||||
}
|
||||
"ReadConfig": {},
|
||||
"Info": {
|
||||
"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
|
||||
to determine what set of logs to read.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```
|
||||
```text
|
||||
{{ log stream }}
|
||||
```
|
||||
|
||||
|
|
|
@ -1,20 +1,10 @@
|
|||
---
|
||||
title: Docker metrics collector plugins
|
||||
description: "Metrics plugins."
|
||||
keywords: "Examples, Usage, plugins, docker, documentation, user guide, metrics"
|
||||
---
|
||||
|
||||
<!-- 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 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,17 +34,19 @@ plugin's rootfs.
|
|||
|
||||
Signals to the plugin that the metrics socket is now available for scraping
|
||||
|
||||
**Request**
|
||||
Request:
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
The request has no playload.
|
||||
The request has no payload.
|
||||
|
||||
Response:
|
||||
|
||||
**Response**
|
||||
```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.
|
||||
This may happen when the daemon is shutting down.
|
||||
|
||||
**Request**
|
||||
Request:
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
The request has no playload.
|
||||
The request has no payload.
|
||||
|
||||
Response:
|
||||
|
||||
**Response**
|
||||
```json
|
||||
{
|
||||
"Err": ""
|
||||
"Err": ""
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
@ -1,19 +1,9 @@
|
|||
---
|
||||
title: Docker network driver plugins
|
||||
description: "Network driver plugins."
|
||||
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
|
||||
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
|
||||
|
||||
|
@ -55,7 +45,6 @@ referring to that network will be sent to the plugin,
|
|||
$ docker run --network=mynet busybox top
|
||||
```
|
||||
|
||||
|
||||
## Find network plugins
|
||||
|
||||
Network plugins are written by third parties, and are published by those
|
||||
|
|
|
@ -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"
|
||||
---
|
||||
|
||||
<!-- 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
|
||||
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,7 +88,8 @@ the volumes available by bind-mounting the provided paths into the containers.
|
|||
|
||||
### `/VolumeDriver.Create`
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"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).
|
||||
`Opts` is a map of driver specific options passed through from the user request.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"Err": ""
|
||||
}
|
||||
```
|
||||
|
||||
Respond with a string error if an error occurred.
|
||||
Respond with a string error if an error occurred.
|
||||
|
||||
### `/VolumeDriver.Remove`
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
invokes `docker rm -v` to remove volumes associated with a container.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"Err": ""
|
||||
|
@ -143,7 +137,8 @@ Respond with a string error if an error occurred.
|
|||
|
||||
### `/VolumeDriver.Mount`
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
- **v1**:
|
||||
- v1
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -169,7 +164,7 @@ at the first mount request and deprovision at the last corresponding unmount req
|
|||
}
|
||||
```
|
||||
|
||||
- **v2**:
|
||||
- v2
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -185,7 +180,7 @@ has been made available.
|
|||
|
||||
### `/VolumeDriver.Path`
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -195,9 +190,9 @@ has been made available.
|
|||
|
||||
Request the path to the volume with the given `volume_name`.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
- **v1**:
|
||||
- v1
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -206,7 +201,7 @@ Request the path to the volume with the given `volume_name`.
|
|||
}
|
||||
```
|
||||
|
||||
- **v2**:
|
||||
- v2
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -223,7 +218,8 @@ is not provided.
|
|||
|
||||
### `/VolumeDriver.Unmount`
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "volume_name",
|
||||
|
@ -237,7 +233,8 @@ this point.
|
|||
|
||||
`ID` is a unique ID for the caller that is requesting the mount.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"Err": ""
|
||||
|
@ -246,10 +243,10 @@ this point.
|
|||
|
||||
Respond with a string error if an error occurred.
|
||||
|
||||
|
||||
### `/VolumeDriver.Get`
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"Name": "volume_name"
|
||||
|
@ -258,10 +255,9 @@ Respond with a string error if an error occurred.
|
|||
|
||||
Get info about `volume_name`.
|
||||
|
||||
Response:
|
||||
|
||||
**Response**:
|
||||
|
||||
- **v1**:
|
||||
- v1
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -274,7 +270,7 @@ Get info about `volume_name`.
|
|||
}
|
||||
```
|
||||
|
||||
- **v2**:
|
||||
- v2
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -293,16 +289,17 @@ optional.
|
|||
|
||||
### /VolumeDriver.List
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
Get the list of volumes registered with the plugin.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
- **v1**:
|
||||
- v1
|
||||
|
||||
```json
|
||||
{
|
||||
|
@ -316,7 +313,7 @@ Get the list of volumes registered with the plugin.
|
|||
}
|
||||
```
|
||||
|
||||
- **v2**:
|
||||
- v2
|
||||
|
||||
```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.
|
||||
|
||||
### /VolumeDriver.Capabilities
|
||||
|
||||
**Request**:
|
||||
Request:
|
||||
|
||||
```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
|
||||
implemented, the default values are used.
|
||||
|
||||
**Response**:
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"Capabilities": {
|
||||
|
|
Loading…
Reference in New Issue