github.com/walkingsparrow/docker@v1.4.2-0.20151218153551-b708a2249bfa/docs/extend/plugins_volume.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Volume plugins" 4 description = "How to manage data with external volume plugins" 5 keywords = ["Examples, Usage, volume, docker, data, volumes, plugin, api"] 6 [menu.main] 7 parent = "mn_extend" 8 +++ 9 <![end-metadata]--> 10 11 # Write a volume plugin 12 13 Docker volume plugins enable Docker deployments to be integrated with external 14 storage systems, such as Amazon EBS, and enable data volumes to persist beyond 15 the lifetime of a single Docker host. See the [plugin documentation](plugins.md) 16 for more information. 17 18 # Command-line changes 19 20 A volume plugin makes use of the `-v`and `--volume-driver` flag on the `docker run` command. The `-v` flag accepts a volume name and the `--volume-driver` flag a driver type, for example: 21 22 $ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh 23 24 This command passes the `volumename` through to the volume plugin as a 25 user-given name for the volume. The `volumename` must not begin with a `/`. 26 27 By having the user specify a `volumename`, a plugin can associate the volume 28 with an external volume beyond the lifetime of a single container or container 29 host. This can be used, for example, to move a stateful container from one 30 server to another. 31 32 By specifying a `volumedriver` in conjunction with a `volumename`, users can use plugins such as [Flocker](https://clusterhq.com/docker-plugin/) to manage volumes external to a single host, such as those on EBS. 33 34 35 # Create a VolumeDriver 36 37 The container creation endpoint (`/containers/create`) accepts a `VolumeDriver` 38 field of type `string` allowing to specify the name of the driver. It's default 39 value of `"local"` (the default driver for local volumes). 40 41 # Volume plugin protocol 42 43 If a plugin registers itself as a `VolumeDriver` when activated, then it is 44 expected to provide writeable paths on the host filesystem for the Docker 45 daemon to provide to containers to consume. 46 47 The Docker daemon handles bind-mounting the provided paths into user 48 containers. 49 50 ### /VolumeDriver.Create 51 52 **Request**: 53 ``` 54 { 55 "Name": "volume_name", 56 "Opts": {} 57 } 58 ``` 59 60 Instruct the plugin that the user wants to create a volume, given a user 61 specified volume name. The plugin does not need to actually manifest the 62 volume on the filesystem yet (until Mount is called). 63 Opts is a map of driver specific options passed through from the user request. 64 65 **Response**: 66 ``` 67 { 68 "Err": "" 69 } 70 ``` 71 72 Respond with a string error if an error occurred. 73 74 ### /VolumeDriver.Remove 75 76 **Request**: 77 ``` 78 { 79 "Name": "volume_name" 80 } 81 ``` 82 83 Delete the specified volume from disk. This request is issued when a user invokes `docker rm -v` to remove volumes associated with a container. 84 85 **Response**: 86 ``` 87 { 88 "Err": "" 89 } 90 ``` 91 92 Respond with a string error if an error occurred. 93 94 ### /VolumeDriver.Mount 95 96 **Request**: 97 ``` 98 { 99 "Name": "volume_name" 100 } 101 ``` 102 103 Docker requires the plugin to provide a volume, given a user specified volume 104 name. This is called once per container start. If the same volume_name is requested 105 more than once, the plugin may need to keep track of each new mount request and provision 106 at the first mount request and deprovision at the last corresponding unmount request. 107 108 **Response**: 109 ``` 110 { 111 "Mountpoint": "/path/to/directory/on/host", 112 "Err": "" 113 } 114 ``` 115 116 Respond with the path on the host filesystem where the volume has been made 117 available, and/or a string error if an error occurred. 118 119 ### /VolumeDriver.Path 120 121 **Request**: 122 ``` 123 { 124 "Name": "volume_name" 125 } 126 ``` 127 128 Docker needs reminding of the path to the volume on the host. 129 130 **Response**: 131 ``` 132 { 133 "Mountpoint": "/path/to/directory/on/host", 134 "Err": "" 135 } 136 ``` 137 138 Respond with the path on the host filesystem where the volume has been made 139 available, and/or a string error if an error occurred. 140 141 ### /VolumeDriver.Unmount 142 143 **Request**: 144 ``` 145 { 146 "Name": "volume_name" 147 } 148 ``` 149 150 Indication that Docker no longer is using the named volume. This is called once 151 per container stop. Plugin may deduce that it is safe to deprovision it at 152 this point. 153 154 **Response**: 155 ``` 156 { 157 "Err": "" 158 } 159 ``` 160 161 Respond with a string error if an error occurred. 162