diff --git a/doc/admin-guide-cloud-rst/source/blockstorage.rst b/doc/admin-guide-cloud-rst/source/blockstorage.rst index 2e62ba80c3..58d0dc81d0 100644 --- a/doc/admin-guide-cloud-rst/source/blockstorage.rst +++ b/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 diff --git a/doc/admin-guide-cloud-rst/source/blockstorage_glusterfs_backend.rst b/doc/admin-guide-cloud-rst/source/blockstorage_glusterfs_backend.rst index 914f9d8a6c..6db53c21a2 100644 --- a/doc/admin-guide-cloud-rst/source/blockstorage_glusterfs_backend.rst +++ b/doc/admin-guide-cloud-rst/source/blockstorage_glusterfs_backend.rst @@ -1,7 +1,5 @@ .. glusterfs_backend: -.. orphan: - Configure a GlusterFS back end ------------------------------ diff --git a/doc/admin-guide-cloud-rst/source/blockstorage_multi_backend.rst b/doc/admin-guide-cloud-rst/source/blockstorage_multi_backend.rst new file mode 100644 index 0000000000..2982161138 --- /dev/null +++ b/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``.