github.com/AliyunContainerService/cli@v0.0.0-20181009023821-814ced4b30d0/docs/extend/plugins_volume.md (about) 1 --- 2 description: "How to manage data with external volume plugins" 3 keywords: "Examples, Usage, volume, docker, data, volumes, plugin, api" 4 --- 5 6 <!-- This file is maintained within the docker/cli GitHub 7 repository at https://github.com/docker/cli/. Make all 8 pull requests against that repo. If you see this file in 9 another repository, consider it read-only there, as it will 10 periodically be overwritten by the definitive file. Pull 11 requests which include edits to this file in other repositories 12 will be rejected. 13 --> 14 15 # Docker volume plugins 16 17 Docker Engine volume plugins enable Engine deployments to be integrated with 18 external storage systems such as Amazon EBS, and enable data volumes to persist 19 beyond the lifetime of a single Docker host. See the 20 [plugin documentation](legacy_plugins.md) for more information. 21 22 ## Changelog 23 24 ### 1.13.0 25 26 - If used as part of the v2 plugin architecture, mountpoints that are part of 27 paths returned by the plugin must be mounted under the directory specified by 28 `PropagatedMount` in the plugin configuration 29 ([#26398](https://github.com/docker/docker/pull/26398)) 30 31 ### 1.12.0 32 33 - Add `Status` field to `VolumeDriver.Get` response 34 ([#21006](https://github.com/docker/docker/pull/21006#)) 35 - Add `VolumeDriver.Capabilities` to get capabilities of the volume driver 36 ([#22077](https://github.com/docker/docker/pull/22077)) 37 38 ### 1.10.0 39 40 - Add `VolumeDriver.Get` which gets the details about the volume 41 ([#16534](https://github.com/docker/docker/pull/16534)) 42 - Add `VolumeDriver.List` which lists all volumes owned by the driver 43 ([#16534](https://github.com/docker/docker/pull/16534)) 44 45 ### 1.8.0 46 47 - Initial support for volume driver plugins 48 ([#14659](https://github.com/docker/docker/pull/14659)) 49 50 ## Command-line changes 51 52 To give a container access to a volume, use the `--volume` and `--volume-driver` 53 flags on the `docker container run` command. The `--volume` (or `-v`) flag 54 accepts a volume name and path on the host, and the `--volume-driver` flag 55 accepts a driver type. 56 57 ```bash 58 $ docker volume create --driver=flocker volumename 59 60 $ docker container run -it --volume volumename:/data busybox sh 61 ``` 62 63 ### `--volume` 64 65 The `--volume` (or `-v`) flag takes a value that is in the format 66 `<volume_name>:<mountpoint>`. The two parts of the value are 67 separated by a colon (`:`) character. 68 69 - The volume name is a human-readable name for the volume, and cannot begin with 70 a `/` character. It is referred to as `volume_name` in the rest of this topic. 71 - The `Mountpoint` is the path on the host (v1) or in the plugin (v2) where the 72 volume has been made available. 73 74 ### `volumedriver` 75 76 Specifying a `volumedriver` in conjunction with a `volumename` allows you to 77 use plugins such as [Flocker](https://github.com/ScatterHQ/flocker) to manage 78 volumes external to a single host, such as those on EBS. 79 80 ## Create a VolumeDriver 81 82 The container creation endpoint (`/containers/create`) accepts a `VolumeDriver` 83 field of type `string` allowing to specify the name of the driver. If not 84 specified, it defaults to `"local"` (the default driver for local volumes). 85 86 ## Volume plugin protocol 87 88 If a plugin registers itself as a `VolumeDriver` when activated, it must 89 provide the Docker Daemon with writeable paths on the host filesystem. The Docker 90 daemon provides these paths to containers to consume. The Docker daemon makes 91 the volumes available by bind-mounting the provided paths into the containers. 92 93 > **Note**: Volume plugins should *not* write data to the `/var/lib/docker/` 94 > directory, including `/var/lib/docker/volumes`. The `/var/lib/docker/` 95 > directory is reserved for Docker. 96 97 ### `/VolumeDriver.Create` 98 99 **Request**: 100 ```json 101 { 102 "Name": "volume_name", 103 "Opts": {} 104 } 105 ``` 106 107 Instruct the plugin that the user wants to create a volume, given a user 108 specified volume name. The plugin does not need to actually manifest the 109 volume on the filesystem yet (until `Mount` is called). 110 `Opts` is a map of driver specific options passed through from the user request. 111 112 **Response**: 113 ```json 114 { 115 "Err": "" 116 } 117 ``` 118 119 Respond with a string error if an error occurred. 120 121 ### `/VolumeDriver.Remove` 122 123 **Request**: 124 ```json 125 { 126 "Name": "volume_name" 127 } 128 ``` 129 130 Delete the specified volume from disk. This request is issued when a user 131 invokes `docker rm -v` to remove volumes associated with a container. 132 133 **Response**: 134 ```json 135 { 136 "Err": "" 137 } 138 ``` 139 140 Respond with a string error if an error occurred. 141 142 ### `/VolumeDriver.Mount` 143 144 **Request**: 145 ```json 146 { 147 "Name": "volume_name", 148 "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" 149 } 150 ``` 151 152 Docker requires the plugin to provide a volume, given a user specified volume 153 name. `Mount` is called once per container start. If the same `volume_name` is requested 154 more than once, the plugin may need to keep track of each new mount request and provision 155 at the first mount request and deprovision at the last corresponding unmount request. 156 157 `ID` is a unique ID for the caller that is requesting the mount. 158 159 **Response**: 160 161 - **v1**: 162 163 ```json 164 { 165 "Mountpoint": "/path/to/directory/on/host", 166 "Err": "" 167 } 168 ``` 169 170 - **v2**: 171 172 ```json 173 { 174 "Mountpoint": "/path/under/PropagatedMount", 175 "Err": "" 176 } 177 ``` 178 179 `Mountpoint` is the path on the host (v1) or in the plugin (v2) where the volume 180 has been made available. 181 182 `Err` is either empty or contains an error string. 183 184 ### `/VolumeDriver.Path` 185 186 **Request**: 187 188 ```json 189 { 190 "Name": "volume_name" 191 } 192 ``` 193 194 Request the path to the volume with the given `volume_name`. 195 196 **Response**: 197 198 - **v1**: 199 200 ```json 201 { 202 "Mountpoint": "/path/to/directory/on/host", 203 "Err": "" 204 } 205 ``` 206 207 - **v2**: 208 209 ```json 210 { 211 "Mountpoint": "/path/under/PropagatedMount", 212 "Err": "" 213 } 214 ``` 215 216 Respond with the path on the host (v1) or inside the plugin (v2) where the 217 volume has been made available, and/or a string error if an error occurred. 218 219 `Mountpoint` is optional. However, the plugin may be queried again later if one 220 is not provided. 221 222 ### `/VolumeDriver.Unmount` 223 224 **Request**: 225 ```json 226 { 227 "Name": "volume_name", 228 "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" 229 } 230 ``` 231 232 Docker is no longer using the named volume. `Unmount` is called once per 233 container stop. Plugin may deduce that it is safe to deprovision the volume at 234 this point. 235 236 `ID` is a unique ID for the caller that is requesting the mount. 237 238 **Response**: 239 ```json 240 { 241 "Err": "" 242 } 243 ``` 244 245 Respond with a string error if an error occurred. 246 247 248 ### `/VolumeDriver.Get` 249 250 **Request**: 251 ```json 252 { 253 "Name": "volume_name" 254 } 255 ``` 256 257 Get info about `volume_name`. 258 259 260 **Response**: 261 262 - **v1**: 263 264 ```json 265 { 266 "Volume": { 267 "Name": "volume_name", 268 "Mountpoint": "/path/to/directory/on/host", 269 "Status": {} 270 }, 271 "Err": "" 272 } 273 ``` 274 275 - **v2**: 276 277 ```json 278 { 279 "Volume": { 280 "Name": "volume_name", 281 "Mountpoint": "/path/under/PropagatedMount", 282 "Status": {} 283 }, 284 "Err": "" 285 } 286 ``` 287 288 Respond with a string error if an error occurred. `Mountpoint` and `Status` are 289 optional. 290 291 292 ### /VolumeDriver.List 293 294 **Request**: 295 ```json 296 {} 297 ``` 298 299 Get the list of volumes registered with the plugin. 300 301 **Response**: 302 303 - **v1**: 304 305 ```json 306 { 307 "Volumes": [ 308 { 309 "Name": "volume_name", 310 "Mountpoint": "/path/to/directory/on/host" 311 } 312 ], 313 "Err": "" 314 } 315 ``` 316 317 - **v2**: 318 319 ```json 320 { 321 "Volumes": [ 322 { 323 "Name": "volume_name", 324 "Mountpoint": "/path/under/PropagatedMount" 325 } 326 ], 327 "Err": "" 328 } 329 ``` 330 331 332 Respond with a string error if an error occurred. `Mountpoint` is optional. 333 334 ### /VolumeDriver.Capabilities 335 336 **Request**: 337 ```json 338 {} 339 ``` 340 341 Get the list of capabilities the driver supports. 342 343 The driver is not required to implement `Capabilities`. If it is not 344 implemented, the default values are used. 345 346 **Response**: 347 ```json 348 { 349 "Capabilities": { 350 "Scope": "global" 351 } 352 } 353 ``` 354 355 Supported scopes are `global` and `local`. Any other value in `Scope` will be 356 ignored, and `local` is used. `Scope` allows cluster managers to handle the 357 volume in different ways. For instance, a scope of `global`, signals to the 358 cluster manager that it only needs to create the volume once instead of on each 359 Docker host. More capabilities may be added in the future.