Merge "Update Spectrum Scale (GPFS) share driver doc"

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

@@ -24,7 +24,7 @@ Share drivers
    drivers/hitachi-hsp-driver.rst
    drivers/hpe-3par-share-driver.rst
    drivers/huawei-nas-driver.rst
-   drivers/ibm-gpfs-driver.rst
+   drivers/ibm-spectrumscale-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/ibm-gpfs-driver.rst

@@ -1,108 +0,0 @@
-===============
-IBM GPFS driver
-===============
-
-The GPFS driver uses IBM General Parallel File System (GPFS), a
-high-performance, clustered file system, developed by IBM, as the
-storage back end for serving file shares to the Shared File Systems
-service clients.
-
-Supported shared filesystems and operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The driver supports NFS shares.
-
-The following operations are supported:
-
-- Create a share.
-
-- Delete a share.
-
-- Allow share access.
-
-  Note the following limitations:
-
-  - Only IP access type is supported.
-
-  - Only read-write access level is supported.
-
-- Deny share access.
-
-- Create a snapshot.
-
-- Delete a snapshot.
-
-- Create a share from a snapshot.
-
-Requirements
-~~~~~~~~~~~~
-
--  Install GPFS with server license, version >= 2.0, on the storage back
-   end.
-
--  Install Kernel NFS or Ganesha NFS server on the storage back-end
-   servers.
-
--  If using Ganesha NFS, currently NFS Ganesha v1.5 and v2.0 are
-   supported.
-
--  Create a GPFS cluster and create a filesystem on the cluster, that
-   will be used to create the Shared File Systems service shares.
-
--  Enable quotas for the GPFS file system, use :command:`mmchfs -Q yes`.
-
--  Establish network connection between the Shared File Systems service
-   host and the storage back end.
-
-Shared File Systems service driver configuration setting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following parameters in the Shared File Systems service
-configuration file need to be set:
-
-.. code-block:: ini
-
-   share_driver = manila.share.drivers.ibm.gpfs.GPFSShareDriver
-   gpfs_share_export_ip = <IP to be added to GPFS export string>
-
-If the back-end GPFS server is not running on the Shared File Systems
-service host machine, the following options are required to SSH to
-the remote GPFS back-end server:
-
-.. code-block:: ini
-
-   gpfs_ssh_login = <GPFS server SSH login name>
-
-Also one of the following settings is required to execute commands
-over SSH:
-
-.. code-block:: ini
-
-   gpfs_ssh_private_key = <path to GPFS server SSH private key for login>
-
-or:
-
-.. code-block:: ini
-
-   gpfs_ssh_password = <GPFS server SSH login password>
-
-
-Known restrictions
-~~~~~~~~~~~~~~~~~~
-
--  The driver does not support a segmented-network multi-tenancy model
-   but instead works over a flat network where the tenants share a
-   network.
-
--  While using remote GPFS node, with Ganesha NFS,
-   ``gpfs_ssh_private_key`` for remote login to the GPFS node must be
-   specified and there must be a passwordless authentication already
-   setup between the ``manila-share`` service and the remote GPFS node.
-
-Driver options
-~~~~~~~~~~~~~~
-
-The following table contains the configuration options specific to the
-share driver.
-
-.. include:: ../../tables/manila-gpfs.rst

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

@@ -0,0 +1,177 @@
+===============================
+IBM Spectrum Scale share driver
+===============================
+
+IBM Spectrum Scale is a flexible software-defined storage product that can be
+deployed as high-performance file storage or a cost optimized
+large-scale content repository. IBM Spectrum Scale, previously known as
+IBM General Parallel File System (GPFS), is designed to scale performance
+and capacity with no bottlenecks. IBM Spectrum Scale is a cluster file system
+that provides concurrent access to file systems from multiple nodes. The
+storage provided by these nodes can be direct attached, network attached, SAN
+attached, or a combination of these methods. Spectrum Scale provides many
+features beyond common data access, including data replication, policy based
+storage management, and space efficient file snapshot and clone operations.
+
+Supported shared filesystems and operations (NFS shares only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Spectrum Scale share driver supports NFS shares.
+
+The following operations are supported:
+
+- Create a share.
+
+- Delete a share.
+
+- Allow share access.
+
+  - Only IP access type is supported.
+
+  - Both RW & RO access level is supported.
+
+- Deny share access.
+
+- Create a share snapshot.
+
+- Delete a share snapshot.
+
+- Create a share from a snapshot.
+
+- Extend a share.
+
+- Manage a share.
+
+- Unmanage a share.
+
+Requirements
+~~~~~~~~~~~~
+
+Spectrum Scale must be installed and a cluster must be created that includes
+one or more storage nodes and protocol server nodes. The NFS server
+running on these nodes is used to export shares to storage consumers in
+OpenStack virtual machines or even to bare metal storage consumers in the
+OpenStack environment. A file system must also be created and
+mounted on these nodes before configuring the manila service to use Spectrum
+Scale storage. For more details, refer to `Spectrum Scale product
+documentation <https://ibm.biz/Bdi84g>`_.
+
+Spectrum Scale supports two ways of exporting data through NFS with high
+availability.
+
+#. CES (which uses Ganesha NFS)
+
+   * This is provided inherently by the protocol support in Spectrum Scale
+     and is a recommended method for NFS access.
+
+#. CNFS (which uses kernel NFS)
+
+For more information on NFS support in Spectrum Scale, refer to
+`Protocol support in Spectrum Scale <https://ibm.biz/BdiuZN>`_ and
+`NFS Support overview in Spectrum Scale <https://ibm.biz/BdiuZ7>`_.
+
+The following figure is an example of Spectrum Scale architecture
+with OpenStack services:
+
+.. figure:: ../../figures/openstack-spectrumscale-setup.JPG
+   :width: 90%
+   :align: center
+   :alt: OpenStack with Spectrum Scale Setup
+
+Quotas should be enabled for the Spectrum Scale filesystem to be exported
+through NFS using Spectrum Scale share driver.
+Use the following command to enable quota for a filesystem:
+
+.. code-block:: console
+
+   $ mmchfs <filesystem> -Q yes
+
+Limitation
+~~~~~~~~~~
+
+Spectrum Scale share driver currently supports creation of NFS shares in the
+flat network space only. For example, the Spectrum Scale storage node exporting
+the data should be in the same network as that of the Compute VMs which mount
+the shares acting as NFS clients.
+
+Driver configuration
+~~~~~~~~~~~~~~~~~~~~
+
+Spectrum Scale share driver supports creation of shares using both NFS servers
+(Ganesha using Spectrum Scale CES/Kernel NFS).
+
+For both the NFS server types, you need to set the ``share_driver`` in the
+``manila.conf`` as:
+
+.. code-block:: ini
+
+   share_driver = manila.share.drivers.ibm.gpfs.GPFSShareDriver
+
+Spectrum Scale CES (NFS Ganesha server)
+---------------------------------------
+
+To use Spectrum Scale share driver in this mode, set the ``gpfs_share_helpers``
+in the ``manila.conf`` as:
+
+.. code-block:: ini
+
+   gpfs_share_helpers = CES=manila.share.drivers.ibm.gpfs.CESHelper
+
+Following table lists the additional configuration options which are used with
+this driver configuration.
+
+.. include:: ../../tables/manila-spectrumscale_ces.rst
+
+.. note::
+
+    Configuration options related to ssh are required only if ``is_gpfs_node``
+    is set to ``False``.
+
+Spectrum Scale Clustered NFS (Kernel NFS server)
+------------------------------------------------
+
+To use Spectrum Scale share driver in this mode, set the ``gpfs_share_helpers``
+in the ``manila.conf`` as:
+
+.. code-block:: ini
+
+   gpfs_share_helpers = KNFS=manila.share.drivers.ibm.gpfs.KNFSHelper
+
+Following table lists the additional configuration options which are used with
+this driver configuration.
+
+.. include:: ../../tables/manila-spectrumscale_knfs.rst
+
+.. note::
+
+    Configuration options related to ssh are required only if ``is_gpfs_node``
+    is set to ``False``.
+
+Share creation steps
+~~~~~~~~~~~~~~~~~~~~
+
+Sample configuration
+--------------------
+
+.. code-block:: ini
+
+    [gpfs]
+    share_driver = manila.share.drivers.ibm.gpfs.GPFSShareDriver
+    gpfs_share_export_ip = x.x.x.x
+    gpfs_mount_point_base = /ibm/gpfs0
+    gpfs_nfs_server_type = CES
+    is_gpfs_node = True
+    gpfs_share_helpers = CES=manila.share.drivers.ibm.gpfs.CESHelper
+    share_backend_name = GPFS
+    driver_handles_share_servers = False
+
+
+Create GPFS share type and set extra spec
+-----------------------------------------
+
+.. code-block:: ini
+
+   $ manila type-create --snapshot_support True \
+     --create_share_from_snapshot_support True gpfs False
+
+   $ manila type-key gpfs set share_backend_name=GPFS

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

@@ -0,0 +1,57 @@
+..
+    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-spectrumscale_ces:
+
+.. list-table:: Description of IBM Spectrum Scale CES share driver configuration options
+   :header-rows: 1
+   :class: config-ref-table
+
+   * - Configuration option = Default value
+     - Description
+
+   * - **[DEFAULT]**
+     -
+
+   * - ``gpfs_mount_point_base`` = ``$state_path/mnt``
+
+     - (String) Base folder where exported shares are located.
+
+   * - ``gpfs_nfs_server_type`` = ``CES``
+
+     - (String) NFS Server type. Valid choices are "CES" (Ganesha NFS) or "KNFS" (Kernel NFS).
+
+   * - ``gpfs_share_export_ip`` = ``None``
+
+     - (Host address) IP to be added to GPFS export string.
+
+   * - ``gpfs_share_helpers`` = ``KNFS=manila.share.drivers.ibm.gpfs.KNFSHelper, CES=manila.share.drivers.ibm.gpfs.CESHelper``
+
+     - (List) Specify list of share export helpers.
+
+   * - ``gpfs_ssh_login`` = ``None``
+
+     - (String) GPFS server SSH login name.
+
+   * - ``gpfs_ssh_password`` = ``None``
+
+     - (String) GPFS server SSH login password. The password is not needed, if 'gpfs_ssh_private_key' is configured.
+
+   * - ``gpfs_ssh_port`` = ``22``
+
+     - (Port number) GPFS server SSH port.
+
+   * - ``gpfs_ssh_private_key`` = ``None``
+
+     - (String) Path to GPFS server SSH private key for login.
+
+   * - ``is_gpfs_node`` = ``False``
+
+     - (Boolean) True:when Manila services are running on one of the Spectrum Scale node. False:when Manila services are not running on any of the Spectrum Scale node.

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

@@ -8,35 +8,54 @@
     autogenerate-config-doc tool from the openstack-doc-tools repository, or
     ask for help on the documentation mailing list, IRC channel or meeting.
 
-.. _manila-gpfs:
+.. _manila-spectrumscale_knfs:
 
-.. list-table:: Description of IBM GPFS share driver configuration options
+.. list-table:: Description of IBM Spectrum Scale KNFS share driver configuration options
    :header-rows: 1
    :class: config-ref-table
 
    * - Configuration option = Default value
      - Description
+
    * - **[DEFAULT]**
      -
+
    * - ``gpfs_mount_point_base`` = ``$state_path/mnt``
+
      - (String) Base folder where exported shares are located.
+
    * - ``gpfs_nfs_server_list`` = ``None``
+
      - (List) A list of the fully qualified NFS server names that make up the OpenStack Manila configuration.
-   * - ``gpfs_nfs_server_type`` = ``KNFS``
+
-     - (String) NFS Server type. Valid choices are "KNFS" (kernel NFS) or "CES" (Ganesha NFS).
+   * - ``gpfs_nfs_server_type`` = ``CES``
+
+     - (String) NFS Server type. Valid choices are "CES" (Ganesha NFS) or "KNFS" (Kernel NFS).
+
    * - ``gpfs_share_export_ip`` = ``None``
-     - (String) IP to be added to GPFS export string.
+
+     - (Host address) IP to be added to GPFS export string.
+
    * - ``gpfs_share_helpers`` = ``KNFS=manila.share.drivers.ibm.gpfs.KNFSHelper, CES=manila.share.drivers.ibm.gpfs.CESHelper``
+
      - (List) Specify list of share export helpers.
+
    * - ``gpfs_ssh_login`` = ``None``
+
      - (String) GPFS server SSH login name.
+
    * - ``gpfs_ssh_password`` = ``None``
+
      - (String) GPFS server SSH login password. The password is not needed, if 'gpfs_ssh_private_key' is configured.
+
    * - ``gpfs_ssh_port`` = ``22``
+
      - (Port number) GPFS server SSH port.
+
    * - ``gpfs_ssh_private_key`` = ``None``
+
      - (String) Path to GPFS server SSH private key for login.
+
    * - ``is_gpfs_node`` = ``False``
+
      - (Boolean) True:when Manila services are running on one of the Spectrum Scale node. False:when Manila services are not running on any of the Spectrum Scale node.
-   * - ``knfs_export_options`` = ``rw,sync,no_root_squash,insecure,no_wdelay,no_subtree_check``
-     - (String) DEPRECATED: Options to use when exporting a share using kernel NFS server. Note that these defaults can be overridden when a share is created by passing metadata with key name export_options. This option isn't used any longer. Please use share-type extra specs for export options.

tools/autogenerate-config-flagmappings/manila.flagmappings

@@ -77,15 +77,15 @@ glusterfs_share_layout glusterfs
 glusterfs_target glusterfs
 glusterfs_volume_pattern glusterfs
 goodness_function generic
-gpfs_mount_point_base gpfs
+gpfs_mount_point_base spectrumscale_ces spectrumscale_knfs
-gpfs_nfs_server_list gpfs
+gpfs_nfs_server_list spectrumscale_knfs
-gpfs_nfs_server_type gpfs
+gpfs_nfs_server_type spectrumscale_ces spectrumscale_knfs
-gpfs_share_export_ip gpfs
+gpfs_share_export_ip spectrumscale_ces spectrumscale_knfs
-gpfs_share_helpers gpfs
+gpfs_share_helpers spectrumscale_ces spectrumscale_knfs
-gpfs_ssh_login gpfs
+gpfs_ssh_login spectrumscale_ces spectrumscale_knfs
-gpfs_ssh_password gpfs
+gpfs_ssh_password spectrumscale_ces spectrumscale_knfs
-gpfs_ssh_port gpfs
+gpfs_ssh_port spectrumscale_ces spectrumscale_knfs
-gpfs_ssh_private_key gpfs
+gpfs_ssh_private_key spectrumscale_ces spectrumscale_knfs
 hdfs_namenode_ip hdfs
 hdfs_namenode_port hdfs
 hdfs_ssh_name hdfs
@@ -124,8 +124,7 @@ hpe3par_username hpe3par
 instance_format disable
 instance_uuid_format disable
 interface_driver generic
-is_gpfs_node gpfs
+is_gpfs_node spectrumscale_ces spectrumscale_knfs
-knfs_export_options gpfs
 log_config_append disable
 log_date_format disable
 log_dir disable

tools/autogenerate-config-flagmappings/manila.headers

@@ -10,7 +10,6 @@ emc EMC share driver
 ganesha Ganesha
 generic Generic share driver
 glusterfs GlusterFS share driver
-gpfs IBM GPFS share driver
 hdfs HDFS share driver
 hds_hnas HDS NAS share driver
 hds_hsp HDS HSP share driver
@@ -28,6 +27,8 @@ redis Redis
 san SAN
 scheduler Scheduler
 share Share
+spectrumscale_ces IBM Spectrum Scale CES share driver
+spectrumscale_knfs IBM Spectrum Scale KNFS share driver
 unity Dell EMC Unity share driver
 tegile Tegile share driver
 vmax Dell EMC VMAX share driver