Merge "nimble: update documentation for supportability"

doc/source/configuration/block-storage/drivers/nimble-volume-driver.rst

@@ -17,8 +17,9 @@ later.
 
 Nimble Storage Cinder driver does not support port binding with multiple
 interfaces on the same subnet due to existing limitation in os-brick. This
-is partially referenced in https://bugs.launchpad.net/os-brick/+bug/1722432
+is partially referenced in the bug https://bugs.launchpad
-but does not resolve for multiple software iscsi ifaces.
+.net/os-brick/+bug/1722432 but does not resolve for multiple software
+iscsi ifaces
 
 Supported operations
 ~~~~~~~~~~~~~~~~~~~~
@@ -151,3 +152,95 @@ Configuration options
 The Nimble storage driver supports these configuration options:
 
 .. include:: ../../tables/cinder-nimble.inc
+
+
+Multipathing
+~~~~~~~~~~~~
+In OpenStack environments where Cinder block device multipathing is desired
+there are a few things to consider.
+
+Configuring mulitpathing varies by system depending on the environment. In a
+scenario where solely Nimble devices are being created by Cinder, the
+following ``/etc/multipath.conf`` file may be used:
+
+.. code-block:: json
+
+   defaults {
+       user_friendly_names yes
+       find_multipaths     no
+   }
+   blacklist {
+       devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
+       devnode "^hd[a-z]"
+       device {
+           vendor  ".*"
+           product ".*"
+       }
+   }
+   blacklist_exceptions {
+       device {
+           vendor  "Nimble"
+           product "Server"
+       }
+   }
+   devices {
+       device {
+           vendor               "Nimble"
+           product              "Server"
+           path_grouping_policy group_by_prio
+           prio                 "alua"
+           hardware_handler     "1 alua"
+           path_selector        "service-time 0"
+           path_checker         tur
+           features             "1 queue_if_no_path"
+           no_path_retry        30
+           failback             immediate
+           fast_io_fail_tmo     5
+           dev_loss_tmo         infinity
+           rr_min_io_rq         1
+           rr_weight            uniform
+       }
+   }
+
+After making changes to ``/etc/multipath.conf``, the multipath subsystem needs
+to be reconfigured:
+
+.. code-block:: console
+
+   # multipathd reconfigure
+
+.. tip::
+
+   The latest best practices for Nimble devices can be found in the HPE Nimble
+   Storage Linux Integration Guide found on https://infosight.hpe.com
+
+.. important::
+
+   OpenStack Cinder is currently not compatible with the HPE Nimble Storage
+   Linux Toolkit (NLT)
+
+Nova needs to be configured to pickup the actual multipath device created on
+the host.
+
+In ``/etc/nova/nova.conf``, add the following to the ``[libvirt]`` section:
+
+.. code-block:: ini
+
+   [libvirt]
+   volume_use_multipath = True
+
+.. note::
+   In versions prior to Newton, the option was called ``iscsi_use_multipath``
+
+After editing the Nova configuration file, the ``nova-conductor`` service
+needs to be restarted.
+
+.. tip::
+   Depending on which particular OpenStack distribution is being used, Nova
+   may use a different configuration file than the default.
+
+To validate that instances get properly connected to the multipath device,
+inspect the instance devices:
+
+.. code-block:: console
+   # virsh dumpxml <Instance ID | Instance Name | Instance UUID>