github.com/olljanat/moby@v1.13.1/docs/extend/index.md (about) 1 --- 2 description: Develop and use a plugin with the managed plugin system 3 keywords: "API, Usage, plugins, documentation, developer" 4 title: Managed plugin system 5 --- 6 7 <!-- This file is maintained within the docker/docker Github 8 repository at https://github.com/docker/docker/. Make all 9 pull requests against that repo. If you see this file in 10 another repository, consider it read-only there, as it will 11 periodically be overwritten by the definitive file. Pull 12 requests which include edits to this file in other repositories 13 will be rejected. 14 --> 15 16 # Docker Engine managed plugin system 17 18 * [Installing and using a plugin](index.md#installing-and-using-a-plugin) 19 * [Developing a plugin](index.md#developing-a-plugin) 20 21 Docker Engine's plugins system allows you to install, start, stop, and remove 22 plugins using Docker Engine. This mechanism is currently only available for 23 volume drivers, but more plugin driver types will be available in future releases. 24 25 For information about the legacy plugin system available in Docker Engine 1.12 26 and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md). 27 28 > **Note**: Docker Engine managed plugins are currently not supported 29 on Windows daemons. 30 31 ## Installing and using a plugin 32 33 Plugins are distributed as Docker images and can be hosted on Docker Hub or on 34 a private registry. 35 36 To install a plugin, use the `docker plugin install` command, which pulls the 37 plugin from Docker hub or your private registry, prompts you to grant 38 permissions or capabilities if necessary, and enables the plugin. 39 40 To check the status of installed plugins, use the `docker plugin ls` command. 41 Plugins that start successfully are listed as enabled in the output. 42 43 After a plugin is installed, you can use it as an option for another Docker 44 operation, such as creating a volume. 45 46 In the following example, you install the `sshfs` plugin, verify that it is 47 enabled, and use it to create a volume. 48 49 1. Install the `sshfs` plugin. 50 51 ```bash 52 $ docker plugin install vieux/sshfs 53 54 Plugin "vieux/sshfs" is requesting the following privileges: 55 - network: [host] 56 - capabilities: [CAP_SYS_ADMIN] 57 Do you grant the above permissions? [y/N] y 58 59 vieux/sshfs 60 ``` 61 62 The plugin requests 2 privileges: 63 - It needs access to the `host` network. 64 - It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run 65 the `mount` command. 66 67 2. Check that the plugin is enabled in the output of `docker plugin ls`. 68 69 ```bash 70 $ docker plugin ls 71 72 ID NAME TAG DESCRIPTION ENABLED 73 69553ca1d789 vieux/sshfs latest the `sshfs` plugin true 74 ``` 75 76 3. Create a volume using the plugin. 77 This example mounts the `/remote` directory on host `1.2.3.4` into a 78 volume named `sshvolume`. This volume can now be mounted into containers. 79 80 ```bash 81 $ docker volume create \ 82 -d vieux/sshfs \ 83 --name sshvolume \ 84 -o sshcmd=user@1.2.3.4:/remote 85 86 sshvolume 87 ``` 88 4. Verify that the volume was created successfully. 89 90 ```bash 91 $ docker volume ls 92 93 DRIVER NAME 94 vieux/sshfs sshvolume 95 ``` 96 97 5. Start a container that uses the volume `sshvolume`. 98 99 ```bash 100 $ docker run -v sshvolume:/data busybox ls /data 101 102 <content of /remote on machine 1.2.3.4> 103 ``` 104 105 To disable a plugin, use the `docker plugin disable` command. To completely 106 remove it, use the `docker plugin remove` command. For other available 107 commands and options, see the 108 [command line reference](../reference/commandline/index.md). 109 110 ## Service creation using plugins 111 112 In swarm mode, it is possible to create a service that allows for attaching 113 to networks or mounting volumes. Swarm schedules services based on plugin availability 114 on a node. In this example, a volume plugin is installed on a swarm worker and a volume 115 is created using the plugin. In the manager, a service is created with the relevant 116 mount options. It can be observed that the service is scheduled to run on the worker 117 node with the said volume plugin and volume. 118 119 In the following example, node1 is the manager and node2 is the worker. 120 121 1. Prepare manager. In node 1: 122 123 ```bash 124 $ docker swarm init 125 Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager. 126 ``` 127 128 2. Join swarm, install plugin and create volume on worker. In node 2: 129 130 ```bash 131 $ docker swarm join \ 132 --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ 133 192.168.99.100:2377 134 ``` 135 136 ```bash 137 $ docker plugin install tiborvass/sample-volume-plugin 138 latest: Pulling from tiborvass/sample-volume-plugin 139 eb9c16fbdc53: Download complete 140 Digest: sha256:00b42de88f3a3e0342e7b35fa62394b0a9ceb54d37f4c50be5d3167899994639 141 Status: Downloaded newer image for tiborvass/sample-volume-plugin:latest 142 Installed plugin tiborvass/sample-volume-plugin 143 ``` 144 145 ```bash 146 $ docker volume create -d tiborvass/sample-volume-plugin --name pluginVol 147 ``` 148 149 3. Create a service using the plugin and volume. In node1: 150 151 ```bash 152 $ docker service create --name my-service --mount type=volume,volume-driver=tiborvass/sample-volume-plugin,source=pluginVol,destination=/tmp busybox top 153 154 $ docker service ls 155 z1sj8bb8jnfn my-service replicated 1/1 busybox:latest 156 ``` 157 docker service ls shows service 1 instance of service running. 158 159 4. Observe the task getting scheduled in node 2: 160 161 ```bash 162 $ docker ps --format '{{.ID}}\t {{.Status}} {{.Names}} {{.Command}}' 163 83fc1e842599 Up 2 days my-service.1.9jn59qzn7nbc3m0zt1hij12xs "top" 164 ``` 165 166 ## Developing a plugin 167 168 #### The rootfs directory 169 The `rootfs` directory represents the root filesystem of the plugin. In this 170 example, it was created from a Dockerfile: 171 172 >**Note:** The `/run/docker/plugins` directory is mandatory inside of the 173 plugin's filesystem for docker to communicate with the plugin. 174 175 ```bash 176 $ git clone https://github.com/vieux/docker-volume-sshfs 177 $ cd docker-volume-sshfs 178 $ docker build -t rootfsimage . 179 $ id=$(docker create rootfsimage true) # id was cd851ce43a403 when the image was created 180 $ sudo mkdir -p myplugin/rootfs 181 $ sudo docker export "$id" | sudo tar -x -C myplugin/rootfs 182 $ docker rm -vf "$id" 183 $ docker rmi rootfsimage 184 ``` 185 186 #### The config.json file 187 188 The `config.json` file describes the plugin. See the [plugins config reference](config.md). 189 190 Consider the following `config.json` file. 191 192 ```json 193 { 194 "description": "sshFS plugin for Docker", 195 "documentation": "https://docs.docker.com/engine/extend/plugins/", 196 "entrypoint": ["/go/bin/docker-volume-sshfs"], 197 "network": { 198 "type": "host" 199 }, 200 "interface" : { 201 "types": ["docker.volumedriver/1.0"], 202 "socket": "sshfs.sock" 203 }, 204 "capabilities": ["CAP_SYS_ADMIN"] 205 } 206 ``` 207 208 This plugin is a volume driver. It requires a `host` network and the 209 `CAP_SYS_ADMIN` capability. It depends upon the `/go/bin/docker-volume-sshfs` 210 entrypoint and uses the `/run/docker/plugins/sshfs.sock` socket to communicate 211 with Docker Engine. This plugin has no runtime parameters. 212 213 #### Creating the plugin 214 215 A new plugin can be created by running 216 `docker plugin create <plugin-name> ./path/to/plugin/data` where the plugin 217 data contains a plugin configuration file `config.json` and a root filesystem 218 in subdirectory `rootfs`. 219 220 After that the plugin `<plugin-name>` will show up in `docker plugin ls`. 221 Plugins can be pushed to remote registries with 222 `docker plugin push <plugin-name>`.