From 61317fa5572f16aa7b950b8d8d7cceca9e8171e1 Mon Sep 17 00:00:00 2001 From: Vitaliy Levitski Date: Mon, 23 Jan 2017 15:22:32 +0200 Subject: [PATCH] Add documentation for Manila MapRFS driver Change-Id: I098dd555a410a3aec2f0bc4ee51cefd42c9b498a --- .../source/shared-file-systems/drivers.rst | 1 + .../drivers/maprfs-native-driver.rst | 137 ++++++++++++++++++ .../source/tables/manila-maprfs.rst | 38 +++++ .../manila.flagmappings | 9 ++ .../manila.headers | 1 + 5 files changed, 186 insertions(+) create mode 100644 doc/config-reference/source/shared-file-systems/drivers/maprfs-native-driver.rst create mode 100644 doc/config-reference/source/tables/manila-maprfs.rst diff --git a/doc/config-reference/source/shared-file-systems/drivers.rst b/doc/config-reference/source/shared-file-systems/drivers.rst index 1c757b11d0..9d68e019c1 100644 --- a/doc/config-reference/source/shared-file-systems/drivers.rst +++ b/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 diff --git a/doc/config-reference/source/shared-file-systems/drivers/maprfs-native-driver.rst b/doc/config-reference/source/shared-file-systems/drivers/maprfs-native-driver.rst new file mode 100644 index 0000000000..5dcd9c2fcc --- /dev/null +++ b/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 `_. + +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 `_ + 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 `_ +for more information. diff --git a/doc/config-reference/source/tables/manila-maprfs.rst b/doc/config-reference/source/tables/manila-maprfs.rst new file mode 100644 index 0000000000..8d0b1d5d56 --- /dev/null +++ b/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. diff --git a/tools/autogenerate-config-flagmappings/manila.flagmappings b/tools/autogenerate-config-flagmappings/manila.flagmappings index 47866bbb5b..e1e0e53431 100644 --- a/tools/autogenerate-config-flagmappings/manila.flagmappings +++ b/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 diff --git a/tools/autogenerate-config-flagmappings/manila.headers b/tools/autogenerate-config-flagmappings/manila.headers index b3d0dd2443..01b327e103 100644 --- a/tools/autogenerate-config-flagmappings/manila.headers +++ b/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