From ab0ed8b667a8af400965bcc046b3d583831eaed5 Mon Sep 17 00:00:00 2001

Message-Id: <ab0ed8b667a8af400965bcc046b3d583831eaed5@dist-git>

From: Eric Blake <eblake@redhat.com>

Date: Wed, 26 Feb 2014 14:54:22 +0100

Subject: [PATCH] storage: document gluster pool

https://bugzilla.redhat.com/show_bug.cgi?id=1032370

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>

(cherry picked from commit ed5fa7f39399080b0aeb5a657fc71b75019edbe9)

Signed-off-by: Jiri Denemark <jdenemar@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 2bb29b1..015de1e 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 72c4fd6..d1e8f36 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>

@@ -125,6 +126,17 @@

     <ref name='sourcesheepdog'/>

   </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'>

     <optional>

       <element name='vendor'>

@@ -277,7 +289,7 @@

   <define name='sourceinfodir'>

     <element name='dir'>

       <attribute name='path'>

-        <ref name='absFilePath'/>

+        <ref name='absDirPath'/>

       </attribute>

       <empty/>

     </element>

@@ -506,6 +518,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..6a32c95 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.

+    

+

   </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 c75480b..9c25f2f 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;

 }

-- 

1.9.0