@@ -1,51 +1,54 @@

 ---

-aliases: [

-"/engine/extend/"

-]

-title: "Managed plugin system"

-description: "How develop and use a plugin with the managed plugin system"

-keywords: ["API, Usage, plugins, documentation, developer"]

-advisory: "experimental"

+advisory: experimental

+aliases:

+- /engine/extend/

+description: Develop and use a plugin with the managed plugin system

+keywords:

+- API, Usage, plugins, documentation, developer

+title: Managed plugin system

 ---

+<!-- This file is maintained within the docker/docker Github

+     repository at https://github.com/docker/docker/. 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

 This document describes the plugin system available today in the **experimental

 build** of Docker 1.12:

-* [How to operate an existing plugin](#how-to-operate-a-plugin)

-* [How to develop a plugin](#how-to-develop-a-plugin)

-

-Unlike the legacy plugin system, you now manage plugins using Docker Engine:

+* [Installing and using a plugin](index.md#installing-and-using-a-plugin)

+* [Developing a plugin](index.md#developing-a-plugin)

-* install plugins

-* start plugins

-* stop plugins

-* remove plugins

+Docker Engine's plugins system allows you to install, start, stop, and remove

+plugins using Docker Engine. This mechanism is currently only available for

+volume drivers, but more plugin driver types will be available in future releases.

-The current Docker Engine plugin system only supports volume drivers. We are

-adding more plugin driver types in the future releases.

+For information about the legacy plugin system available in Docker Engine 1.12

+and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md).

-For information on Docker Engine plugins generally available in Docker Engine

-1.12 and earlier, refer to [Understand legacy Docker Engine plugins](legacy_plugins.md).

+## Installing and using a plugin

-## How to operate a plugin

+Plugins are distributed as Docker images and can be hosted on Docker Hub or on

+a private registry.

-Plugins are distributed as Docker images, so develpers can host them on Docker

-Hub or on a private registry.

+To install a plugin, use the `docker plugin install` command, which pulls the

+plugin from Docker hub or your private registry, prompts you to grant

+permissions or capabilities if necessary, and enables the plugin.

-You install the plugin using a single command: `docker plugin install <PLUGIN>`.

-The `plugin install` command pulls the plugin from the Docker Hub or private

-registry. If necessary the CLI prompts you to accept any privilege requriements.

-For example the plugin may require access to a device on the host system.

-Finally it enables the plugin.

+To check the status of installed plugins, use the `docker plugin ls` command.

+Plugins that start successfully are listed as enabled in the output.

-Run `docker plugin ls` to check the status of installed plugins. The Engine

-markes plugins that are started without issues as `ENABLED`.

+After a plugin is installed, you can use it as an option for another Docker

+operation, such as creating a volume.

-After you install a plugin, the plugin behavior is the same as legacy plugins.

-The following example demonstrates how to install the `sshfs` plugin and use it

-to create a volume.

+In the following example, you install the `sshfs` plugin, verify that it is

+enabled, and use it to create a volume.

 1.  Install the `sshfs` plugin.

@@ -60,11 +63,12 @@ to create a volume.

     vieux/sshfs

     ```

-    The plugin requests 2 privileges, the `CAP_SYS_ADMIN` capability to be able

-    to do mount inside the plugin and `host networking`.

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

-2.  Check for a value of `true` the `ENABLED` column to verify the plugin

-started without error.

+2.  Check that the plugin is enabled in the output of `docker plugin ls`.

     ```bash

     $ docker plugin ls

@@ -74,6 +78,8 @@ started without error.

     ```

 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.

     ```bash

     $ docker volume create \

@@ -83,39 +89,39 @@ started without error.

     sshvolume

     ```

-

-4.  Use the volume `sshvolume`.

+4.  Verify that the volume was created successfully.

     ```bash

-    $ docker run -v sshvolume:/data busybox ls /data

+    $ docker volume ls

-    <content of /remote on machine 1.2.3.4>

+    DRIVER              NAME

+    vieux/sshfs         sshvolume

     ```

-5.  Verify the plugin successfully created the volume.

+5.  Start a container that uses the volume `sshvolume`.

     ```bash

-    $ docker volume ls

+    $ docker run -v sshvolume:/data busybox ls /data

-    DRIVER              VOLUME NAME

-    vieux/sshfs         sshvolume

+    <content of /remote on machine 1.2.3.4>

     ```

-    You can stop a plugin with the `docker plugin disable`

-    command or remove a plugin with `docker plugin remove`.

-

-See the [command line reference](../reference/commandline/index.md) for more

-information.

+To disable a plugin, use the `docker plugin disable` command. To completely

+remove it, use the `docker plugin remove` command. For other available

+commands and options, see the

+[command line reference](../reference/commandline/index.md).

-## How to develop a plugin

+## Developing a plugin

-Plugin creation is currently a manual process. We plan to add automation in a

-future release with a command such as `docker plugin build`.

+Currently, there are no CLI commands available to help you develop a plugin.

+This is expected to change in a future release. The manual process for creating

+plugins is described in this section.

-This section describes the format of an existing enabled plugin. You have to

-create and format the plugin files by hand.

+### Plugin location and files

-Plugins are stored in `/var/lib/docker/plugins`. For instance:

+Plugins are stored in `/var/lib/docker/plugins`. The `plugins.json` file lists

+each plugin's configuration, and each plugin is stored in a directory with a

+unique identifier.

 ```bash

 # ls -la /var/lib/docker/plugins

@@ -126,9 +132,12 @@ drwxr-xr-x  3 root root 4096 Aug  8 17:56 cd851ce43a403

 -rw-------  1 root root 2107 Aug  8 18:03 plugins.json

 ```

-`plugins.json` is an inventory of all installed plugins. For example:

+### Format of plugins.json

-```bash

+The `plugins.json` is an inventory of all installed plugins. This example shows

+a `plugins.json` with a single plugin installed.

+

+```json

 # cat plugins.json

 {

   "cd851ce43a403": {

@@ -179,7 +188,10 @@ drwxr-xr-x  3 root root 4096 Aug  8 17:56 cd851ce43a403

 }

 ```

-Each folder represents a plugin. For example:

+### Contents of a plugin directory

+

+Each directory within `/var/lib/docker/plugins/` contains a `rootfs` directory

+and two JSON files.

 ```bash

 # ls -la /var/lib/docker/plugins/cd851ce43a403

@@ -189,28 +201,34 @@ drwx------ 19 root root 4096 Aug  8 17:56 rootfs

 -rw-------  1 root root  347 Aug  8 17:56 manifest.json

 ```

-`rootfs` represents the root filesystem of the plugin. In this example, it was

-created from a Dockerfile as follows:

+#### The rootfs directory

+The `rootfs` directory represents the root filesystem of the plugin. In this

+example, it was created from a Dockerfile:

->**Note:** `/run/docker/plugins` is mandatory for docker to communicate with

-the plugin._

+>**Note:** The `/run/docker/plugins` directory is mandatory for docker to communicate with

+the plugin.

 ```bash

 $ git clone https://github.com/vieux/docker-volume-sshfs

 $ cd docker-volume-sshfs

 $ docker build -t rootfs .

 $ id=$(docker create rootfs true) # id was cd851ce43a403 when the image was created

-$ mkdir -p /var/lib/docker/plugins/$id/rootfs

-$ docker export "$id" | tar -x -C /var/lib/docker/plugins/$id/rootfs

+$ sudo mkdir -p /var/lib/docker/plugins/$id/rootfs

+$ sudo docker export "$id" | sudo tar -x -C /var/lib/docker/plugins/$id/rootfs

+$ sudo chgrp -R docker /var/lib/docker/plugins/

 $ docker rm -vf "$id"

 $ docker rmi rootfs

 ```

-`manifest.json` describes the plugin and `plugin-config.json` contains some

-runtime parameters. [See the Plugins Manifest reference](manifest.md). For example:

+#### The manifest.json and plugin-config.json files

-```bash

-# cat manifest.json

+The `manifest.json` file describes the plugin. The `plugin-config.json` file

+contains runtime parameters and is only required if your plugin has runtime

+parameters. [See the Plugins Manifest reference](manifest.md).

+

+Consider the following `manifest.json` file.

+

+```json

 {

 	"manifestVersion": "v0",

 	"description": "sshFS plugin for Docker",

@@ -227,13 +245,15 @@ runtime parameters. [See the Plugins Manifest reference](manifest.md). For examp

 }

 ```

-In this example, you can see the plugin is a volume driver, requires the

-`CAP_SYS_ADMIN` capability, `host networking`, `/go/bin/docker-volume-sshfs` as

-entrypoint and is going to use `/run/docker/plugins/sshfs.sock` to communicate

-with the Docker Engine.

+This plugin is a volume driver. It requires a `host` network and the

+`CAP_SYS_ADMIN` capability. It depends upon the `/go/bin/docker-volume-sshfs`

+entrypoint and uses the `/run/docker/plugins/sshfs.sock` socket to communicate

+with Docker Engine.

-```bash

-# cat plugin-config.json

+

+Consider the following `plugin-config.json` file.

+

+```json

 {

   "Devices": null,

   "Args": null,

@@ -242,26 +262,42 @@ with the Docker Engine.

 }

 ```

-This plugin doesn't require runtime parameters.

+This plugin has no runtime parameters.

+

+Each of these JSON files is included as part of `plugins.json`, as you can see

+by looking back at the example above. After a plugin is installed, `manifest.json`

+is read-only, but `plugin-config.json` is read-write, and includes all runtime

+configuration options for the plugin.

+

+### Creating the plugin

+

+Follow these steps to create a plugin:

-Both `manifest.json` and `plugin-config.json` are part of the `plugins.json`.

-`manifest.json` is read-only and `plugin-config.json` is read-write.

+1. Choose a name for the plugin. Plugin name uses the same format as images,

+   for example: `<repo_name>/<name>`.

-To summarize, follow the steps below to create a plugin:

+2. Create a `rootfs` and export it to `/var/lib/docker/plugins/$id/rootfs`

+   using `docker export`. See [The rootfs directory](#the-rootfs-directory) for

+   an example of creating a `rootfs`.

-0. Choose a name for the plugin. Plugin name uses the same format as images,

-for example: `<repo_name>/<name>`.

-1. Create a rootfs in `/var/lib/docker/plugins/$id/rootfs`.

-2. Create manifest.json file in `/var/lib/docker/plugins/$id/`.

-3. Create a `plugin-config.json` if needed.

-4. Create or add a section to `/var/lib/docker/plugins/plugins.json`. Use

+3. Create a `manifest.json` file in `/var/lib/docker/plugins/$id/`.

+

+4. Create a `plugin-config.json` file if needed.

+

+5. Create or add a section to `/var/lib/docker/plugins/plugins.json`. Use

    `<user>/<name>` as “Name” and `$id` as “Id”.

-5. Restart the Docker Engine.

-6. Run `docker plugin ls`.

-    * If your plugin is listed as `ENABLED=true`, you can push it to the

-    registry.

-    * If the plugin is not listed or if `ENABLED=false`, something went wrong.

-    Check the daemon logs for errors.

-7. If you are not already logged in, use `docker login` to authenticate against

-   a registry.

-8. Run `docker plugin push <repo_name>/<name>` to push the plugin.

+

+6. Restart the Docker Engine service.

+

+7. Run `docker plugin ls`.

+    * If your plugin is enabled, you can push it to the

+      registry.

+    * If the plugin is not listed or is disabled, something went wrong.

+      Check the daemon logs for errors.

+

+8. If you are not already logged in, use `docker login` to authenticate against

+   the registry so that you can push to it.

+

+9. Run `docker plugin push <repo_name>/<name>` to push the plugin.

+

+The plugin can now be used by any user with access to your registry.