openstack/openstack-manuals
Code Issues Proposed changes

Merge "Add Unity Cinder driver doc"

Browse Source
This commit is contained in:
Jenkins 2017-01-24 04:34:18 +00:00 committed by Gerrit Code Review
commit e0ca81025f
6 changed files with 324 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

296
doc/config-reference/source/block-storage/drivers/dell-emc-unity-driver.rst Normal file
View File

@ -0,0 +1,296 @@
=====================
Dell EMC Unity driver
=====================
Unity driver has been integrated in the OpenStack Block Storage project since
the Ocata release. The driver is built on the top of Block Storage framework
and a Dell EMC distributed Python package
`storops <https://pypi.python.org/pypi/storops>`_.
Prerequisites
~~~~~~~~~~~~~
+-------------------+----------------+
| Software | Version |
+===================+================+
| Unity OE | 4.1.X |
+-------------------+----------------+
| OpenStack | Ocata |
+-------------------+----------------+
| storops | 0.4.2 or newer |
+-------------------+----------------+
Supported operations
~~~~~~~~~~~~~~~~~~~~
- Create, delete, attach, and detach volumes.
- Create, list, and delete volume snapshots.
- Create a volume from a snapshot.
- Copy an image to a volume.
- Clone a volume.
- Extend a volume.
- Migrate a volume.
- Get volume statistics.
- Efficient non-disruptive volume backup.
Driver configuration
~~~~~~~~~~~~~~~~~~~~
.. note:: The following instructions should all be performed on Black Storage
nodes.
#. Install `storops` from pypi:
.. code-block:: console
# pip install storops
#. Add the following content into ``/etc/cinder/cinder.conf``:
.. code-block:: ini
# Storage protocol
storage_protocol = iSCSI
# Unisphere IP
san_ip = <SAN IP>
# Unisphere username and password
san_login = <SAN LOGIN>
san_password = <SAN PASSWORD>
# Volume driver name
volume_driver = cinder.volume.drivers.dell_emc.unity.Driver
# backend's name
volume_backend_name = Storage_ISCSI_01
.. note:: These are minimal options for Unity driver, for more options,
see `Driver options`_.
.. note:: (**Optional**) If you require multipath based data access, perform
below steps on both Block Storage and Compute nodes.
#. Install ``sysfsutils``, ``sg3-utils`` and ``multipath-tools``:
.. code-block:: console
# apt-get install multipath-tools sg3-utils sysfsutils
#. (Required for FC driver in case `Auto-zoning Support`_ is disabled) Zone the
FC ports of Compute nodes with Unity FC target ports.
#. Enable Unity storage optimized multipath configuration:
Add the following content into ``/etc/multipath.conf``
.. code-block:: none
blacklist {
# Skip the files uner /dev that are definitely not FC/iSCSI devices
# Different system may need different customization
devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
devnode "^hd[a-z][0-9]*"
devnode "^cciss!c[0-9]d[0-9]*[p[0-9]*]"
# Skip LUNZ device from VNX/Unity
device {
vendor "DGC"
product "LUNZ"
}
}
defaults {
user_friendly_names no
flush_on_last_del yes
}
devices {
# Device attributed for EMC CLARiiON and VNX/Unity series ALUA
device {
vendor "DGC"
product ".*"
product_blacklist "LUNZ"
path_grouping_policy group_by_prio
path_selector "round-robin 0"
path_checker emc_clariion
features "0"
no_path_retry 12
hardware_handler "1 alua"
prio alua
failback immediate
}
}
#. Restart the multipath service:
.. code-block:: console
# service multipath-tools restart
#. Enable multipath for image transfer in ``/etc/cinder/cinder.conf``.
.. code-block:: ini
use_multipath_for_image_xfer = True
Restart the ``cinder-volume`` service to load the change.
#. Enable multipath for volume attache/detach in ``/etc/nova/nova.conf``.
.. code-block:: ini
[libvirt]
...
volume_use_multipath = True
...
#. Restart the ``nova-compute`` service.
Driver options
~~~~~~~~~~~~~~
.. include:: ../../tables/cinder-dell_emc_unity.rst
Live migration integration
~~~~~~~~~~~~~~~~~~~~~~~~~~
It is suggested to have multipath configured on Compute nodes for robust data
access in VM instances live migration scenario. Once ``user_friendly_names no``
is set in defaults section of ``/etc/multipath.conf``, Compute nodes will use
the WWID as the alias for the multipath devices.
To enable multipath in live migration:
.. note:: Make sure `Driver configuration`_ steps are performed before
following steps.
#. Set multipath in ``/etc/nova/nova.conf``:
.. code-block:: none
[libvirt]
...
volume_use_multipath = True
...
Restart `nova-compute` service.
#. Set ``user_friendly_names no`` in ``/etc/multipath.conf``
.. code-block:: none
...
defaults {
user_friendly_names no
}
...
#. Restart the ``multipath-tools`` service.
Thin and thick provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Only thin volume provisioning is supported in Unity volume driver.
QoS support
```````````
Unity driver supports ``maxBWS`` and ``maxIOPS`` specs for the back-end
consumer type. ``maxBWS`` represents the ``Maximum IO/S`` absolute limit,
``maxIOPS`` represents the ``Maximum Bandwidth (KBPS)`` absolute limit on the
Unity respectively.
Auto-zoning support
~~~~~~~~~~~~~~~~~~~
Unity volume driver supports auto-zoning, and share the same configuration
guide for other vendors. Refer to :ref:`fc_zone_manager`
for detailed configuration steps.
Solution for LUNZ device
~~~~~~~~~~~~~~~~~~~~~~~~
The EMC host team also found LUNZ on all of the hosts, EMC best practice is to
present a LUN with HLU 0 to clear any LUNZ devices as they can cause issues on
the host. See KB `LUNZ Device <https://support.emc.com/kb/463402>`_.
To workaround this issue, Unity driver creates a `Dummy LUN` (if not present),
and adds it to each host to occupy the `HLU 0` during volume attachment.
.. note:: This `Dummy LUN` is shared among all hosts connected to the Unity.
Troubleshooting
~~~~~~~~~~~~~~~
To troubleshoot a failure in OpenStack deployment, the best way is to enable
verbose and debug log, at the same time, leverage the build-in [request_id]_ to
track specific Block Storage command logs.
#. Enable verbose log, set following in ``/etc/cinder/cinder.conf`` and restart
all Block Storage services:
.. code-block:: none
[DEFALUT]
...
debug = True
verbose = True
...
If other projects (usually Compute) are also involved, set `debug`
and ``verbose`` to ``True``.
#. use ``--debug`` to trigger any problematic Block Storage operation:
.. code-block:: console
# cinder --debug create --name unity_vol1 100
You will see the request ID from the console, for example:
.. code-block:: console
DEBUG:keystoneauth:REQ: curl -g -i -X POST
http://192.168.1.9:8776/v2/e50d22bdb5a34078a8bfe7be89324078/volumes -H
"User-Agent: python-cinderclient" -H "Content-Type: application/json" -H
"Accept: application/json" -H "X-Auth-Token:
{SHA1}bf4a85ad64302b67a39ad7c6f695a9630f39ab0e" -d '{"volume": {"status":
"creating", "user_id": null, "name": "unity_vol1", "imageRef": null,
"availability_zone": null, "description": null, "multiattach": false,
"attach_status": "detached", "volume_type": null, "metadata": {},
"consistencygroup_id": null, "source_volid": null, "snapshot_id": null,
"project_id": null, "source_replica": null, "size": 10}}'
DEBUG:keystoneauth:RESP: [202] X-Compute-Request-Id:
req-3a459e0e-871a-49f9-9796-b63cc48b5015 Content-Type: application/json
Content-Length: 804 X-Openstack-Request-Id:
req-3a459e0e-871a-49f9-9796-b63cc48b5015 Date: Mon, 12 Dec 2016 09:31:44 GMT
Connection: keep-alive
#. Use commands like ``grep``, ``awk`` to find the error related to the Block
Storage operations.
.. code-block:: console
# grep "req-3a459e0e-871a-49f9-9796-b63cc48b5015" cinder-volume.log
.. [request_id] `Return request ID to caller
<https://specs.openstack.org/openstack/openstack-specs/specs/return-request-id.html>`_

3
doc/config-reference/source/block-storage/fc-zoning.rst
View File

@ -1,3 +1,6 @@
.. _fc_zone_manager:
==========================
Fibre Channel Zone Manager
==========================

1
doc/config-reference/source/block-storage/volume-drivers.rst
View File

@ -21,6 +21,7 @@ Volume drivers
drivers/datera-volume-driver.rst
drivers/dell-equallogic-driver.rst
drivers/dell-storagecenter-driver.rst
drivers/dell-emc-unity-driver.rst
drivers/dothill-driver.rst
drivers/emc-scaleio-driver.rst
drivers/emc-vmax-driver.rst

22
doc/config-reference/source/tables/cinder-dell_emc_unity.rst Normal file
View File

@ -0,0 +1,22 @@
..
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.
.. _cinder-dell_emc_unity:
.. list-table:: Description of Dell EMC Unity volume driver configuration options
:header-rows: 1
:class: config-ref-table
* - Configuration option = Default value
- Description
* - **[DEFAULT]**
-
* - ``unity_storage_pool_names`` = ``None``
- (List) A comma-separated list of storage pool names to be used.

1
tools/autogenerate-config-flagmappings/cinder.flagmappings
View File

@ -671,6 +671,7 @@ tintri_server_password tintri
tintri_server_username tintri
trace_flags debug
transfer_api_class api
unity_storage_pool_names dell_emc_unity
until_refresh common
use_chap_auth common
use_default_quota_class quota

1
tools/autogenerate-config-flagmappings/cinder.headers
View File

@ -13,6 +13,7 @@ coho Coho volume driver
coordination Coordination
coprhd Coprhd volume driver
datera Datera volume driver
dell_emc_unity Dell EMC Unity volume driver
dellsc Dell Storage Center volume driver
disco Disco volume driver
dothill Dot Hill volume driver