redirect_from:
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:
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.
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 and host networking.
Check for a value of true the ENABLED 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 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 for more information.
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/pluginsis 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:
<repo_name>/<name>./var/lib/docker/plugins/$id/rootfs./var/lib/docker/plugins/$id/.plugin-config.json if needed./var/lib/docker/plugins/plugins.json. Use <user>/<name> as “Name” and $id as “Id”.docker plugin ls.ENABLED=true, you can push it to the registry.ENABLED=false, something went wrong. Check the daemon logs for errors.docker login to authenticate against a registry.docker plugin push <repo_name>/<name> to push the plugin.