diff options
Diffstat (limited to 'devdocs/docker/engine%2Fextend%2Fplugins_volume%2Findex.html')
| -rw-r--r-- | devdocs/docker/engine%2Fextend%2Fplugins_volume%2Findex.html | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/devdocs/docker/engine%2Fextend%2Fplugins_volume%2Findex.html b/devdocs/docker/engine%2Fextend%2Fplugins_volume%2Findex.html new file mode 100644 index 00000000..14319e18 --- /dev/null +++ b/devdocs/docker/engine%2Fextend%2Fplugins_volume%2Findex.html @@ -0,0 +1,98 @@ + <h1 id="docker-volume-plugins">Docker volume plugins</h1> <p>Docker Engine volume plugins enable Engine deployments to be integrated with external storage systems such as Amazon EBS, and enable data volumes to persist beyond the lifetime of a single Docker host. See the <a href="../legacy_plugins/index">plugin documentation</a> for more information.</p> <h2 id="changelog">Changelog</h2> <h3 id="1130">1.13.0</h3> <ul> <li>If used as part of the v2 plugin architecture, mountpoints that are part of paths returned by the plugin must be mounted under the directory specified by <code class="language-plaintext highlighter-rouge">PropagatedMount</code> in the plugin configuration (<a href="https://github.com/docker/docker/pull/26398">#26398</a>)</li> </ul> <h3 id="1120">1.12.0</h3> <ul> <li>Add <code class="language-plaintext highlighter-rouge">Status</code> field to <code class="language-plaintext highlighter-rouge">VolumeDriver.Get</code> response (<a href="https://github.com/docker/docker/pull/21006#">#21006</a>)</li> <li>Add <code class="language-plaintext highlighter-rouge">VolumeDriver.Capabilities</code> to get capabilities of the volume driver (<a href="https://github.com/docker/docker/pull/22077">#22077</a>)</li> </ul> <h3 id="1100">1.10.0</h3> <ul> <li>Add <code class="language-plaintext highlighter-rouge">VolumeDriver.Get</code> which gets the details about the volume (<a href="https://github.com/docker/docker/pull/16534">#16534</a>)</li> <li>Add <code class="language-plaintext highlighter-rouge">VolumeDriver.List</code> which lists all volumes owned by the driver (<a href="https://github.com/docker/docker/pull/16534">#16534</a>)</li> </ul> <h3 id="180">1.8.0</h3> <ul> <li>Initial support for volume driver plugins (<a href="https://github.com/docker/docker/pull/14659">#14659</a>)</li> </ul> <h2 id="command-line-changes">Command-line changes</h2> <p>To give a container access to a volume, use the <code class="language-plaintext highlighter-rouge">--volume</code> and <code class="language-plaintext highlighter-rouge">--volume-driver</code> flags on the <code class="language-plaintext highlighter-rouge">docker container run</code> command. The <code class="language-plaintext highlighter-rouge">--volume</code> (or <code class="language-plaintext highlighter-rouge">-v</code>) flag accepts a volume name and path on the host, and the <code class="language-plaintext highlighter-rouge">--volume-driver</code> flag accepts a driver type.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker volume create --driver=flocker volumename + +$ docker container run -it --volume volumename:/data busybox sh +</pre></div> <h3 id="--volume"><code class="language-plaintext highlighter-rouge">--volume</code></h3> <p>The <code class="language-plaintext highlighter-rouge">--volume</code> (or <code class="language-plaintext highlighter-rouge">-v</code>) flag takes a value that is in the format <code class="language-plaintext highlighter-rouge"><volume_name>:<mountpoint></code>. The two parts of the value are separated by a colon (<code class="language-plaintext highlighter-rouge">:</code>) character.</p> <ul> <li>The volume name is a human-readable name for the volume, and cannot begin with a <code class="language-plaintext highlighter-rouge">/</code> character. It is referred to as <code class="language-plaintext highlighter-rouge">volume_name</code> in the rest of this topic.</li> <li>The <code class="language-plaintext highlighter-rouge">Mountpoint</code> is the path on the host (v1) or in the plugin (v2) where the volume has been made available.</li> </ul> <h3 id="volumedriver"><code class="language-plaintext highlighter-rouge">volumedriver</code></h3> <p>Specifying a <code class="language-plaintext highlighter-rouge">volumedriver</code> in conjunction with a <code class="language-plaintext highlighter-rouge">volumename</code> allows you to use plugins such as <a href="https://github.com/ScatterHQ/flocker">Flocker</a> to manage volumes external to a single host, such as those on EBS.</p> <h2 id="create-a-volumedriver">Create a VolumeDriver</h2> <p>The container creation endpoint (<code class="language-plaintext highlighter-rouge">/containers/create</code>) accepts a <code class="language-plaintext highlighter-rouge">VolumeDriver</code> field of type <code class="language-plaintext highlighter-rouge">string</code> allowing to specify the name of the driver. If not specified, it defaults to <code class="language-plaintext highlighter-rouge">"local"</code> (the default driver for local volumes).</p> <h2 id="volume-plugin-protocol">Volume plugin protocol</h2> <p>If a plugin registers itself as a <code class="language-plaintext highlighter-rouge">VolumeDriver</code> when activated, it must provide the Docker Daemon with writeable paths on the host filesystem. The Docker daemon provides these paths to containers to consume. The Docker daemon makes the volumes available by bind-mounting the provided paths into the containers.</p> <blockquote> <p><strong>Note</strong></p> <p>Volume plugins should <em>not</em> write data to the <code class="language-plaintext highlighter-rouge">/var/lib/docker/</code> directory, including <code class="language-plaintext highlighter-rouge">/var/lib/docker/volumes</code>. The <code class="language-plaintext highlighter-rouge">/var/lib/docker/</code> directory is reserved for Docker.</p> </blockquote> <h3 id="volumedrivercreate"><code class="language-plaintext highlighter-rouge">/VolumeDriver.Create</code></h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Name": "volume_name", + "Opts": {} +} +</pre></div> <p>Instruct the plugin that the user wants to create a volume, given a user specified volume name. The plugin does not need to actually manifest the volume on the filesystem yet (until <code class="language-plaintext highlighter-rouge">Mount</code> is called). <code class="language-plaintext highlighter-rouge">Opts</code> is a map of driver specific options passed through from the user request.</p> <p><strong>Response</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Err": "" +} +</pre></div> <p>Respond with a string error if an error occurred.</p> <h3 id="volumedriverremove"><code class="language-plaintext highlighter-rouge">/VolumeDriver.Remove</code></h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Name": "volume_name" +} +</pre></div> <p>Delete the specified volume from disk. This request is issued when a user invokes <code class="language-plaintext highlighter-rouge">docker rm -v</code> to remove volumes associated with a container.</p> <p><strong>Response</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Err": "" +} +</pre></div> <p>Respond with a string error if an error occurred.</p> <h3 id="volumedrivermount"><code class="language-plaintext highlighter-rouge">/VolumeDriver.Mount</code></h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Name": "volume_name", + "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" +} +</pre></div> <p>Docker requires the plugin to provide a volume, given a user specified volume name. <code class="language-plaintext highlighter-rouge">Mount</code> is called once per container start. If the same <code class="language-plaintext highlighter-rouge">volume_name</code> is requested more than once, the plugin may need to keep track of each new mount request and provision at the first mount request and deprovision at the last corresponding unmount request.</p> <p><code class="language-plaintext highlighter-rouge">ID</code> is a unique ID for the caller that is requesting the mount.</p> <p><strong>Response</strong>:</p> <ul> <li> <p><strong>v1</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Mountpoint": "/path/to/directory/on/host", + "Err": "" +} +</pre></div> </li> <li> <p><strong>v2</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Mountpoint": "/path/under/PropagatedMount", + "Err": "" +} +</pre></div> </li> </ul> <p><code class="language-plaintext highlighter-rouge">Mountpoint</code> is the path on the host (v1) or in the plugin (v2) where the volume has been made available.</p> <p><code class="language-plaintext highlighter-rouge">Err</code> is either empty or contains an error string.</p> <h3 id="volumedriverpath"><code class="language-plaintext highlighter-rouge">/VolumeDriver.Path</code></h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Name": "volume_name" +} +</pre></div> <p>Request the path to the volume with the given <code class="language-plaintext highlighter-rouge">volume_name</code>.</p> <p><strong>Response</strong>:</p> <ul> <li> <p><strong>v1</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Mountpoint": "/path/to/directory/on/host", + "Err": "" +} +</pre></div> </li> <li> <p><strong>v2</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Mountpoint": "/path/under/PropagatedMount", + "Err": "" +} +</pre></div> </li> </ul> <p>Respond with the path on the host (v1) or inside the plugin (v2) where the volume has been made available, and/or a string error if an error occurred.</p> <p><code class="language-plaintext highlighter-rouge">Mountpoint</code> is optional. However, the plugin may be queried again later if one is not provided.</p> <h3 id="volumedriverunmount"><code class="language-plaintext highlighter-rouge">/VolumeDriver.Unmount</code></h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Name": "volume_name", + "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c" +} +</pre></div> <p>Docker is no longer using the named volume. <code class="language-plaintext highlighter-rouge">Unmount</code> is called once per container stop. Plugin may deduce that it is safe to deprovision the volume at this point.</p> <p><code class="language-plaintext highlighter-rouge">ID</code> is a unique ID for the caller that is requesting the mount.</p> <p><strong>Response</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Err": "" +} +</pre></div> <p>Respond with a string error if an error occurred.</p> <h3 id="volumedriverget"><code class="language-plaintext highlighter-rouge">/VolumeDriver.Get</code></h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Name": "volume_name" +} +</pre></div> <p>Get info about <code class="language-plaintext highlighter-rouge">volume_name</code>.</p> <p><strong>Response</strong>:</p> <ul> <li> <p><strong>v1</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Volume": { + "Name": "volume_name", + "Mountpoint": "/path/to/directory/on/host", + "Status": {} + }, + "Err": "" +} +</pre></div> </li> <li> <p><strong>v2</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Volume": { + "Name": "volume_name", + "Mountpoint": "/path/under/PropagatedMount", + "Status": {} + }, + "Err": "" +} +</pre></div> </li> </ul> <p>Respond with a string error if an error occurred. <code class="language-plaintext highlighter-rouge">Mountpoint</code> and <code class="language-plaintext highlighter-rouge">Status</code> are optional.</p> <h3 id="volumedriverlist">/VolumeDriver.List</h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{} +</pre></div> <p>Get the list of volumes registered with the plugin.</p> <p><strong>Response</strong>:</p> <ul> <li> <p><strong>v1</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Volumes": [ + { + "Name": "volume_name", + "Mountpoint": "/path/to/directory/on/host" + } + ], + "Err": "" +} +</pre></div> </li> <li> <p><strong>v2</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Volumes": [ + { + "Name": "volume_name", + "Mountpoint": "/path/under/PropagatedMount" + } + ], + "Err": "" +} +</pre></div> </li> </ul> <p>Respond with a string error if an error occurred. <code class="language-plaintext highlighter-rouge">Mountpoint</code> is optional.</p> <h3 id="volumedrivercapabilities">/VolumeDriver.Capabilities</h3> <p><strong>Request</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{} +</pre></div> <p>Get the list of capabilities the driver supports.</p> <p>The driver is not required to implement <code class="language-plaintext highlighter-rouge">Capabilities</code>. If it is not implemented, the default values are used.</p> <p><strong>Response</strong>:</p> <div class="highlight"><pre class="highlight" data-language="">{ + "Capabilities": { + "Scope": "global" + } +} +</pre></div> <p>Supported scopes are <code class="language-plaintext highlighter-rouge">global</code> and <code class="language-plaintext highlighter-rouge">local</code>. Any other value in <code class="language-plaintext highlighter-rouge">Scope</code> will be ignored, and <code class="language-plaintext highlighter-rouge">local</code> is used. <code class="language-plaintext highlighter-rouge">Scope</code> allows cluster managers to handle the volume in different ways. For instance, a scope of <code class="language-plaintext highlighter-rouge">global</code>, signals to the cluster manager that it only needs to create the volume once instead of on each Docker host. More capabilities may be added in the future.</p> +<p><a href="https://docs.docker.com/search/?q=Examples">Examples</a>, <a href="https://docs.docker.com/search/?q=Usage">Usage</a>, <a href="https://docs.docker.com/search/?q=volume">volume</a>, <a href="https://docs.docker.com/search/?q=docker">docker</a>, <a href="https://docs.docker.com/search/?q=data">data</a>, <a href="https://docs.docker.com/search/?q=volumes">volumes</a>, <a href="https://docs.docker.com/search/?q=plugin">plugin</a>, <a href="https://docs.docker.com/search/?q=api">api</a></p> +<div class="_attribution"> + <p class="_attribution-p"> + © 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br> + <a href="https://docs.docker.com/engine/extend/plugins_volume/" class="_attribution-link">https://docs.docker.com/engine/extend/plugins_volume/</a> + </p> +</div> |