diff --git a/docs/extend/index.md b/docs/extend/index.md deleted file mode 100644 index 588dc10a2f..0000000000 --- a/docs/extend/index.md +++ /dev/null @@ -1,20 +0,0 @@ - - - -## Extending Docker Engine - -Currently, you can extend Docker Engine by adding a plugin. This section contains the following topics: - -* [New Docker Plugin System](new/index.md) -* [Legacy Docker Plugins](legacy/index.md) - diff --git a/docs/extend/legacy/index.md b/docs/extend/legacy/index.md deleted file mode 100644 index 031d7d2394..0000000000 --- a/docs/extend/legacy/index.md +++ /dev/null @@ -1,22 +0,0 @@ - - - -## Legacy Docker Plugins - -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) -* [Write a network plugin](plugins_network.md) -* [Write an authorization plugin](plugins_authorization.md) -* [Docker plugin API](plugin_api.md) diff --git a/docs/extend/legacy/plugins.md b/docs/extend/legacy_plugins.md similarity index 97% rename from docs/extend/legacy/plugins.md rename to docs/extend/legacy_plugins.md index 72d50bd150..02874f315e 100644 --- a/docs/extend/legacy/plugins.md +++ b/docs/extend/legacy_plugins.md @@ -5,11 +5,15 @@ description = "How to add additional functionality to Docker with plugins extens keywords = ["Examples, Usage, plugins, docker, documentation, user guide"] [menu.main] parent = "engine_extend" -weight=-1 +weight=3 +++ -# Understand Engine plugins +# Understand legacy 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). 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 @@ -72,7 +76,7 @@ Plugin ### Authorization plugins - Plugin | Description + Plugin | Description ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ [Twistlock AuthZ Broker](https://github.com/twistlock/authz) | A basic extendable authorization plugin that runs directly on the host or inside a container. This plugin allows you to define user policies that it evaluates during authorization. Basic authorization is provided if Docker daemon is started with the --tlsverify flag (username is extracted from the certificate common name). diff --git a/docs/extend/new/index.md b/docs/extend/menu.md similarity index 78% rename from docs/extend/new/index.md rename to docs/extend/menu.md index 9c809a03a4..026e56427f 100644 --- a/docs/extend/new/index.md +++ b/docs/extend/menu.md @@ -1,12 +1,13 @@ diff --git a/docs/extend/new/plugins.md b/docs/extend/new/plugins.md deleted file mode 100644 index 04f83ea243..0000000000 --- a/docs/extend/new/plugins.md +++ /dev/null @@ -1,227 +0,0 @@ - - -# New Plugin System - -The goal of this document is to describe the current state of the new plugin system available today in the **experimental build** of Docker 1.12. - -The main difference, compared to legacy plugins, is that plugins are now managed by Docker: plugins are installed, started, stopped and removed by docker. - -Only volume drivers are currently supported but more types will be added in the next release. - -This document is split in two parts, the user perspective, “how to operate a plugin” and the developer perspective “how to create a plugin” - - -## How to operate a plugin - -Plugins are distributed as docker images, so they can be hosted on the Docker Hub or on a private registry. -Installing a plugin is very easy, it’s a simple command: `docker plugin install` -This command is going to pull the plugin from the Docker Hub / Private registry, ask the operator to accept privileges (for example, plugin requires access to a device on the host system), if necessary and enable it. -You can then check the status of the plugin with the docker plugin ls command, the plugin will be marked as ENABLED if it was started without issue. - -Then, the plugin behavior is the same as legacy plugins, here is a full example using a sshfs plugin: - -### install the 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 -``` - -Here the plugin requests 2 privileges, the `CAP_SYS_ADMIN` capability to be able to do mount inside the plugin and `host networking`. - -### verify that the plugin has correctly started -##### by looking at the ENABLED column. (The value should be true) - -```bash -$ docker plugin ls -NAME TAG ENABLED -vieux/sshfs latest true -``` - -### create a volume using the plugin installed above - -```bash -$ docker volume create -d vieux/sshfs --name sshvolume -o sshcmd=user@1.2.3.4:/remote -sshvolume -``` - -### use the volume created above - -```bash -$ docker run -v sshvolume:/data busybox ls /data - -``` - -### verify that the plugin was created successfully - -```bash -$ docker volume ls -DRIVER NAME -vieux/sshfs sshvolume -``` - -It’s also possible to stop a plugin with the `docker plugin disable` command and to remove a plugin with `docker plugin remove`. - -See the [command line reference](../engine/reference/commandline/) for more information. - -## How to create a plugin - -The creation of plugin is currently a manual process, in the future release, a command such as `docker plugin build` will be added to automate the process. So here we are going to describe the format of an existing enabled plugin, to create a plugin you have to manually craft all those files by hand. - -Plugins are stored in `/var/lib/docker/plugins`. See this example: - -```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 -``` - -The file `plugins.json` is an inventory of all installed plugins, see an example of the content: - -```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 this Dockerfile as follows: - -_Note: `/run/docker/plugins` is mandatory for docker to communicate with the plugin._ - -```bash -$ git clone 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` describe the plugin and `plugin-config.json` contains some runtime parameters, see 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": [] -} -``` - -No runtime parameters are needed for this 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. - - - -To sum up, here are the steps required to create a plugin today: - -0. choose the name of the plugins, same format as images, for example `/` -1. create a rootfs as showed above in `/var/lib/docker/plugins/$id/rootfs` -2. create manifest.json file in `/var/lib/docker/plugins/$id/` as shown above -3. create a `plugin-config.json` if needed, as shown above. -4. create or add a section to `/var/lib/docker/plugins/plugins.json` as shown above, use -`/` as “Name” and `$id` as “Id” -5. restart docker -6. `docker plugin ls` - a. if your plugin is listed as `ENABLED=true`, go to 7. - b. if the plugins is not listed or listed as `ENABLED=false` something went wrong, look at the daemon logs. -7. if not logged in already, use `docker login` to authenticate against a registry. -8. push the plugin with `docker plugin push /` - - diff --git a/docs/extend/legacy/plugin_api.md b/docs/extend/plugin_api.md similarity index 96% rename from docs/extend/legacy/plugin_api.md rename to docs/extend/plugin_api.md index a799a13520..1f55b6d528 100644 --- a/docs/extend/legacy/plugin_api.md +++ b/docs/extend/plugin_api.md @@ -5,7 +5,7 @@ description = "How to write Docker plugins extensions " keywords = ["API, Usage, plugins, documentation, developer"] [menu.main] parent = "engine_extend" -weight=1 +weight=7 +++ @@ -14,9 +14,13 @@ weight=1 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 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 -[here](plugins.md). +[here](legacy_plugins.md). ## What plugins are diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md new file mode 100644 index 0000000000..fb7af836e5 --- /dev/null +++ b/docs/extend/plugins.md @@ -0,0 +1,272 @@ + + +# 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 `. +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 + + + ``` + +5. Verify the plugin successfully crated 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](../engine/reference/commandline/) 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 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: `/`. +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 + `/` 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 /` to push the plugin. diff --git a/docs/extend/legacy/plugins_authorization.md b/docs/extend/plugins_authorization.md similarity index 97% rename from docs/extend/legacy/plugins_authorization.md rename to docs/extend/plugins_authorization.md index 8630bfb761..572c6e99be 100644 --- a/docs/extend/legacy/plugins_authorization.md +++ b/docs/extend/plugins_authorization.md @@ -6,13 +6,17 @@ keywords = ["security, authorization, authentication, docker, documentation, plu aliases = ["/engine/extend/authorization/"] [menu.main] parent = "engine_extend" -weight = -1 +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). + 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 same is true for callers using Docker's remote API to contact the daemon. If you diff --git a/docs/extend/legacy/plugins_network.md b/docs/extend/plugins_network.md similarity index 91% rename from docs/extend/legacy/plugins_network.md rename to docs/extend/plugins_network.md index ec1ccddfea..f1d72ceeae 100644 --- a/docs/extend/legacy/plugins_network.md +++ b/docs/extend/plugins_network.md @@ -5,11 +5,16 @@ description = "Network driver plugins." keywords = ["Examples, Usage, plugins, docker, documentation, user guide"] [menu.main] parent = "engine_extend" +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). + Docker Engine network plugins enable Engine deployments to be extended to support a wide range of networking technologies, such as VXLAN, IPVLAN, MACVLAN or something completely different. Network driver plugins are supported via the diff --git a/docs/extend/legacy/plugins_volume.md b/docs/extend/plugins_volume.md similarity index 96% rename from docs/extend/legacy/plugins_volume.md rename to docs/extend/plugins_volume.md index 66afa7d439..45eb25eb04 100644 --- a/docs/extend/legacy/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -5,11 +5,16 @@ description = "How to manage data with external volume plugins" keywords = ["Examples, Usage, volume, docker, data, volumes, plugin, api"] [menu.main] parent = "engine_extend" +weight=6 +++ # Write a volume plugin +This document describes Docker Engine volume 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). + 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