External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-07-03 16:42:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

storage: document gluster pool

Browse Source 
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@redhat.com>
This commit is contained in:
Eric Blake 2013-10-15 17:06:18 -06:00
parent 318ea3cb77
commit ed5fa7f393
8 changed files with 168 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/formatstorage.html.in
View File

@ -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.2.0</span>). This corresponds to the
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

26
docs/schemas/storagepool.rng
View File

@ -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>

91
docs/storage.html.in
View File

@ -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.2.0</span>
</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>&lt;name&gt;</code> element is always the volume name
(no slash). The pool source also supports an
optional <code>&lt;dir&gt;</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>
&lt;pool type="gluster"&gt;
&lt;name&gt;myglusterpool&lt;/name&gt;
&lt;source&gt;
&lt;name&gt;volname&lt;/name&gt;
&lt;host name='localhost'/&gt;
&lt;dir path='/'/&gt;
&lt;/source&gt;
&lt;/pool&gt;</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>
&lt;volume&gt;
&lt;name&gt;myfile&lt;/name&gt;
&lt;key&gt;volname/myfile&lt;/key&gt;
&lt;source&gt;
&lt;/source&gt;
&lt;capacity unit='bytes'&gt;53687091200&lt;/capacity&gt;
&lt;allocation unit='bytes'&gt;53687091200&lt;/allocation&gt;
&lt;/volume&gt;</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>

9
tests/storagepoolxml2xmlin/pool-gluster-sub.xml Normal file
View File

@ -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>

8
tests/storagepoolxml2xmlin/pool-gluster.xml Normal file
View File

@ -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>

12
tests/storagepoolxml2xmlout/pool-gluster-sub.xml Normal file
View File

@ -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>

12
tests/storagepoolxml2xmlout/pool-gluster.xml Normal file
View File

@ -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>

2
tests/storagepoolxml2xmltest.c
View File

@ -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;
}