[libvirt] [PATCHv4 2/8] storage: document gluster pool
Daniel Veillard
veillard at redhat.com
Mon Nov 25 06:12:26 UTC 2013
On Fri, Nov 22, 2013 at 08:20:24PM -0700, Eric Blake wrote:
> Add support for a new <pool type='gluster'>, similar to
> RBD and Sheepdog. Terminology wise, a gluster volume
> forms a libvirt storage pool, within the gluster volume,
> individual files are treated as libvirt storage volumes.
>
> * docs/schemas/storagepool.rng (poolgluster): New pool type.
> * docs/formatstorage.html.in: Document gluster.
> * docs/storage.html.in: Likewise, and contrast it with netfs.
> * tests/storagepoolxml2xmlin/pool-gluster.xml: New test.
> * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise.
> * tests/storagepoolxml2xmltest.c (mymain): Likewise.
>
> Signed-off-by: Eric Blake <eblake at redhat.com>
> ---
> docs/formatstorage.html.in | 15 ++--
> docs/schemas/storagepool.rng | 26 ++++++-
> docs/storage.html.in | 91 +++++++++++++++++++++++-
> tests/storagepoolxml2xmlin/pool-gluster-sub.xml | 9 +++
> tests/storagepoolxml2xmlin/pool-gluster.xml | 8 +++
> tests/storagepoolxml2xmlout/pool-gluster-sub.xml | 12 ++++
> tests/storagepoolxml2xmlout/pool-gluster.xml | 12 ++++
> tests/storagepoolxml2xmltest.c | 2 +
> 8 files changed, 168 insertions(+), 7 deletions(-)
> create mode 100644 tests/storagepoolxml2xmlin/pool-gluster-sub.xml
> create mode 100644 tests/storagepoolxml2xmlin/pool-gluster.xml
> create mode 100644 tests/storagepoolxml2xmlout/pool-gluster-sub.xml
> create mode 100644 tests/storagepoolxml2xmlout/pool-gluster.xml
>
> diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in
> index 5f277b4..a7f3b57 100644
> --- a/docs/formatstorage.html.in
> +++ b/docs/formatstorage.html.in
> @@ -21,8 +21,10 @@
> <code>iscsi</code>, <code>logical</code>, <code>scsi</code>
> (all <span class="since">since 0.4.1</span>), <code>mpath</code>
> (<span class="since">since 0.7.1</span>), <code>rbd</code>
> - (<span class="since">since 0.9.13</span>), or <code>sheepdog</code>
> - (<span class="since">since 0.10.0</span>). This corresponds to the
> + (<span class="since">since 0.9.13</span>), <code>sheepdog</code>
> + (<span class="since">since 0.10.0</span>),
> + or <code>gluster</code> (<span class="since">since
> + 1.1.5</span>). This corresponds to the
well 1.1.5 will become 1.2.0 actually so just change the 2 occurences
> storage backend drivers listed further along in this document.
> </p>
> <h3><a name="StoragePoolFirst">General metadata</a></h3>
> @@ -101,7 +103,9 @@
> path to the block device node. <span class="since">Since 0.4.1</span></dd>
> <dt><code>dir</code></dt>
> <dd>Provides the source for pools backed by directories (pool
> - type <code>dir</code>). May
> + type <code>dir</code>), or optionally to select a subdirectory
> + within a pool that resembles a filesystem (pool
> + type <code>gluster</code>). May
> only occur once. Contains a single attribute <code>path</code>
> which is the fully qualified path to the backing directory.
> <span class="since">Since 0.4.1</span></dd>
> @@ -129,7 +133,7 @@
> <dt><code>host</code></dt>
> <dd>Provides the source for pools backed by storage from a
> remote server (pool types <code>netfs</code>, <code>iscsi</code>,
> - <code>rbd</code>, <code>sheepdog</code>). Will be
> + <code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
> used in combination with a <code>directory</code>
> or <code>device</code> element. Contains an attribute <code>name</code>
> which is the hostname or IP address of the server. May optionally
> @@ -160,7 +164,8 @@
> <dt><code>name</code></dt>
> <dd>Provides the source for pools backed by storage from a
> named element (pool types <code>logical</code>, <code>rbd</code>,
> - <code>sheepdog</code>). Contains a string identifier.
> + <code>sheepdog</code>, <code>gluster</code>). Contains a
> + string identifier.
> <span class="since">Since 0.4.5</span></dd>
> <dt><code>format</code></dt>
> <dd>Provides information about the format of the pool (pool
> diff --git a/docs/schemas/storagepool.rng b/docs/schemas/storagepool.rng
> index 61fa7a3..8d7a94d 100644
> --- a/docs/schemas/storagepool.rng
> +++ b/docs/schemas/storagepool.rng
> @@ -21,6 +21,7 @@
> <ref name='poolmpath'/>
> <ref name='poolrbd'/>
> <ref name='poolsheepdog'/>
> + <ref name='poolgluster'/>
> </choice>
> </element>
> </define>
> @@ -145,6 +146,17 @@
> </interleave>
> </define>
>
> + <define name='poolgluster'>
> + <attribute name='type'>
> + <value>gluster</value>
> + </attribute>
> + <interleave>
> + <ref name='commonmetadata'/>
> + <ref name='sizing'/>
> + <ref name='sourcegluster'/>
> + </interleave>
> + </define>
> +
> <define name='sourceinfovendor'>
> <interleave>
> <optional>
> @@ -309,7 +321,7 @@
> <define name='sourceinfodir'>
> <element name='dir'>
> <attribute name='path'>
> - <ref name='absFilePath'/>
> + <ref name='absDirPath'/>
> </attribute>
> <empty/>
> </element>
> @@ -554,6 +566,18 @@
> </element>
> </define>
>
> + <define name='sourcegluster'>
> + <element name='source'>
> + <interleave>
> + <ref name='sourceinfohost'/>
> + <ref name='sourceinfoname'/>
> + <optional>
> + <ref name='sourceinfodir'/>
> + </optional>
> + </interleave>
> + </element>
> + </define>
> +
> <define name='IscsiQualifiedName'>
> <data type='string'>
> <param name="pattern">iqn\.[0-9]{4}-(0[1-9]|1[0-2])\.[a-zA-Z0-9\.\-]+(:.+)?</param>
> diff --git a/docs/storage.html.in b/docs/storage.html.in
> index 0464565..9465b83 100644
> --- a/docs/storage.html.in
> +++ b/docs/storage.html.in
> @@ -114,6 +114,9 @@
> <li>
> <a href="#StorageBackendSheepdog">Sheepdog backend</a>
> </li>
> + <li>
> + <a href="#StorageBackendGluster">Gluster backend</a>
> + </li>
> </ul>
>
> <h2><a name="StorageBackendDir">Directory pool</a></h2>
> @@ -280,7 +283,9 @@
> <code>glusterfs</code> - use the glusterfs FUSE file system.
> For now, the <code>dir</code> specified as the source can only
> be a gluster volume name, as gluster does not provide a way to
> - directly mount subdirectories within a volume.
> + directly mount subdirectories within a volume. (To bypass the
> + file system completely, see
> + the <a href="#StorageBackendGluster">gluster</a> pool.)
> </li>
> <li>
> <code>cifs</code> - use the SMB (samba) or CIFS file system
> @@ -652,5 +657,89 @@
> The Sheepdog pool does not use the volume format type element.
> </p>
>
> + <h2><a name="StorageBackendGluster">Gluster pools</a></h2>
> + <p>
> + This provides a pool based on native Gluster access. Gluster is
> + a distributed file system that can be exposed to the user via
> + FUSE, NFS or SMB (see the <a href="#StorageBackendNetfs">netfs</a>
> + pool for that usage); but for minimal overhead, the ideal access
> + is via native access (only possible for QEMU/KVM compiled with
> + libgfapi support).
> +
> + The cluster and storage volume must already be running, and it
> + is recommended that the volume be configured with <code>gluster
> + volume set $volname storage.owner-uid=$uid</code>
> + and <code>gluster volume set $volname
> + storage.owner-gid=$gid</code> for the uid and gid that qemu will
> + be run as. It may also be necessary to
> + set <code>rpc-auth-allow-insecure on</code> for the glusterd
> + service, as well as <code>gluster set $volname
> + server.allow-insecure on</code>, to allow access to the gluster
> + volume.
> +
> + <span class="since">Since 1.1.5</span>
1.2.0
> + </p>
> +
> + <h3>Example pool input</h3>
> + <p>A gluster volume corresponds to a libvirt storage pool. If a
> + gluster volume could be mounted as <code>mount -t glusterfs
> + localhost:/volname /some/path</code>, then the following example
> + will describe the same pool without having to create a local
> + mount point. Remember that with gluster, the mount point can be
> + through any machine in the cluster, and gluster will
> + automatically pick the ideal transport to the actual bricks
> + backing the gluster volume, even if on a different host than the
> + one named in the <code>host</code> designation.
> + The <code><name></code> element is always the volume name
> + (no slash). The pool source also supports an
> + optional <code><dir></code> element with
> + a <code>path</code> attribute that lists the absolute name of a
> + subdirectory relative to the gluster volume to use instead of
> + the top-level directory of the volume.</p>
> + <pre>
> + <pool type="gluster">
> + <name>myglusterpool</name>
> + <source>
> + <name>volname</name>
> + <host name='localhost'/>
> + <dir path='/'/>
> + </source>
> + </pool></pre>
> +
> + <h3>Example volume output</h3>
> + <p>Libvirt storage volumes associated with a gluster pool
> + correspond to the files that can be found when mounting the
> + gluster volume. The <code>name</code> is the path relative to
> + the effective mount specified for the pool; and
> + the <code>key</code> is a path including the gluster volume
> + name and any subdirectory specified by the pool.</p>
> + <pre>
> + <volume>
> + <name>myfile</name>
> + <key>volname/myfile</key>
> + <source>
> + </source>
> + <capacity unit='bytes'>53687091200</capacity>
> + <allocation unit='bytes'>53687091200</allocation>
> + </volume></pre>
> +
> + <h3>Example disk attachment</h3>
> + <p>Files within a gluster volume can be attached to Qemu guests.
> + Information about attaching a Gluster image to a
> + guest can be found
> + at the <a href="formatdomain.html#elementsDisks">format domain</a>
> + page.</p>
> +
> + <h3>Valid pool format types</h3>
> + <p>
> + The Gluster pool does not use the pool format type element.
> + </p>
> +
> + <h3>Valid volume format types</h3>
> + <p>
> + The valid volume types are the same as for the <code>directory</code>
> + pool type.
> + </p>
> +
> </body>
> </html>
> diff --git a/tests/storagepoolxml2xmlin/pool-gluster-sub.xml b/tests/storagepoolxml2xmlin/pool-gluster-sub.xml
> new file mode 100644
> index 0000000..ba4458f
> --- /dev/null
> +++ b/tests/storagepoolxml2xmlin/pool-gluster-sub.xml
> @@ -0,0 +1,9 @@
> +<pool type='gluster'>
> + <source>
> + <name>volume</name>
> + <dir path='/sub'/>
> + <host name='localhost'/>
> + </source>
> + <name>mygluster</name>
> + <uuid>65fcba04-5b13-bd93-cff3-52ce48e11ad8</uuid>
> +</pool>
> diff --git a/tests/storagepoolxml2xmlin/pool-gluster.xml b/tests/storagepoolxml2xmlin/pool-gluster.xml
> new file mode 100644
> index 0000000..ae9401f
> --- /dev/null
> +++ b/tests/storagepoolxml2xmlin/pool-gluster.xml
> @@ -0,0 +1,8 @@
> +<pool type='gluster'>
> + <source>
> + <name>volume</name>
> + <host name='localhost'/>
> + </source>
> + <name>mygluster</name>
> + <uuid>65fcba04-5b13-bd93-cff3-52ce48e11ad8</uuid>
> +</pool>
> diff --git a/tests/storagepoolxml2xmlout/pool-gluster-sub.xml b/tests/storagepoolxml2xmlout/pool-gluster-sub.xml
> new file mode 100644
> index 0000000..df7d719
> --- /dev/null
> +++ b/tests/storagepoolxml2xmlout/pool-gluster-sub.xml
> @@ -0,0 +1,12 @@
> +<pool type='gluster'>
> + <name>mygluster</name>
> + <uuid>65fcba04-5b13-bd93-cff3-52ce48e11ad8</uuid>
> + <capacity unit='bytes'>0</capacity>
> + <allocation unit='bytes'>0</allocation>
> + <available unit='bytes'>0</available>
> + <source>
> + <host name='localhost'/>
> + <dir path='/sub'/>
> + <name>volume</name>
> + </source>
> +</pool>
> diff --git a/tests/storagepoolxml2xmlout/pool-gluster.xml b/tests/storagepoolxml2xmlout/pool-gluster.xml
> new file mode 100644
> index 0000000..a7fa506
> --- /dev/null
> +++ b/tests/storagepoolxml2xmlout/pool-gluster.xml
> @@ -0,0 +1,12 @@
> +<pool type='gluster'>
> + <name>mygluster</name>
> + <uuid>65fcba04-5b13-bd93-cff3-52ce48e11ad8</uuid>
> + <capacity unit='bytes'>0</capacity>
> + <allocation unit='bytes'>0</allocation>
> + <available unit='bytes'>0</available>
> + <source>
> + <host name='localhost'/>
> + <dir path='/'/>
> + <name>volume</name>
> + </source>
> +</pool>
> diff --git a/tests/storagepoolxml2xmltest.c b/tests/storagepoolxml2xmltest.c
> index a81cf99..039d515 100644
> --- a/tests/storagepoolxml2xmltest.c
> +++ b/tests/storagepoolxml2xmltest.c
> @@ -102,6 +102,8 @@ mymain(void)
> DO_TEST("pool-iscsi-multiiqn");
> DO_TEST("pool-iscsi-vendor-product");
> DO_TEST("pool-sheepdog");
> + DO_TEST("pool-gluster");
> + DO_TEST("pool-gluster-sub");
>
> return ret==0 ? EXIT_SUCCESS : EXIT_FAILURE;
> }
That patch set got a lot of review already (though it seems to have
increased slighty since v3), but i would love to get it in 1.2.0.
Since Peter and Dan fully reviewed it last round, and assuming you
handled all comments back, I suggest to push before tomorrow freeze :-)
ACK,
Daniel
--
Daniel Veillard | Open Source and Standards, Red Hat
veillard at redhat.com | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
http://veillard.com/ | virtualization library http://libvirt.org/
More information about the libvir-list
mailing list