From ed5fa7f39399080b0aeb5a657fc71b75019edbe9 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Tue, 15 Oct 2013 17:06:18 -0600 Subject: [PATCH] storage: document gluster pool Add support for a new , 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 --- docs/formatstorage.html.in | 15 ++- docs/schemas/storagepool.rng | 26 +++++- docs/storage.html.in | 91 ++++++++++++++++++- .../storagepoolxml2xmlin/pool-gluster-sub.xml | 9 ++ tests/storagepoolxml2xmlin/pool-gluster.xml | 8 ++ .../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 c90d7b1baa..17c0313c66 100644 --- a/docs/formatstorage.html.in +++ b/docs/formatstorage.html.in @@ -21,8 +21,10 @@ iscsi, logical, scsi (all since 0.4.1), mpath (since 0.7.1), rbd - (since 0.9.13), or sheepdog - (since 0.10.0). This corresponds to the + (since 0.9.13), sheepdog + (since 0.10.0), + or gluster (since + 1.2.0). This corresponds to the storage backend drivers listed further along in this document.

General metadata

@@ -101,7 +103,9 @@ path to the block device node. Since 0.4.1
dir
Provides the source for pools backed by directories (pool - type dir). May + type dir), or optionally to select a subdirectory + within a pool that resembles a filesystem (pool + type gluster). May only occur once. Contains a single attribute path which is the fully qualified path to the backing directory. Since 0.4.1
@@ -129,7 +133,7 @@
host
Provides the source for pools backed by storage from a remote server (pool types netfs, iscsi, - rbd, sheepdog). Will be + rbd, sheepdog, gluster). Will be used in combination with a directory or device element. Contains an attribute name which is the hostname or IP address of the server. May optionally @@ -160,7 +164,8 @@
name
Provides the source for pools backed by storage from a named element (pool types logical, rbd, - sheepdog). Contains a string identifier. + sheepdog, gluster). Contains a + string identifier. Since 0.4.5
format
Provides information about the format of the pool (pool diff --git a/docs/schemas/storagepool.rng b/docs/schemas/storagepool.rng index 61fa7a3eb3..8d7a94d656 100644 --- a/docs/schemas/storagepool.rng +++ b/docs/schemas/storagepool.rng @@ -21,6 +21,7 @@ + @@ -145,6 +146,17 @@ + + + gluster + + + + + + + + @@ -309,7 +321,7 @@ - + @@ -554,6 +566,18 @@ + + + + + + + + + + + + iqn\.[0-9]{4}-(0[1-9]|1[0-2])\.[a-zA-Z0-9\.\-]+(:.+)? diff --git a/docs/storage.html.in b/docs/storage.html.in index 0464565adb..6a32c95e89 100644 --- a/docs/storage.html.in +++ b/docs/storage.html.in @@ -114,6 +114,9 @@
  • Sheepdog backend
    • +
  • + Gluster backend +

    • Directory pool

    @@ -280,7 +283,9 @@ glusterfs - use the glusterfs FUSE file system. For now, the dir 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 gluster pool.)
  • cifs - use the SMB (samba) or CIFS file system @@ -652,5 +657,89 @@ The Sheepdog pool does not use the volume format type element.

    +

    Gluster pools

    +

    + 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 netfs + 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 gluster + volume set $volname storage.owner-uid=$uid + and gluster volume set $volname + storage.owner-gid=$gid for the uid and gid that qemu will + be run as. It may also be necessary to + set rpc-auth-allow-insecure on for the glusterd + service, as well as gluster set $volname + server.allow-insecure on, to allow access to the gluster + volume. + + Since 1.2.0 +

    + +

    Example pool input

    +

    A gluster volume corresponds to a libvirt storage pool. If a + gluster volume could be mounted as mount -t glusterfs + localhost:/volname /some/path, 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 host designation. + The <name> element is always the volume name + (no slash). The pool source also supports an + optional <dir> element with + a path 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.

    + 
    +      <pool type="gluster">
+        <name>myglusterpool</name>
+        <source>
+          <name>volname</name>
+          <host name='localhost'/>
+          <dir path='/'/>
+        </source>
+      </pool>
    + +

    Example volume output

    +

    Libvirt storage volumes associated with a gluster pool + correspond to the files that can be found when mounting the + gluster volume. The name is the path relative to + the effective mount specified for the pool; and + the key is a path including the gluster volume + name and any subdirectory specified by the pool.

    + 
    +       <volume>
+         <name>myfile</name>
+         <key>volname/myfile</key>
+         <source>
+         </source>
+         <capacity unit='bytes'>53687091200</capacity>
+         <allocation unit='bytes'>53687091200</allocation>
+       </volume>
    + +

    Example disk attachment

    +

    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 format domain + page.

    + +

    Valid pool format types

    +

    + The Gluster pool does not use the pool format type element. +

    + +

    Valid volume format types

    +

    + The valid volume types are the same as for the directory + pool type. +

    + diff --git a/tests/storagepoolxml2xmlin/pool-gluster-sub.xml b/tests/storagepoolxml2xmlin/pool-gluster-sub.xml new file mode 100644 index 0000000000..ba4458fbd3 --- /dev/null +++ b/tests/storagepoolxml2xmlin/pool-gluster-sub.xml @@ -0,0 +1,9 @@ + + + volume + + + + mygluster + 65fcba04-5b13-bd93-cff3-52ce48e11ad8 + diff --git a/tests/storagepoolxml2xmlin/pool-gluster.xml b/tests/storagepoolxml2xmlin/pool-gluster.xml new file mode 100644 index 0000000000..ae9401fdc7 --- /dev/null +++ b/tests/storagepoolxml2xmlin/pool-gluster.xml @@ -0,0 +1,8 @@ + + + volume + + + mygluster + 65fcba04-5b13-bd93-cff3-52ce48e11ad8 + diff --git a/tests/storagepoolxml2xmlout/pool-gluster-sub.xml b/tests/storagepoolxml2xmlout/pool-gluster-sub.xml new file mode 100644 index 0000000000..df7d719b15 --- /dev/null +++ b/tests/storagepoolxml2xmlout/pool-gluster-sub.xml @@ -0,0 +1,12 @@ + + mygluster + 65fcba04-5b13-bd93-cff3-52ce48e11ad8 + 0 + 0 + 0 + + + + volume + + diff --git a/tests/storagepoolxml2xmlout/pool-gluster.xml b/tests/storagepoolxml2xmlout/pool-gluster.xml new file mode 100644 index 0000000000..a7fa5068f4 --- /dev/null +++ b/tests/storagepoolxml2xmlout/pool-gluster.xml @@ -0,0 +1,12 @@ + + mygluster + 65fcba04-5b13-bd93-cff3-52ce48e11ad8 + 0 + 0 + 0 + + + + volume + + diff --git a/tests/storagepoolxml2xmltest.c b/tests/storagepoolxml2xmltest.c index a81cf99704..039d515cba 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; } -- GitLab