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

docs(plugins): fix typos and formatting 

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2024-01-10 10:38:42 +01:00
parent cfe18f5e03
commit 3df149545e
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"
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
{

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

16
docs/extend/legacy_plugins.md
View File

@ -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).

41
docs/extend/plugin_api.md
View File

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

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

67
docs/extend/plugins_logging.md
View File

@ -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 }}
```

34
docs/extend/plugins_metrics.md
View File

@ -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": ""
}
```

21
docs/extend/plugins_network.md
View File

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

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"
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": {