From 3df149545efa64f07e42c341fcd3fadb0d71aace Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 10 Jan 2024 10:38:42 +0100 Subject: [PATCH] docs(plugins): fix typos and formatting Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/extend/config.md | 191 +++++++++++++-------------- docs/extend/index.md | 127 +++++++++--------- docs/extend/legacy_plugins.md | 16 +-- docs/extend/plugin_api.md | 41 +++--- docs/extend/plugins_authorization.md | 31 ++--- docs/extend/plugins_logging.md | 67 +++++----- docs/extend/plugins_metrics.md | 34 ++--- docs/extend/plugins_network.md | 21 +-- docs/extend/plugins_volume.md | 78 ++++++----- 9 files changed, 266 insertions(+), 340 deletions(-) diff --git a/docs/extend/config.md b/docs/extend/config.md index 6af92c55b4..1f96d3e009 100644 --- a/docs/extend/config.md +++ b/docs/extend/config.md @@ -1,192 +1,185 @@ --- description: "How to develop and use a plugin with the managed plugin system" keywords: "API, Usage, plugins, documentation, developer" +title: Plugin Config Version 1 of Plugin V2 --- - - - -# Plugin Config Version 1 of Plugin V2 - This document outlines the format of the V0 plugin configuration. -Plugin configs describe the various constituents of a docker plugin. Plugin -configs can be serialized to JSON format with the following media types: +Plugin configs describe the various constituents of a Docker engine plugin. +Plugin configs can be serialized to JSON format with the following media types: | Config Type | Media Type | |-------------|-----------------------------------------| -| config | "application/vnd.docker.plugin.v1+json" | +| config | `application/vnd.docker.plugin.v1+json` | -## *Config* Field Descriptions +## Config Field Descriptions -Config provides the base accessible fields for working with V0 plugin format - in the registry. +Config provides the base accessible fields for working with V0 plugin format in +the registry. -- **`description`** *string* +- `description` string - description of the plugin + Description of the plugin -- **`documentation`** *string* +- `documentation` string - link to the documentation about the plugin + Link to the documentation about the plugin -- **`interface`** *PluginInterface* +- `interface` PluginInterface - interface implemented by the plugins, struct consisting of the following fields + Interface implemented by the plugins, struct consisting of the following fields: - - **`types`** *string array* + - `types` string array - types indicate what interface(s) the plugin currently implements. + Types indicate what interface(s) the plugin currently implements. - currently supported: + Supported types: - - **docker.volumedriver/1.0** + - `docker.volumedriver/1.0` - - **docker.networkdriver/1.0** + - `docker.networkdriver/1.0` - - **docker.ipamdriver/1.0** + - `docker.ipamdriver/1.0` - - **docker.authz/1.0** + - `docker.authz/1.0` - - **docker.logdriver/1.0** + - `docker.logdriver/1.0` - - **docker.metricscollector/1.0** + - `docker.metricscollector/1.0` - - **`socket`** *string* + - `socket` string - socket is the name of the socket the engine should use to communicate with the plugins. - the socket will be created in `/run/docker/plugins`. + Socket is the name of the socket the engine should use to communicate with the plugins. + the socket will be created in `/run/docker/plugins`. +- `entrypoint` string array -- **`entrypoint`** *string array* + Entrypoint of the plugin, see [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) - entrypoint of the plugin, see [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) +- `workdir` string -- **`workdir`** *string* + Working directory of the plugin, see [`WORKDIR`](https://docs.docker.com/engine/reference/builder/#workdir) - workdir of the plugin, see [`WORKDIR`](https://docs.docker.com/engine/reference/builder/#workdir) +- `network` PluginNetwork -- **`network`** *PluginNetwork* + Network of the plugin, struct consisting of the following fields: - network of the plugin, struct consisting of the following fields + - `type` string - - **`type`** *string* + Network type. - network type. + Supported types: - currently supported: + - `bridge` + - `host` + - `none` - - **bridge** - - **host** - - **none** +- `mounts` PluginMount array -- **`mounts`** *PluginMount array* + Mount of the plugin, struct consisting of the following fields. + See [`MOUNTS`](https://github.com/opencontainers/runtime-spec/blob/master/config.md#mounts). - mount of the plugin, struct consisting of the following fields, see [`MOUNTS`](https://github.com/opencontainers/runtime-spec/blob/master/config.md#mounts) + - `name` string - - **`name`** *string* + Name of the mount. - name of the mount. + - `description` string - - **`description`** *string* + Description of the mount. - description of the mount. + - `source` string - - **`source`** *string* + Source of the mount. - source of the mount. + - `destination` string - - **`destination`** *string* + Destination of the mount. - destination of the mount. + - `type` string - - **`type`** *string* + Mount type. - mount type. + - `options` string array - - **`options`** *string array* + Options of the mount. - options of the mount. +- `ipchost` Boolean -- **`ipchost`** *boolean* Access to host ipc namespace. -- **`pidhost`** *boolean* - Access to host pid namespace. -- **`propagatedMount`** *string* +- `pidhost` Boolean - 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 { diff --git a/docs/extend/index.md b/docs/extend/index.md index b0c2f29589..22ab0f3f30 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -1,24 +1,14 @@ --- +title: Docker Engine managed plugin system description: Develop and use a plugin with the managed plugin system keywords: "API, Usage, plugins, documentation, developer" --- - - -# Docker Engine managed plugin system - - [Installing and using a plugin](index.md#installing-and-using-a-plugin) - [Developing a plugin](index.md#developing-a-plugin) - [Debugging plugins](index.md#debugging-plugins) -Docker Engine's plugin system allows you to install, start, stop, and remove +Docker Engine's plugin system lets you install, start, stop, and remove plugins using Docker Engine. For information about legacy (non-managed) plugins, refer to @@ -49,78 +39,78 @@ enabled, and use it to create a volume. > **Note** > > This example is intended for instructional purposes only. Once the volume is -> created, your SSH password to the remote host will be exposed as plaintext -> when inspecting the volume. You should delete the volume as soon as you are -> done with the example. +> created, your SSH password to the remote host is exposed as plaintext when +> inspecting the volume. Delete the volume as soon as you are done with the +> example. -1. Install the `sshfs` plugin. +1. Install the `sshfs` plugin. - ```console - $ docker plugin install vieux/sshfs + ```console + $ docker plugin install vieux/sshfs - Plugin "vieux/sshfs" is requesting the following privileges: - - network: [host] - - capabilities: [CAP_SYS_ADMIN] - Do you grant the above permissions? [y/N] y + Plugin "vieux/sshfs" is requesting the following privileges: + - network: [host] + - capabilities: [CAP_SYS_ADMIN] + Do you grant the above permissions? [y/N] y - vieux/sshfs - ``` + vieux/sshfs + ``` - The plugin requests 2 privileges: + The plugin requests 2 privileges: - - It needs access to the `host` network. - - It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run - the `mount` command. + - It needs access to the `host` network. + - It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run + the `mount` command. -2. Check that the plugin is enabled in the output of `docker plugin ls`. +2. Check that the plugin is enabled in the output of `docker plugin ls`. - ```console - $ docker plugin ls + ```console + $ docker plugin ls - ID NAME TAG DESCRIPTION ENABLED - 69553ca1d789 vieux/sshfs latest the `sshfs` plugin true - ``` + ID NAME TAG DESCRIPTION ENABLED + 69553ca1d789 vieux/sshfs latest the `sshfs` plugin true + ``` -3. Create a volume using the plugin. - This example mounts the `/remote` directory on host `1.2.3.4` into a - volume named `sshvolume`. +3. Create a volume using the plugin. + This example mounts the `/remote` directory on host `1.2.3.4` into a + volume named `sshvolume`. - This volume can now be mounted into containers. + This volume can now be mounted into containers. - ```console - $ docker volume create \ - -d vieux/sshfs \ - --name sshvolume \ - -o sshcmd=user@1.2.3.4:/remote \ - -o password=$(cat file_containing_password_for_remote_host) + ```console + $ docker volume create \ + -d vieux/sshfs \ + --name sshvolume \ + -o sshcmd=user@1.2.3.4:/remote \ + -o password=$(cat file_containing_password_for_remote_host) - sshvolume - ``` + sshvolume + ``` -4. Verify that the volume was created successfully. +4. Verify that the volume was created successfully. - ```console - $ docker volume ls + ```console + $ docker volume ls - DRIVER NAME - vieux/sshfs sshvolume - ``` + DRIVER NAME + vieux/sshfs sshvolume + ``` -5. Start a container that uses the volume `sshvolume`. +5. Start a container that uses the volume `sshvolume`. - ```console - $ docker run --rm -v sshvolume:/data busybox ls /data + ```console + $ docker run --rm -v sshvolume:/data busybox ls /data - - ``` + + ``` -6. Remove the volume `sshvolume` +6. Remove the volume `sshvolume` - ```console - $ docker volume rm sshvolume + ```console + $ docker volume rm sshvolume - sshvolume - ``` + sshvolume + ``` To disable a plugin, use the `docker plugin disable` command. To completely remove it, use the `docker plugin remove` command. For other available @@ -134,8 +124,10 @@ commands and options, see the The `rootfs` directory represents the root filesystem of the plugin. In this example, it was created from a Dockerfile: -> **Note:** The `/run/docker/plugins` directory is mandatory inside of the -> plugin's filesystem for docker to communicate with the plugin. +> **Note** +> +> The `/run/docker/plugins` directory is mandatory inside of the +> plugin's filesystem for Docker to communicate with the plugin. ```console $ git clone https://github.com/vieux/docker-volume-sshfs @@ -219,11 +211,10 @@ INFO[0421] Path Called... Returned path /data/samplevol plugin=f52a3df433b9a INFO[0421] Unmount Called... Unmounted samplevol plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 ``` -#### Using docker-runc to obtain logfiles and shell into the plugin. +#### Using runc to obtain logfiles and shell into the plugin. -`docker-runc`, the default docker container runtime can be used for debugging -plugins. This is specifically useful to collect plugin logs if they are -redirected to a file. +Use `runc`, the default docker container runtime, for debugging plugins by +collecting plugin logs redirected to a file. ```console $ sudo runc --root /run/docker/runtime-runc/plugins.moby list diff --git a/docs/extend/legacy_plugins.md b/docs/extend/legacy_plugins.md index 31a8a655fb..0086761c19 100644 --- a/docs/extend/legacy_plugins.md +++ b/docs/extend/legacy_plugins.md @@ -1,21 +1,11 @@ --- +title: Use Docker Engine plugins aliases: - "/engine/extend/plugins/" description: "How to add additional functionality to Docker with plugins extensions" keywords: "Examples, Usage, plugins, docker, documentation, user guide" --- - - -# Use Docker Engine plugins - This document describes the Docker Engine plugins generally available in Docker Engine. To view information on plugins managed by Docker, refer to [Docker Engine plugin system](index.md). @@ -40,7 +30,7 @@ Follow the instructions in the plugin's documentation. ## Finding a plugin -The sections below provide an inexhaustive overview of available plugins. +The sections below provide an overview of available third-party plugins. ### Network plugins @@ -97,4 +87,4 @@ of the plugin for help. The Docker team may not be able to assist you. ## Writing a plugin If you are interested in writing a plugin for Docker, or seeing how they work -under the hood, see the [docker plugins reference](plugin_api.md). +under the hood, see the [Docker plugins reference](plugin_api.md). diff --git a/docs/extend/plugin_api.md b/docs/extend/plugin_api.md index 812b465085..4600992c4e 100644 --- a/docs/extend/plugin_api.md +++ b/docs/extend/plugin_api.md @@ -1,19 +1,9 @@ --- +title: Docker Plugin API description: "How to write Docker plugins extensions " keywords: "API, Usage, plugins, documentation, developer" --- - - -# Docker Plugin API - Docker plugins are out-of-process extensions which add capabilities to the Docker Engine. @@ -26,8 +16,8 @@ If you just want to learn about or use Docker plugins, look ## What plugins are -A plugin is a process running on the same or a different host as the docker daemon, -which registers itself by placing a file on the same docker host in one of the plugin +A plugin is a process running on the same or a different host as the Docker daemon, +which registers itself by placing a file on the 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 diff --git a/docs/extend/plugins_authorization.md b/docs/extend/plugins_authorization.md index 203c1bf2e2..8a646e50fa 100644 --- a/docs/extend/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -1,22 +1,12 @@ --- +title: Access authorization plugin description: "How to create authorization plugins to manage access control to your Docker daemon." keywords: "security, authorization, authentication, docker, documentation, plugin, extend" aliases: - "/engine/extend/authorization/" --- - - -# Access authorization plugin - -This document describes the Docker Engine plugins generally available in Docker +This document describes the Docker Engine plugins available in Docker Engine. To view information on plugins managed by Docker Engine, refer to [Docker Engine plugin system](index.md). @@ -41,7 +31,7 @@ third-party components using a generic API. The access authorization subsystem was built using this mechanism. Using this subsystem, you don't need to rebuild the Docker daemon to add an -authorization plugin. You can add a plugin to an installed Docker daemon. You do +authorization plugin. You can add a plugin to an installed Docker daemon. You do need to restart the Docker daemon to add a new plugin. An authorization plugin approves or denies requests to the Docker daemon based @@ -158,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 diff --git a/docs/extend/plugins_logging.md b/docs/extend/plugins_logging.md index d6ce96cfb3..2d30571fe3 100644 --- a/docs/extend/plugins_logging.md +++ b/docs/extend/plugins_logging.md @@ -1,19 +1,9 @@ --- +title: Docker log driver plugins description: "Log driver plugins." keywords: "Examples, Usage, plugins, docker, documentation, user guide, logging" --- - - -# Docker log driver plugins - This document describes logging driver plugins for Docker. Logging drivers enables users to forward container logs to another service for @@ -46,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 }} ``` diff --git a/docs/extend/plugins_metrics.md b/docs/extend/plugins_metrics.md index c698a5a137..dc47e46926 100644 --- a/docs/extend/plugins_metrics.md +++ b/docs/extend/plugins_metrics.md @@ -1,20 +1,10 @@ --- +title: Docker metrics collector plugins description: "Metrics plugins." keywords: "Examples, Usage, plugins, docker, documentation, user guide, metrics" --- - - -# Docker metrics collector plugins - -Docker exposes internal metrics based on the prometheus format. Metrics plugins +Docker exposes internal metrics based on the Prometheus format. Metrics plugins enable accessing these metrics in a consistent way by providing a Unix socket at a predefined path where the plugin can scrape the metrics. @@ -44,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": "" } ``` diff --git a/docs/extend/plugins_network.md b/docs/extend/plugins_network.md index 46075e5734..e24fd26257 100644 --- a/docs/extend/plugins_network.md +++ b/docs/extend/plugins_network.md @@ -1,19 +1,9 @@ --- +title: Docker network driver plugins description: "Network driver plugins." keywords: "Examples, Usage, plugins, docker, documentation, user guide" --- - - -# Docker network driver plugins - This document describes Docker Engine network driver plugins generally available in Docker Engine. To view information on plugins managed by Docker Engine, refer to [Docker Engine plugin system](index.md). @@ -26,11 +16,11 @@ LibNetwork, which shares plugin infrastructure with Engine. Effectively, network driver plugins are activated in the same way as other plugins, and use the same kind of protocol. -## Network plugins and swarm mode +## Network plugins and Swarm mode -[Legacy plugins](legacy_plugins.md) do not work in swarm mode. However, -plugins written using the [v2 plugin system](index.md) do work in swarm mode, as -long as they are installed on each swarm worker node. +[Legacy plugins](legacy_plugins.md) do not work in Swarm mode. However, +plugins written using the [v2 plugin system](index.md) do work in Swarm mode, as +long as they are installed on each Swarm worker node. ## Use network driver plugins @@ -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 diff --git a/docs/extend/plugins_volume.md b/docs/extend/plugins_volume.md index 23e7cddf9e..3e42bc75aa 100644 --- a/docs/extend/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -1,19 +1,9 @@ --- +title: Docker volume plugins description: "How to manage data with external volume plugins" keywords: "Examples, Usage, volume, docker, data, volumes, plugin, api" --- - - -# Docker volume plugins - Docker Engine volume plugins enable Engine deployments to be integrated with external storage systems such as Amazon EBS, and enable data volumes to persist beyond the lifetime of a single Docker host. See the @@ -50,7 +40,7 @@ beyond the lifetime of a single Docker host. See the ## Command-line changes To give a container access to a volume, use the `--volume` and `--volume-driver` -flags on the `docker container run` command. The `--volume` (or `-v`) flag +flags on the `docker container run` command. The `--volume` (or `-v`) flag accepts a volume name and path on the host, and the `--volume-driver` flag accepts a driver type. @@ -98,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": {