github.com/a4a881d4/docker@v1.9.0-rc2/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": null
    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": null
    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.
   105  
   106  **Response**:
   107  ```
   108  {
   109      "Mountpoint": "/path/to/directory/on/host",
   110      "Err": null
   111  }
   112  ```
   113  
   114  Respond with the path on the host filesystem where the volume has been made
   115  available, and/or a string error if an error occurred.
   116  
   117  ### /VolumeDriver.Path
   118  
   119  **Request**:
   120  ```
   121  {
   122      "Name": "volume_name"
   123  }
   124  ```
   125  
   126  Docker needs reminding of the path to the volume on the host.
   127  
   128  **Response**:
   129  ```
   130  {
   131      "Mountpoint": "/path/to/directory/on/host",
   132      "Err": null
   133  }
   134  ```
   135  
   136  Respond with the path on the host filesystem where the volume has been made
   137  available, and/or a string error if an error occurred.
   138  
   139  ### /VolumeDriver.Unmount
   140  
   141  **Request**:
   142  ```
   143  {
   144      "Name": "volume_name"
   145  }
   146  ```
   147  
   148  Indication that Docker no longer is using the named volume. This is called once
   149  per container stop.  Plugin may deduce that it is safe to deprovision it at
   150  this point.
   151  
   152  **Response**:
   153  ```
   154  {
   155      "Err": null
   156  }
   157  ```
   158  
   159  Respond with a string error if an error occurred.
   160