beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 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
parent ffa0446e8b
commit b39e65e937
1 changed files with 131 additions and 95 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

226
docs/extend/index.md
View file

@ -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
---
<!-- 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.
-->
# 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 <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.
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.
<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
$ 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: `<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
Follow these steps to create a plugin:
1. Choose a name for the plugin. Plugin name uses the same format as images,
for example: `<repo_name>/<name>`.
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.