Rewrites to Developing Plugins topic

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
(cherry picked from commit b39e65e9378cf6a32bcc3ac3bd8b982d339ea25d)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/extend/index.md

@@ -1,48 +1,50 @@
 ---
-redirect_from:
-- "/engine/extend/"
-title: "Docker Engine 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
+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.
+-->
+
 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.
 
@@ -57,11 +59,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
@@ -71,6 +74,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 \
@@ -80,39 +85,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              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`.
+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).
 
-See the [command line reference](../reference/commandline/index.md) for more
-information.
+## Developing a plugin
 
-## How to develop a plugin
+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.
 
-Plugin creation is currently a manual process. We plan to add automation in a
-future release with a command such as `docker plugin build`.
+### Plugin location and files
 
-This section describes the format of an existing enabled plugin. You have to
-create and format the plugin files by hand.
-
-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
@@ -123,9 +128,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": {
@@ -176,7 +184,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
@@ -186,28 +197,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",
@@ -224,13 +241,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,
@@ -239,26 +258,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
 
-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.
+Follow these steps to create a plugin:
 
-To summarize, follow the steps below to create a plugin:
+1. Choose a name for the plugin. Plugin name uses the same format as images,
+   for example: `<repo_name>/<name>`.
 
-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
+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`.
+
+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.