Merge "Converts section_multi_backend.xml to RST"

doc/admin-guide-cloud-rst/source/blockstorage.rst

@@ -128,15 +128,16 @@ in the `OpenStack End User Guide`_.
 
 .. include:: blockstorage_nfs_backend.rst
 .. include:: blockstorage_glusterfs_backend.rst
+.. include:: blockstorage_multi_backend.rst
 
 .. toctree::
    :hidden:
 
    blockstorage_nfs_backend.rst
    blockstorage_glusterfs_backend.rst
+   blockstorage_multi_backend.rst
 
 .. TODO (MZ) Convert and include the following sections
-   include: blockstorage/section_multi_backend.xml
    include: blockstorage/section_backup-block-storage-disks.xml
    include: blockstorage/section_volume-migration.xml
    include: blockstorage/section_glusterfs_removal.xml

doc/admin-guide-cloud-rst/source/blockstorage_glusterfs_backend.rst

@@ -1,7 +1,5 @@
 .. glusterfs_backend:
 
-.. orphan:
-
 Configure a GlusterFS back end
 ------------------------------
 

doc/admin-guide-cloud-rst/source/blockstorage_multi_backend.rst

@@ -0,0 +1,156 @@
+.. _multi_backend:
+
+.. highlight: ini
+   :linenothreshold: 5
+
+Configure multiple-storage back ends
+------------------------------------
+
+When you configure multiple-storage back ends, you can create several
+back-end storage solutions that serve the same OpenStack Compute
+configuration and one ``cinder-volume`` is launched for each back-end
+storage or back-end storage pool.
+
+In a multiple-storage back-end configuration, each back end has a name
+(``volume_backend_name``). Several back ends can have the same name.
+In that case, the scheduler properly decides which back end the volume
+has to be created in.
+
+The name of the back end is declared as an extra-specification of a
+volume type (such as, ``volume_backend_name=LVM_iSCSI``). When a volume
+is created, the scheduler chooses an appropriate back end to handle the
+request, according to the volume type specified by the user.
+
+**Enable multiple-storage back ends**
+
+To enable a multiple-storage back ends, you must set the
+`enabled_backends` flag in the :file:`cinder.conf` file.
+This flag defines the names (separated by a comma) of the configuration
+groups for the different back ends: one name is associated to one
+configuration group for a back end (such as, ``[lvmdriver-1]``).
+
+.. note::
+
+   The configuration group name is not related to the ``volume_backend_name``.
+
+.. note::
+
+   After setting the `enabled_backends` flag on an existing cinder
+   service, and restarting the Block Storage services, the original ``host``
+   service is replaced with a new host service. The new service appears
+   with a name like ``host@backend``. Use::
+
+    $ cinder-manage volume host --currentname CURRENTNAME --newname CURRENTNAME@BACKEND
+
+   to convert current block devices to the new hostname.
+
+The options for a configuration group must be defined in the group
+(or default options are used). All the standard Block Storage
+configuration options (``volume_group``, ``volume_driver``, and so on)
+might be used in a configuration group. Configuration values in
+the ``[DEFAULT]`` configuration group are not used.
+
+These examples show three back ends:
+
+.. code-block:: ini
+   :linenos:
+
+   enabled_backends=lvmdriver-1,lvmdriver-2,lvmdriver-3
+   [lvmdriver-1]
+   volume_group=cinder-volumes-1
+   volume_driver=cinder.volume.drivers.lvm.LVMISCSIDriver
+   volume_backend_name=LVM_iSCSI
+   [lvmdriver-2]
+   volume_group=cinder-volumes-2
+   volume_driver=cinder.volume.drivers.lvm.LVMISCSIDriver
+   volume_backend_name=LVM_iSCSI
+   [lvmdriver-3]
+   volume_group=cinder-volumes-3
+   volume_driver=cinder.volume.drivers.lvm.LVMISCSIDriver
+   volume_backend_name=LVM_iSCSI_b
+
+In this configuration, ``lvmdriver-1`` and ``lvmdriver-2`` have the same
+``volume_backend_name``. If a volume creation requests the ``LVM_iSCSI``
+back end name, the scheduler uses the capacity filter scheduler to choose
+the most suitable driver, which is either ``lvmdriver-1`` or ``lvmdriver-2``.
+The capacity filter scheduler is enabled by default. The next section
+provides more information. In addition, this example presents a
+``lvmdriver-3`` back end.
+
+**Configure Block Storage scheduler multi back end**
+
+You must enable the `filter_scheduler` option to use
+multiple-storage back ends. The filter scheduler:
+
+#. Filters the available back ends. By default, ``AvailabilityZoneFilter``,
+   ``CapacityFilter`` and ``CapabilitiesFilter`` are enabled.
+
+#. Weights the previously filtered back ends. By default, the
+   `CapacityWeigher` option is enabled. When this option is
+   enabled, the filter scheduler assigns the highest weight to back
+   ends with the most available capacity.
+
+The scheduler uses filters and weights to pick the best back end to
+handle the request. The scheduler uses volume types to explicitly create
+volumes on specific back ends.
+
+.. TODO: when filter/weighing scheduler documentation will be up, a ref
+         should be added here
+
+**Volume type**
+
+Before using it, a volume type has to be declared to Block Storage.
+This can be done by the following command::
+
+ $ cinder --os-username admin --os-tenant-name admin type-create lvm
+
+Then, an extra-specification has to be created to link the volume
+type to a back end name. Run this command::
+
+ $ cinder --os-username admin --os-tenant-name admin type-key lvm set \
+   volume_backend_name=LVM_iSCSI
+
+This example creates a ``lvm`` volume type with
+``volume_backend_name=LVM_iSCSI`` as extra-specifications.
+
+Create another volume type::
+
+ $ cinder --os-username admin --os-tenant-name admin type-create lvm_gold
+
+ $ cinder --os-username admin --os-tenant-name admin type-key lvm_gold set \
+   volume_backend_name=LVM_iSCSI_b
+
+This second volume type is named ``lvm_gold`` and has ``LVM_iSCSI_b`` as
+back end name.
+
+.. note::
+
+   To list the extra-specifications, use this command::
+
+    $ cinder --os-username admin --os-tenant-name admin extra-specs-list
+
+.. note::
+
+   If a volume type points to a ``volume_backend_name`` that does not
+   exist in the Block Storage configuration, the ``filter_scheduler``
+   returns an error that it cannot find a valid host with the suitable
+   back end.
+
+**Usage**
+
+When you create a volume, you must specify the volume type.
+The extra-specifications of the volume type are used to determine which
+back end has to be used.
+
+::
+
+$ cinder create --volume_type lvm --display_name test_multi_backend 1
+
+Considering the :file:`cinder.conf` described previously, the scheduler
+creates this volume on ``lvmdriver-1`` or ``lvmdriver-2``.
+
+::
+
+$ cinder create --volume_type lvm_gold --display_name test_multi_backend 1
+
+This second volume is created on ``lvmdriver-3``.