new file mode 100644

@@ -0,0 +1,272 @@

+<!--[metadata]>

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

+[menu.main]

+parent = "engine_extend"

+weight=1

+<![end-metadata]-->

+

+# 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:

+

+* install plugins

+* start plugins

+* stop plugins

+* remove plugins

+

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

+adding more plugin driver types in the future releases.

+

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

+

+## How to operate a plugin

+

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

+Hub or on a private registry.

+

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

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

+Finally it enables the plugin.

+

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

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

+

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

+

+1.  Install the `sshfs` plugin.

+

+    ```bash

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

+

+    vieux/sshfs

+    ```

+

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

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

+

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

+started without error.

+

+    ```bash

+    $ docker plugin ls

+

+    NAME                TAG                 ENABLED

+    vieux/sshfs         latest              true

+    ```

+

+3. Create a volume using the plugin.

+

+    ```bash

+    $ docker volume create \

+      -d vieux/sshfs \

+      --name sshvolume \

+      -o sshcmd=user@1.2.3.4:/remote

+

+    sshvolume

+    ```

+

+4.  Use the volume `sshvolume`.

+

+    ```bash

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

+

+    <content of /remote on machine 1.2.3.4>

+    ```

+

+5. Verify the plugin successfully created the volume.

+

+    ```bash

+    $ docker volume ls

+

+    DRIVER              NAME

+    vieux/sshfs         sshvolume

+    ```

+

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

+

+## How to develop 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`.

+

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

+

+```bash

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

+total 20

+drwx------  4 root root 4096 Aug  8 18:03 .

+drwx--x--x 12 root root 4096 Aug  8 17:53 ..

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

+

+```bash

+# cat plugins.json

+{

+  "cd851ce43a403": {

+    "plugin": {

+      "Manifest": {

+        "Args": {

+          "Value": null,

+          "Settable": null,

+          "Description": "",

+          "Name": ""

+        },

+        "Env": null,

+        "Devices": null,

+        "Mounts": null,

+        "Capabilities": [

+          "CAP_SYS_ADMIN"

+        ],

+        "ManifestVersion": "v0.1",

+        "Description": "sshFS plugin for Docker",

+        "Documentation": "https://docs.docker.com/engine/extend/plugins/",

+        "Interface": {

+          "Socket": "sshfs.sock",

+          "Types": [

+            "docker.volumedriver/1.0"

+          ]

+        },

+        "Entrypoint": [

+          "/go/bin/docker-volume-sshfs"

+        ],

+        "Workdir": "",

+        "User": {},

+        "Network": {

+          "Type": "host"

+        }

+      },

+      "Config": {

+        "Devices": null,

+        "Args": null,

+        "Env": [],

+        "Mounts": []

+      },

+      "Active": true,

+      "Tag": "latest",

+      "Name": "vieux/sshfs",

+      "Id": "cd851ce43a403"

+    }

+  }

+}

+```

+

+Each folder represents a plugin. For example:

+

+```bash

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

+total 12

+drwx------ 19 root root 4096 Aug  8 17:56 rootfs

+-rw-r--r--  1 root root   50 Aug  8 17:56 plugin-config.json

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

+

+>**Note:** `/run/docker/plugins` 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

+$ docker rm -vf "$id"

+$ docker rmi rootfs

+```

+

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

+runtime parameters. For example:

+

+```bash

+# cat manifest.json

+{

+	"manifestVersion": "v0.1",

+	"description": "sshFS plugin for Docker",

+	"documentation": "https://docs.docker.com/engine/extend/plugins/",

+	"entrypoint": ["/go/bin/docker-volume-sshfs"],

+	"network": {

+		   "type": "host"

+		   },

+		   "interface" : {

+		   	       "types": ["docker.volumedriver/1.0"],

+			       		"socket": "sshfs.sock"

+					},

+					"capabilities": ["CAP_SYS_ADMIN"]

+}

+```

+

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

+

+```bash

+# cat plugin-config.json

+{

+  "Devices": null,

+  "Args": null,

+  "Env": [],

+  "Mounts": []

+}

+```

+

+This plugin doesn't require runtime parameters.

+

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

+

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

+

+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

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

@@ -1,6 +1,7 @@

 <!--[metadata]>

 +++

-title = "Extending Engine with plugins"

+aliases = "/engine/extend/plugins/"

+title = "Use Docker Engine plugins"

 description = "How to add additional functionality to Docker with plugins extensions"

 keywords = ["Examples, Usage, plugins, docker, documentation, user guide"]

 [menu.main]

@@ -9,11 +10,11 @@ weight=3

 +++

 <![end-metadata]-->

-# Understand legacy Docker Engine plugins

+# Use Docker Engine plugins

 This document describes the Docker Engine plugins generally available in Docker

-Engine 1.12 and earlier. To view information on plugins managed by Docker

-Engine, refer to [Docker Engine plugin system](plugins.md).

+Engine. To view information on plugins managed by Docker Engine currently in

+experimental status, refer to [Docker Engine plugin system](index.md).

 You can extend the capabilities of the Docker Engine by loading third-party

 plugins. This page explains the types of plugins and provides links to several

@@ -21,7 +22,7 @@ volume and network plugins for Docker.

 ## Types of plugins

-Plugins extend Docker's functionality.  They come in specific types.  For

+Plugins extend Docker's functionality. They come in specific types.  For

 example, a [volume plugin](plugins_volume.md) might enable Docker

 volumes to persist across multiple Docker hosts and a

 [network plugin](plugins_network.md) might provide network plumbing.

@@ -1,7 +1,7 @@

 <!--[metadata]>

 +++

-title = "Extend Docker"

-description = "How to extend Docker Engine with plugins"

+title = "Implement plugins"

+description = "Develop plugins and use existing plugins for Docker Engine"

 keywords = ["extend, plugins, docker, documentation, developer"]

 type="menu"

 [menu.main]

@@ -12,9 +12,4 @@ weight = 0

 <![end-metadata]-->

-## New Docker Plugin System

-

-Currently, you can extend Docker Engine by adding a plugin. This section contains the following topics:

-

-* [Understand Docker plugins](plugins.md)

-* [Write a volume plugin](plugins_volume.md)

+<!--menu page not rendered-->

@@ -14,9 +14,9 @@ weight=7

 Docker plugins are out-of-process extensions which add capabilities to the

 Docker Engine.

-This document describes the Docker Engine plugin API generally available in

-Docker Engine 1.12 and earlier. To view information on plugins managed by Docker

-Engine, refer to [Docker Engine plugin system](plugins.md).

+This document describes the Docker Engine plugin API. To view information on

+plugins managed by Docker Engine currently in experimental status, refer to

+[Docker Engine plugin system](index.md).

 This page is intended for people who want to develop their own Docker plugin.

 If you just want to learn about or use Docker plugins, look

deleted file mode 100644

@@ -1,272 +0,0 @@

-<!--[metadata]>

-+++

-aliases = [

-"/engine/extend/"

-]

-title = "New Plugin System"

-description = "How to operate and create a plugin with the new system"

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

-advisory = "experimental"

-[menu.main]

-parent = "engine_extend"

-weight=1

-+++

-<![end-metadata]-->

-

-# Docker Engine 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:

-

-* install plugins

-* start plugins

-* stop plugins

-* remove plugins

-

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

-adding more plugin driver types in the future releases.

-

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

-

-## How to operate a plugin

-

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

-Hub or on a private registry.

-

-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 privilige requriements.

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

-Finally it enables the plugin.

-

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

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

-

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

-

-1.  Install the `sshfs` plugin.

-

-    ```bash

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

-

-    vieux/sshfs

-    ```

-

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

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

-

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

-started without error.

-

-    ```bash

-    $ docker plugin ls

-

-    NAME                TAG                 ENABLED

-    vieux/sshfs         latest              true

-    ```

-

-3. Create a volume using the plugin.

-

-    ```bash

-    $ docker volume create \

-      -d vieux/sshfs \

-      --name sshvolume \

-      -o sshcmd=user@1.2.3.4:/remote

-

-    sshvolume

-    ```

-

-4.  Use the volume `sshvolume`.

-

-    ```bash

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

-

-    <content of /remote on machine 1.2.3.4>

-    ```

-

-5. Verify the plugin successfully created the volume.

-

-    ```bash

-    $ docker volume ls

-

-    DRIVER              NAME

-    vieux/sshfs         sshvolume

-    ```

-

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

-

-## How to develop 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`.

-

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

-

-```bash

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

-total 20

-drwx------  4 root root 4096 Aug  8 18:03 .

-drwx--x--x 12 root root 4096 Aug  8 17:53 ..

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

-

-```bash

-# cat plugins.json

-{

-  "cd851ce43a403": {

-    "plugin": {

-      "Manifest": {

-        "Args": {

-          "Value": null,

-          "Settable": null,

-          "Description": "",

-          "Name": ""

-        },

-        "Env": null,

-        "Devices": null,

-        "Mounts": null,

-        "Capabilities": [

-          "CAP_SYS_ADMIN"

-        ],

-        "ManifestVersion": "v0.1",

-        "Description": "sshFS plugin for Docker",

-        "Documentation": "https://docs.docker.com/engine/extend/plugins/",

-        "Interface": {

-          "Socket": "sshfs.sock",

-          "Types": [

-            "docker.volumedriver/1.0"

-          ]

-        },

-        "Entrypoint": [

-          "/go/bin/docker-volume-sshfs"

-        ],

-        "Workdir": "",

-        "User": {},

-        "Network": {

-          "Type": "host"

-        }

-      },

-      "Config": {

-        "Devices": null,

-        "Args": null,

-        "Env": [],

-        "Mounts": []

-      },

-      "Active": true,

-      "Tag": "latest",

-      "Name": "vieux/sshfs",

-      "Id": "cd851ce43a403"

-    }

-  }

-}

-```

-

-Each folder represents a plugin. For example:

-

-```bash

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

-total 12

-drwx------ 19 root root 4096 Aug  8 17:56 rootfs

--rw-r--r--  1 root root   50 Aug  8 17:56 plugin-config.json

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

-

->**Note:** `/run/docker/plugins` 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

-$ docker rm -vf "$id"

-$ docker rmi rootfs

-```

-

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

-runtime parameters. For example:

-

-```bash

-# cat manifest.json

-{

-	"manifestVersion": "v0.1",

-	"description": "sshFS plugin for Docker",

-	"documentation": "https://docs.docker.com/engine/extend/plugins/",

-	"entrypoint": ["/go/bin/docker-volume-sshfs"],

-	"network": {

-		   "type": "host"

-		   },

-		   "interface" : {

-		   	       "types": ["docker.volumedriver/1.0"],

-			       		"socket": "sshfs.sock"

-					},

-					"capabilities": ["CAP_SYS_ADMIN"]

-}

-```

-

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

-

-```bash

-# cat plugin-config.json

-{

-  "Devices": null,

-  "Args": null,

-  "Env": [],

-  "Mounts": []

-}

-```

-

-This plugin doesn't require runtime parameters.

-

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

-

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

-

-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

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

@@ -13,9 +13,9 @@ weight = 4

 # Create an authorization plugin

-This document describes Docker Engine authorization plugins generally

-available in Docker Engine 1.12 and earlier. To view information on plugins

-managed by Docker Engine, refer to [Docker Engine plugin system](plugins.md).

+This document describes the Docker Engine plugins generally available in Docker

+Engine. To view information on plugins managed by Docker Engine currently in

+experimental status, refer to [Docker Engine plugin system](index.md).

 Docker's out-of-the-box authorization model is all or nothing. Any user with

 permission to access the Docker daemon can run any Docker client command. The

@@ -12,8 +12,8 @@ weight=5

 # Engine network driver plugins

 This document describes Docker Engine network driver plugins generally

-available in Docker Engine 1.12 and earlier. To view information on plugins

-managed by Docker Engine, refer to [Docker Engine plugin system](plugins.md).

+available in Docker Engine. To view information on plugins

+managed by Docker Engine, refer to [Docker Engine plugin system](index.md).

 Docker Engine network plugins enable Engine deployments to be extended to

 support a wide range of networking technologies, such as VXLAN, IPVLAN, MACVLAN

@@ -46,7 +46,7 @@ commands. For example,

     $ docker network create --driver weave mynet

-Some network driver plugins are listed in [plugins](plugins.md)

+Some network driver plugins are listed in [plugins](legacy_plugins.md)

 The `mynet` network is now owned by `weave`, so subsequent commands

 referring to that network will be sent to the plugin,

@@ -13,8 +13,8 @@ weight=6

 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 Engine host. See the [plugin

-documentation](plugins.md) for more information.

+beyond the lifetime of a single Engine host. See the

+[plugin documentation](legacy_plugins.md) for more information.

 ## Changelog

@@ -211,7 +211,7 @@ $ docker run -d -P \

 ```

 A list of available plugins, including volume plugins, is available

-[here](../extend/plugins.md).

+[here](../extend/legacy_plugins.md).

 ### Volume labels

@@ -537,7 +537,7 @@ built-in network drivers. For example:

 You can inspect it, add containers to and from it, and so forth. Of course,

 different plugins may make use of different technologies or frameworks. Custom

 networks can include features not present in Docker's default networks. For more

-information on writing plugins, see [Extending Docker](../../extend/plugins.md) and

+information on writing plugins, see [Extending Docker](../../extend/legacy_plugins.md) and

 [Writing a network driver plugin](../../extend/plugins_network.md).

 ### Docker embedded DNS server