1berry/docker-cli
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rewrites to Developing Plugins topic

Browse Source 
Signed-off-by: Misty Stanley-Jones <misty@docker.com>
This commit is contained in:
Misty Stanley-Jones 2016-10-20 11:12:02 -07:00 committed by Tibor Vass
parent 7f36c3a1a0
commit 7ec82562ce
1 changed files with 122 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
docs/extend/index.md
View File

@ -1,11 +1,11 @@
--- ---
aliases: [ advisory: experimental
"/engine/extend/" aliases:
] - /engine/extend/
title: "Managed plugin system" description: Develop and use a plugin with the managed plugin system
description: "How develop and use a plugin with the managed plugin system" keywords:
keywords: ["API, Usage, plugins, documentation, developer"] - API, Usage, plugins, documentation, developer
advisory: "experimental" title: Managed plugin system
--- ---
<!-- This file is maintained within the docker/docker Github <!-- This file is maintained within the docker/docker Github
@ -22,39 +22,33 @@ advisory: "experimental"
This document describes the plugin system available today in the **experimental This document describes the plugin system available today in the **experimental
build** of Docker 1.12: build** of Docker 1.12:
* [How to operate an existing plugin](#how-to-operate-a-plugin) * [Installing and using a plugin](index.md#installing-and-using-a-plugin)
* [How to develop a plugin](#how-to-develop-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 For information about the legacy plugin system available in Docker Engine 1.12
* start plugins and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md).
* stop plugins
* remove plugins
The current Docker Engine plugin system only supports volume drivers. We are ## Installing and using a plugin
adding more plugin driver types in the future releases.
For information on Docker Engine plugins generally available in Docker Engine Plugins are distributed as Docker images and can be hosted on Docker Hub or on
1.12 and earlier, refer to [Understand legacy Docker Engine plugins](legacy_plugins.md). 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 To check the status of installed plugins, use the `docker plugin ls` command.
Hub or on a private registry. Plugins that start successfully are listed as enabled in the output.
You install the plugin using a single command: `docker plugin install <PLUGIN>`. After a plugin is installed, you can use it as an option for another Docker
The `plugin install` command pulls the plugin from the Docker Hub or private operation, such as creating a volume.
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.
Run `docker plugin ls` to check the status of installed plugins. The Engine In the following example, you install the `sshfs` plugin, verify that it is
markes plugins that are started without issues as `ENABLED`. enabled, and use it to create 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.
1. Install the `sshfs` plugin. 1. Install the `sshfs` plugin.
@ -69,11 +63,12 @@ to create a volume.
vieux/sshfs vieux/sshfs
``` ```
The plugin requests 2 privileges, the `CAP_SYS_ADMIN` capability to be able The plugin requests 2 privileges:
to do mount inside the plugin and `host networking`. - 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 2. Check that the plugin is enabled in the output of `docker plugin ls`.
started without error.
```bash ```bash
$ docker plugin ls $ docker plugin ls
@ -83,6 +78,8 @@ started without error.
``` ```
3. Create a volume using the plugin. 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 ```bash
$ docker volume create \ $ docker volume create \
@ -92,8 +89,16 @@ started without error.
sshvolume 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 ```bash
$ docker run -v sshvolume:/data busybox ls /data $ docker run -v sshvolume:/data busybox ls /data
@ -101,30 +106,22 @@ started without error.
<content of /remote on machine 1.2.3.4> <content of /remote on machine 1.2.3.4>
``` ```
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 ## Developing a plugin
$ docker volume ls
DRIVER VOLUME NAME Currently, there are no CLI commands available to help you develop a plugin.
vieux/sshfs sshvolume 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` ### Plugin location and files
command or remove a plugin with `docker plugin remove`.
See the [command line reference](../reference/commandline/index.md) for more Plugins are stored in `/var/lib/docker/plugins`. The `plugins.json` file lists
information. each plugin's configuration, and each plugin is stored in a directory with a
unique identifier.
## 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 ```bash
# ls -la /var/lib/docker/plugins # ls -la /var/lib/docker/plugins
@ -135,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 -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 # cat plugins.json
{ {
"cd851ce43a403": { "cd851ce43a403": {
@ -188,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 ```bash
# ls -la /var/lib/docker/plugins/cd851ce43a403 # ls -la /var/lib/docker/plugins/cd851ce43a403
@ -198,28 +201,34 @@ drwx------ 19 root root 4096 Aug 8 17:56 rootfs
-rw------- 1 root root 347 Aug 8 17:56 manifest.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 #### The rootfs directory
created from a Dockerfile as follows: 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 >**Note:** The `/run/docker/plugins` directory is mandatory for docker to communicate with
the plugin._ the plugin.
```bash ```bash
$ git clone https://github.com/vieux/docker-volume-sshfs $ git clone https://github.com/vieux/docker-volume-sshfs
$ cd docker-volume-sshfs $ cd docker-volume-sshfs
$ docker build -t rootfs . $ docker build -t rootfs .
$ id=$(docker create rootfs true) # id was cd851ce43a403 when the image was created $ id=$(docker create rootfs true) # id was cd851ce43a403 when the image was created
$ mkdir -p /var/lib/docker/plugins/$id/rootfs $ sudo mkdir -p /var/lib/docker/plugins/$id/rootfs
$ docker export "$id" | tar -x -C /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 rm -vf "$id"
$ docker rmi rootfs $ docker rmi rootfs
``` ```
`manifest.json` describes the plugin and `plugin-config.json` contains some #### The manifest.json and plugin-config.json files
runtime parameters. [See the Plugins Manifest reference](manifest.md). For example:
```bash The `manifest.json` file describes the plugin. The `plugin-config.json` file
# cat manifest.json 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", "manifestVersion": "v0",
"description": "sshFS plugin for Docker", "description": "sshFS plugin for Docker",
@ -236,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 This plugin is a volume driver. It requires a `host` network and the
`CAP_SYS_ADMIN` capability, `host networking`, `/go/bin/docker-volume-sshfs` as `CAP_SYS_ADMIN` capability. It depends upon the `/go/bin/docker-volume-sshfs`
entrypoint and is going to use `/run/docker/plugins/sshfs.sock` to communicate entrypoint and uses the `/run/docker/plugins/sshfs.sock` socket to communicate
with the Docker Engine. with Docker Engine.
```bash
# cat plugin-config.json Consider the following `plugin-config.json` file.
```json
{ {
"Devices": null, "Devices": null,
"Args": null, "Args": null,
@ -251,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`. Each of these JSON files is included as part of `plugins.json`, as you can see
`manifest.json` is read-only and `plugin-config.json` is read-write. 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, Follow these steps to create a plugin:
for example: `<repo_name>/<name>`.
1. Create a rootfs in `/var/lib/docker/plugins/$id/rootfs`. 1. Choose a name for the plugin. Plugin name uses the same format as images,
2. Create manifest.json file in `/var/lib/docker/plugins/$id/`. for example: `<repo_name>/<name>`.
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”. `<user>/<name>` as “Name” and `$id` as “Id”.
5. Restart the Docker Engine.
6. Run `docker plugin ls`. 6. Restart the Docker Engine service.
* If your plugin is listed as `ENABLED=true`, you can push it to the
7. Run `docker plugin ls`.
* If your plugin is enabled, you can push it to the
registry. registry.
* If the plugin is not listed or if `ENABLED=false`, something went wrong. * If the plugin is not listed or is disabled, something went wrong.
Check the daemon logs for errors. Check the daemon logs for errors.
7. If you are not already logged in, use `docker login` to authenticate against
a registry. 8. If you are not already logged in, use `docker login` to authenticate against
8. Run `docker plugin push <repo_name>/<name>` to push the plugin. 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.