Add documentation for Manila MapRFS driver

Change-Id: I098dd555a410a3aec2f0bc4ee51cefd42c9b498a

doc/config-reference/source/shared-file-systems/drivers.rst

@@ -23,6 +23,7 @@ Share drivers
    drivers/hpe-3par-share-driver.rst
    drivers/huawei-nas-driver.rst
    drivers/ibm-gpfs-driver.rst
+   drivers/maprfs-native-driver.rst
    drivers/netapp-cluster-mode-driver.rst
    drivers/quobyte-driver.rst
 

doc/config-reference/source/shared-file-systems/drivers/maprfs-native-driver.rst

@@ -0,0 +1,137 @@
+====================
+MapRFS native driver
+====================
+
+MapR-FS native driver is a plug-in based on the Shared File Systems service
+and provides high-throughput access to the data on MapR-FS distributed file
+system, which is designed to hold very large amounts of data.
+
+A Shared File Systems service share in this driver is a volume in MapR-FS.
+Instances talk directly to the MapR-FS storage backend via the (mapr-posix)
+client. To mount a MapR-FS volume, the MapR POSIX client is required.
+Access to each share is allowed by user and group based access type, which is
+aligned with MapR-FS ACEs to support access control for multiple users and
+groups. If user name and group name are the same, the group access type will
+be used by default.
+
+For more details, see `MapR documentation <http://maprdocs.mapr.com/>`_.
+
+Network configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+The storage backend and Shared File Systems service hosts should be in a flat
+network. Otherwise, the L3 connectivity between them should exist.
+
+Supported shared filesystems and operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The driver supports MapR-FS shares.
+
+The following operations are supported:
+
+- Create MapR-FS share.
+- Delete MapR-FS share.
+- Allow MapR-FS Share access.
+
+  - Only support user and group access type.
+  - Support level of access (ro/rw).
+
+- Deny MapR-FS Share access.
+- Update MapR-FS Share access.
+- Create snapshot.
+- Delete snapshot.
+- Create share from snapshot.
+- Extend share.
+- Shrink share.
+- Manage share.
+- Unmanage share.
+- Manage snapshot.
+- Unmanage snapshot.
+- Ensure share.
+
+Requirements
+~~~~~~~~~~~~
+
+-  Install MapR core packages, version >= 5.2.x, on the storage backend.
+
+-  To enable snapshots, the MapR cluster should have at least M5 license.
+
+-  Establish network connection between the Shared File Systems service hosts
+   and storage backend.
+
+-  Obtain a `ticket <http://maprdocs.mapr.com/home/SecurityGuide/Tickets.html>`_
+   for user who will be used to access MapR-FS.
+
+Back end configuration (manila.conf)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add MapR-FS protocol to ``enabled_share_protocols``:
+
+.. code-block:: ini
+
+    enabled_share_protocols = MAPRFS
+
+Create a section for MapR-FS backend. Example:
+
+.. code-block:: ini
+
+    [maprfs]
+    driver_handles_share_servers = False
+    share_driver =
+    manila.share.drivers.maprfs.maprfs_native.MapRFSNativeShareDriver
+    maprfs_clinode_ip = example
+    maprfs_ssh_name = mapr
+    maprfs_ssh_pw = mapr
+    share_backend_name = maprfs
+
+Set ``driver-handles-share-servers`` to ``False`` as the driver does not
+manage the lifecycle of ``share-servers``.
+
+Add driver backend to ``enabled_share_backends``:
+
+.. code-block:: ini
+
+    enabled_share_backends = maprfs
+
+Driver options
+~~~~~~~~~~~~~~
+
+The following table contains the configuration options specific to this
+driver.
+
+.. include:: ../../tables/manila-maprfs.rst
+
+Known restrictions
+~~~~~~~~~~~~~~~~~~
+
+This driver does not handle user authentication, no tickets or users are
+created by this driver. This means that when 'access_allow' or
+'update_access' is calling, this will have no effect without providing
+tickets to users.
+
+
+Share metadata
+~~~~~~~~~~~~~~
+
+MapR-FS shares can be created by specifying additional options. Metadata is
+used for this purpose. Every metadata option with ``-`` prefix is passed to
+MapR-FS volume. For example, to specify advisory volume quota add
+``_advisoryquota=10G`` option to metadata:
+
+.. code-block:: console
+
+    $ manila create MAPRFS 1 --metadata _advisoryquota=10G
+
+If you need to create a share with your custom backend name or export location
+instead if uuid, you can specify ``_name`` and ``_path`` options:
+
+.. code-block:: console
+
+    $ manila create MAPRFS 1 --metadata _name=example _path=/example
+
+.. WARNING::
+   Specifying invalid options will cause an error.
+
+The list of allowed options depends on mapr-core version.
+See `volume create <http://maprdocs.mapr.com/home/ReferenceGuide/volume-create.html>`_
+for more information.

doc/config-reference/source/tables/manila-maprfs.rst

@@ -0,0 +1,38 @@
+..
+    Warning: Do not edit this file. It is automatically generated from the
+    software project's code and your changes will be overwritten.
+
+    The tool to generate this file lives in openstack-doc-tools repository.
+
+    Please make any changes needed in the code, then run the
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
+    ask for help on the documentation mailing list, IRC channel or meeting.
+
+.. _manila-maprfs:
+
+.. list-table:: Description of MapRFS Share Driver configuration options
+   :header-rows: 1
+   :class: config-ref-table
+
+   * - Configuration option = Default value
+     - Description
+   * - **[DEFAULT]**
+     -
+   * - ``maprfs_clinode_ip`` = ``None``
+     - (List) The list of IPs or hostnames of nodes with mapr-core installed.
+   * - ``maprfs_cldb_ip`` = ``None``
+     - (List) The list of IPs or hostnames of CLDB nodes.
+   * - ``maprfs_zookeeper_ip`` = ``None``
+     - (List) The list of IPs or hostnames of Zookeeper nodes.
+   * - ``maprfs_ssh_name`` = ``None``
+     - (String) Cluster admin user ssh login name.
+   * - ``maprfs_ssh_port`` = ``22``
+     - (Port number) SSH port.
+   * - ``maprfs_ssh_private_key`` = ``None``
+     - (String) Path to private key to ssh login.
+   * - ``maprfs_ssh_pw`` = ``None``
+     - (String) Cluster node SSH login password, this parameter is not necessary, if 'maprfs_ssh_private_key' is configured
+   * - ``maprfs_rename_managed_volume`` = ``True``
+     - (Boolean) Whether driver should rename share on manage operation.
+   * - ``maprfs_base_volume_dir`` = ``True``
+     - (String) Path to directory where volumes should be mounted.

tools/autogenerate-config-flagmappings/manila.flagmappings

@@ -143,6 +143,15 @@ lvm_share_mirrors lvm
 lvm_share_volume_group lvm
 manila_huawei_conf_file huawei
 manila_service_keypair_name generic
+maprfs_base_volume_dir maprfs
+maprfs_cldb_ip maprfs
+maprfs_clinode_ip maprfs
+maprfs_rename_managed_volume maprfs
+maprfs_ssh_name maprfs
+maprfs_ssh_port maprfs
+maprfs_ssh_private_key maprfs
+maprfs_ssh_pw maprfs
+maprfs_zookeeper_ip maprfs
 max_age quota
 max_gigabytes quota
 max_header_line api

tools/autogenerate-config-flagmappings/manila.headers

@@ -18,6 +18,7 @@ hpe3par HPE 3PAR Share Driver
 huawei Huawei Share Driver
 lvm LVM Share Driver
 logging Logging
+maprfs MapRFS Share Driver
 netapp NetApp Share Drivers
 qpid QPID
 quobyte Quobyte Share Driver