openstack-manuals/doc/config-reference/shared-file-systems/drivers/glusterfs-native-driver.xml

<section xml:id="glusterfs-native-driver" xmlns="http://docbook.org/ns/docbook"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
  <title>GlusterFS Native driver</title>
  <para>
    GlusterFS Native driver uses GlusterFS, an open source distributed
    file system, as the storage back end for serving file shares to
    Shared File Systems service clients.
  </para>
  <para>
    A Shared File Systems service share is a GlusterFS volume.
    This driver uses flat-network
    (share-server-less) model. Instances directly talk with the
    GlusterFS back end storage pool. The instances use 'glusterfs'
    protocol to mount the GlusterFS shares. Access to each share is
    allowed via TLS Certificates. Only the instance which has the TLS
    trust established with the GlusterFS back end can mount and hence use
    the share. Currently only 'rw' access is supported.
  </para>
  <simplesect>
    <title>Network approach</title>
    <para>
      L3 connectivity between the storage back end and the host running
      the Shared File Systems share service should exist.
    </para>
  </simplesect>
  <simplesect>
    <title>Supported shared filesystems</title>
    <itemizedlist>
      <listitem>
        <para>
          GlusterFS (access by TLS Certificates (<literal>cert</literal>
          access type))
        </para>
      </listitem>
    </itemizedlist>
  </simplesect>
  <simplesect>
    <title>Multi-tenancy model</title>
    <para>
      The driver does not support network segmented multi-tenancy model.
      Instead multi-tenancy is supported using tenant specific TLS
      certificates.
    </para>
  </simplesect>
  <simplesect>
    <title>Supported operations</title>
    <itemizedlist>
      <listitem>
        <para>
          Create GlusterFS share.
        </para>
      </listitem>
      <listitem>
        <para>
          Delete GlusterFS share.
        </para>
      </listitem>
      <listitem>
        <para>
          Allow GlusterFS share access (rw).
        </para>
      </listitem>
      <listitem>
        <para>
          Deny GlusterFS share access.
        </para>
      </listitem>
      <listitem>
        <para>
          Create GlusterFS snapshot.
        </para>
      </listitem>
      <listitem>
        <para>
          Delete GlusterFS snapshot.
        </para>
      </listitem>
    </itemizedlist>
  </simplesect>
  <simplesect>
    <title>Requirements</title>
    <itemizedlist>
      <listitem>
        <para>
          Install glusterfs-server package, version &gt;= 3.6.x, on the
          storage back end.
        </para>
      </listitem>
      <listitem>
        <para>
          Install glusterfs and glusterfs-fuse package, version
          &gt;=3.6.x, on the Shared File Systems service host.
        </para>
      </listitem>
      <listitem>
        <para>
          Establish network connection between the Shared File Systems
          service host and the storage back end.
        </para>
      </listitem>
    </itemizedlist>
  </simplesect>
  <simplesect>
    <title>Shared File Systems service driver configuration setting</title>
    <para>
      The following parameters in the Shared File Systems service's
      configuration file need to be
      set:
    </para>
    <itemizedlist>
      <listitem>
        <variablelist>
          <varlistentry>
            <term>
              share_driver =
            </term>
            <listitem>
              <para>
                manila.share.drivers.glusterfs_native.GlusterfsNativeShareDriver
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </listitem>
      <listitem>
        <variablelist>
          <varlistentry>
            <term>
              glusterfs_servers = List of GlusterFS servers which
              provide volumes
            </term>
            <listitem>
              <para>
                that can be used to create shares. The servers are
                expected to be of distinct Gluster clusters (ie. should
                not be gluster peers). Each server should be of the form
                <literal>[&lt;remoteuser&gt;@]&lt;glustervolserver&gt;</literal>.
              </para>
              <para>
                The optional <literal>&lt;remoteuser&gt;@</literal> part
                of the server URI indicates SSH access for cluster
                management (see related optional parameters below). If
                it is not given, direct command line management is
                performed (the Shared File Systems service host is
                assumed to be part of the
                GlusterFS cluster the server belongs to).
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </listitem>
      <listitem>
        <variablelist>
          <varlistentry>
            <term>
              glusterfs_volume_pattern = Regular expression template
            </term>
            <listitem>
              <para>
                used to filter GlusterFS volumes for share creation. The
                regex template can contain the #{size} parameter which
                matches a number (sequence of digits) and the value
                shall be interpreted as size of the volume in GB.
                Examples: <literal>manila-share-volume-\d+$</literal>,
                <literal>manila-share-volume-#{size}G-\d+$</literal>;
                with matching volume names, respectively:
                <emphasis>manila-share-volume-12</emphasis>,
                <emphasis>manila-share-volume-3G-13</emphasis>&quot;. In
                latter example, the number that matches
                <literal>#{size}</literal>, that is, 3, is an indication
                that the size of volume is 3G.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </listitem>
    </itemizedlist>
    <para>
      The following configuration parameters are optional:
    </para>
    <itemizedlist>
      <listitem>
        <variablelist>
          <varlistentry>
            <term>
              glusterfs_mount_point_base =
            </term>
            <listitem>
              <para>
                &lt;base path of GlusterFS
                volume mounted on the Shared File Systems service host&gt;
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </listitem>
      <listitem>
        <para>
          glusterfs_path_to_private_key = &lt;path to Shared File Systems
          service host's private key file&gt;
        </para>
      </listitem>
      <listitem>
        <para>
          glusterfs_server_password = &lt;password of remote GlusterFS
          server machine&gt;
        </para>
      </listitem>
    </itemizedlist>
  </simplesect>
  <simplesect>
    <title>Known restrictions</title>
    <itemizedlist>
      <listitem>
        <para>
          GlusterFS volumes are not created on demand. A pre-existing
          set of GlusterFS volumes should be supplied by the GlusterFS
          cluster(s), conforming to the naming convention encoded by
          <literal>glusterfs_volume_pattern</literal>. However, the
          GlusterFS endpoint is allowed to extend this set any time (so
          the Shared File Systems service and GlusterFS endpoints are
          expected to communicate
          volume supply/demand out-of-band).
          <literal>glusterfs_volume_pattern</literal> can include a size
          hint (with <literal>#{size}</literal> syntax), which, if
          present, requires the GlusterFS end to indicate the size of
          the shares in GB in the name. (On share creation, the
          Shared File Systems service picks
          volumes <emphasis>at least</emphasis> as big as the requested
          one.)
        </para>
      </listitem>
      <listitem>
        <para>
          Certificate setup (also known as trust setup) between instance and
          storage back end is out of band of the Shared File Systems service.
        </para>
      </listitem>
      <listitem>
        <para>
          Support for 'create_share_from_snapshot' is planned for
          Liberty release.
        </para>
      </listitem>
      <listitem>
        <para>
          For the Shared File Systems service to use GlusterFS volumes,
          the name of the trashcan
          directory in GlusterFS volumes must not be changed from the
          default.
        </para>
      </listitem>
    </itemizedlist>
  </simplesect>
  <!--
  <simplesect>
    <title>Driver options</title>
    <para>The following table contains the configation options specific to this driver.</para>
    <xi:include href="../../../common/tables/manila-glusterfs.xml"/>
  </simplesect>
  -->
  <simplesect>
        <title>Driver configuration options</title>
        <para>
            Configuration options specific to this driver are documented here:
            <xref linkend="config_table_manila_glusterfs"/>.
        </para>
  </simplesect>
</section>