diff --git a/components/engine/docs/extend/index.md b/components/engine/docs/extend/index.md index 661bfc9f71..e0689f776b 100644 --- a/components/engine/docs/extend/index.md +++ b/components/engine/docs/extend/index.md @@ -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 --- + + # 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) +* [Installing and using a plugin](index.md#installing-and-using-a-plugin) +* [Developing a plugin](index.md#developing-a-plugin) -Unlike the legacy plugin system, you now manage plugins using Docker Engine: +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. -* install plugins -* start plugins -* stop plugins -* remove plugins +For information about the legacy plugin system available in Docker Engine 1.12 +and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md). -The current Docker Engine plugin system only supports volume drivers. We are -adding more plugin driver types in the future releases. +## Installing and using a plugin -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). +Plugins are distributed as Docker images and can be hosted on Docker Hub or on +a private registry. -## How to operate a plugin +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. -Plugins are distributed as Docker images, so develpers can host them on Docker -Hub or on a private registry. +To check the status of installed plugins, use the `docker plugin ls` command. +Plugins that start successfully are listed as enabled in the output. -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 privilege requriements. -For example the plugin may require access to a device on the host system. -Finally it enables the plugin. +After a plugin is installed, you can use it as an option for another Docker +operation, such as creating a volume. -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. +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,8 +89,16 @@ started without error. sshvolume ``` +4. Verify that the volume was created successfully. -4. Use the volume `sshvolume`. + ```bash + $ docker volume ls + + DRIVER NAME + vieux/sshfs sshvolume + ``` + +5. Start a container that uses the volume `sshvolume`. ```bash $ docker run -v sshvolume:/data busybox ls /data @@ -92,30 +106,22 @@ started without error. ``` -5. Verify the plugin successfully created the volume. +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). - ```bash - $ docker volume ls +## Developing a plugin - DRIVER VOLUME NAME - vieux/sshfs sshvolume - ``` +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. - You can stop a plugin with the `docker plugin disable` - command or remove a plugin with `docker plugin remove`. +### Plugin location and files -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: +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. -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. +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. -To summarize, follow the steps below to create a plugin: +### Creating the 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 +Follow these steps to create a plugin: + +1. Choose a name for the plugin. Plugin name uses the same format as images, + for example: `/`. + +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 `/` 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. + +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 /` to push the plugin. + +The plugin can now be used by any user with access to your registry.