Signed-off-by: lixiaobing10051267 <li.xiaobing1@zte.com.cn>
7.5 KiB
aliases | title | description | keywords | advisory | ||
---|---|---|---|---|---|---|
|
Managed plugin system | How develop and use a plugin with the managed plugin system |
|
experimental |
Docker Engine managed plugin system
This document describes the plugin system available today in the experimental build of Docker 1.12:
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.
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.
-
Install the
sshfs
plugin.$ 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 andhost networking
. -
Check for a value of
true
theENABLED
column to verify the plugin started without error.$ docker plugin ls NAME TAG ENABLED vieux/sshfs latest true
-
Create a volume using the plugin.
$ docker volume create \ -d vieux/sshfs \ --name sshvolume \ -o sshcmd=user@1.2.3.4:/remote sshvolume
-
Use the volume
sshvolume
.$ docker run -v sshvolume:/data busybox ls /data <content of /remote on machine 1.2.3.4>
-
Verify the plugin successfully created the volume.
$ docker volume ls DRIVER VOLUME NAME vieux/sshfs sshvolume
You can stop a plugin with the
docker plugin disable
command or remove a plugin withdocker plugin remove
.
See the command line reference 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:
# 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:
# 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",
"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:
# 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._
$ 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. See the Plugins Manifest reference. For example:
# cat manifest.json
{
"manifestVersion": "v0",
"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.
# 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:
- Choose a name for the plugin. Plugin name uses the same format as images,
for example:
<repo_name>/<name>
. - Create a rootfs in
/var/lib/docker/plugins/$id/rootfs
. - Create manifest.json file in
/var/lib/docker/plugins/$id/
. - Create a
plugin-config.json
if needed. - Create or add a section to
/var/lib/docker/plugins/plugins.json
. Use<user>/<name>
as “Name” and$id
as “Id”. - Restart the Docker Engine.
- 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.
- If your plugin is listed as
- If you are not already logged in, use
docker login
to authenticate against a registry. - Run
docker plugin push <repo_name>/<name>
to push the plugin.