IBM Storage: add QoS documentation

Add best practice for using QoS feature with IBM Storage
Cinder driver
Also, handle some general text cleanup and formatting

Change-Id: I848f6feaefbdbddb1f77b699012a96b235f7d7eb
Closes-Bug: 1698433

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

@@ -16,9 +16,9 @@ The driver was validated on the following storage systems:
 * IBM Spectrum Accelerate
 * IBM XIV Storage System
 
-After the driver is configured on the OpenStack cinder nodes, storage volumes
+After the driver is configured on the OpenStack Cinder nodes, storage volumes
-can be allocated by the cinder nodes to the nova nodes. Virtual machines on
+can be allocated by the Cinder nodes to the Nova nodes. Virtual machines on
-the nova nodes can then utilize these storage resources.
+the Nova nodes can then utilize these storage resources.
 
 .. note::
     Unless stated otherwise, all references to XIV storage
@@ -29,14 +29,14 @@ Concept diagram
 ---------------
 This figure illustrates how an IBM storage system is connected
 to the OpenStack cloud environment and provides storage resources when the
-IBM Storage Driver for OpenStack is configured on the OpenStack cinder nodes.
+IBM Storage Driver for OpenStack is configured on the OpenStack Cinder nodes.
 The OpenStack cloud is connected to the IBM storage system over Fibre
 Channel or iSCSI (DS8000 systems support only Fibre Channel connections).
 Remote cloud users can issue requests for storage resources from the
 OpenStack cloud. These requests are transparently handled by the IBM Storage
 Driver, which communicates with the IBM storage system and controls the
 storage volumes on it. The IBM storage resources are then provided to the
-nova nodes in the OpenStack cloud.
+Nova nodes in the OpenStack cloud.
 
 .. figure:: ../../figures/ibm-storage-nova-concept.png
 
@@ -74,21 +74,20 @@ man-in-the-middle (MITM) attacks by following these rules:
 
 * Validate the storage certificate. If you are using an XIV-provided
   certificate, use the CA file that was provided with your storage system
-  (``XIV-CA.pem``). The certificate files should be copied to one of the
+  (``XIV-CA.pem``). The certificate files should be copied to one of the following
-  following directories:
+  directories:
 
-  * ``/etc/ssl/certs``
+    * ``/etc/ssl/certs``
-  * ``/etc/ssl/certs/xiv``
+    * ``/etc/ssl/certs/xiv``
-  * ``/etc/pki``
+    * ``/etc/pki``
-  * ``/etc/pki/xiv``
+    * ``/etc/pki/xiv``
 
-  If you are using your own certificates, copy them to the same directories
+If you are using your own certificates, copy them to the same directories
-  with the prefix ``XIV`` and in the ``.pem`` format.
+with the prefix "XIV" and in the ``.pem`` format. For example: XIV-my_cert.pem.
-  For example: ``XIV-my_cert.pem``.
 
-* To prevent the CVE-2014-3566 MITM attack, follow the OpenStack
+* In order to prevent the CVE-2014-3566 MITM attack, follow the OpenStack
-  community
+  community directions:
-  `directions <http://osdir.com/ml/openstack-dev/2014-10/msg01349.html>`_.
+  (http://osdir.com/ml/openstack-dev/2014-10/msg01349.html).
 
 Troubleshooting
 ~~~~~~~~~~~~~~~
@@ -96,16 +95,16 @@ Troubleshooting
 Refer to this information to troubleshoot technical problems that you
 might encounter when using the IBM Storage Driver for OpenStack.
 
-Checking the cinder node log files
+Checking the Cinder node log files
 ----------------------------------
 
-The cinder log files record operation information that might be useful
+The Cinder log files record operation information that might be useful
 for troubleshooting.
 
 To achieve optimal and clear logging of events, activate the verbose
-logging level in the ``cinder.conf`` file, located in the ``/etc/cinder``
+logging level in the cinder.conf file, located in the ``/etc/cinder``
 folder. Add the following line in the file, save the file, and then
-restart the ``cinder-volume`` service:
+restart the cinder-volume service:
 
 .. code-block:: console
 
@@ -113,17 +112,17 @@ restart the ``cinder-volume`` service:
     debug = True
 
 To turn off the verbose logging level, change ``True`` to ``False``,
-save the file, and then restart the ``cinder-volume`` service.
+save the file, and then restart the cinder-volume service.
 
 Check the log files on a periodic basis to ensure that the IBM
-Storage Driver is functioning properly:
+Storage Driver is functioning properly.
 
-#. Log into the cinder node.
+To check the log file on a Cinder node:
-#. Go to the ``/var/log/cinder`` folder
+Go to the /var/log/cinder folder and open the activity log file named
-#. Open the activity log file named ``cinder-volume.log`` or ``volume.log``.
+cinder-volume.log or volume.log. The IBM Storage Driver writes to this
-   The IBM Storage Driver writes to this log file using the
+log file using the [IBM DS8K STORAGE] or [IBM XIV STORAGE] prefix
-   ``[IBM DS8K STORAGE]`` or ``[IBM XIV STORAGE]`` prefix (depending on
+(depending on the relevant storage system) for each event that it
-   the relevant storage system) for each event that it records in the file.
+records in the file.
 
 
 Best practices
@@ -145,13 +144,13 @@ In order to use multi-tenancy with the IBM Storage Driver for OpenStack:
   credentials, as long as the credentials grant a full access to the relevant
   pool.
 * If the user is a domain administrator, the storage system domain
-  access policy can be ``CLOSED`` (``domain_policy: access=CLOSED``).
+  access policy can be CLOSED (``domain_policy: access=CLOSED``).
   Otherwise, verify that the storage system domain access policy is
-  ``OPEN`` (``domain_policy: access=OPEN``).
+  OPEN (``domain_policy: access=OPEN``).
 * If the user is not a domain administrator, the host management policy
-  of the storage system domain can be ``BASIC`` (``domain_policy:
+  of the storage system domain can be BASIC (``domain_policy:
   host_management=BASIC``). Otherwise, verify that the storage
-  system domain host management policy is ``EXTENDED``
+  system domain host management policy is EXTENDED
   (``domain_policy: host_management=EXTENDED``).
 
 Working with IBM Real-time Compression™
@@ -170,3 +169,61 @@ resources using the IBM Storage Driver for OpenStack:
 
 * The minimum size for a compressed storage volume is 87 GB.
 
+Working with QoS
+----------------
+The IBM Storage Driver for OpenStack provides QoS per volume for
+IBM FlashSystem A9000/A9000R storage systems, running microcode
+version of 12.0 or later. With QoS classes, the user can control
+the maximum bandwidth and I/O operations for each volume.
+
+See IBM Spectrum Accelerate Family Storage Configuration and Usage
+for IBM FlashSystem A9000, IBM FlashSystem A9000R and IBM XIV Gen3,
+SG24-8376 for information about how to set QoS by defining
+performance classes in terms of IOPS and bandwidth limitation
+
+QoS class types:
+
+* Shared (default). Limits the combined rates of all of the volumes
+  in the same QoS class. The maximum rate is the sum of the
+  combined rate for each volume. For example, two volumes under
+  a QoS class of maximum 100 Gbps are allocated a combined
+  maximum bandwidth rate of 100 Gbps.
+
+* Independent. Sets the maximum rate separately for each volume
+  in the QoS class. For example, for two volumes under a QoS
+  class of maximum 100 Gbps, each volume is limited to a rate
+  of 100 Gbps. Thus, the combined maximum bandwidth rate is up
+  to 200 Gbps.
+
+To define a QoS class:
+
+ 1. Create the QoS class:
+
+    .. code-block:: console
+
+         cinder qos-create <class_name> <class_specs: bw=#, iops=#>
+
+ 2. Create a type:
+
+    .. code-block:: console
+
+        cinder type-create type_<qos_class_name>
+
+ 3. Associate the QoS class with the type:
+
+    .. code-block:: console
+
+        cinder qos-associate <qos uuid> <type uuid>
+
+ 4. Announce that the type is supporting QoS:
+
+    .. code-block:: console
+
+        cinder type-key <type_name or UUID> set QoS_support=True
+
+ 5. Create a volume:
+
+    .. code-block:: console
+
+        cinder create 1 --volume-type <type_name>
+