diff --git a/doc/config-reference/source/block-storage/drivers/dell-emc-unity-driver.rst b/doc/config-reference/source/block-storage/drivers/dell-emc-unity-driver.rst new file mode 100644 index 0000000000..b96a208052 --- /dev/null +++ b/doc/config-reference/source/block-storage/drivers/dell-emc-unity-driver.rst @@ -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 `_. + +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 = + # Unisphere username and password + san_login = + 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 `_. + +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 + `_ diff --git a/doc/config-reference/source/block-storage/fc-zoning.rst b/doc/config-reference/source/block-storage/fc-zoning.rst index a4c3e91490..28085e3675 100644 --- a/doc/config-reference/source/block-storage/fc-zoning.rst +++ b/doc/config-reference/source/block-storage/fc-zoning.rst @@ -1,3 +1,6 @@ + +.. _fc_zone_manager: + ========================== Fibre Channel Zone Manager ========================== diff --git a/doc/config-reference/source/block-storage/volume-drivers.rst b/doc/config-reference/source/block-storage/volume-drivers.rst index 6b8dd3fb94..d7155e2ef5 100644 --- a/doc/config-reference/source/block-storage/volume-drivers.rst +++ b/doc/config-reference/source/block-storage/volume-drivers.rst @@ -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 diff --git a/doc/config-reference/source/tables/cinder-dell_emc_unity.rst b/doc/config-reference/source/tables/cinder-dell_emc_unity.rst new file mode 100644 index 0000000000..65d823beee --- /dev/null +++ b/doc/config-reference/source/tables/cinder-dell_emc_unity.rst @@ -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. diff --git a/tools/autogenerate-config-flagmappings/cinder.flagmappings b/tools/autogenerate-config-flagmappings/cinder.flagmappings index 3bec43ecda..8cbae8a8c0 100644 --- a/tools/autogenerate-config-flagmappings/cinder.flagmappings +++ b/tools/autogenerate-config-flagmappings/cinder.flagmappings @@ -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 diff --git a/tools/autogenerate-config-flagmappings/cinder.headers b/tools/autogenerate-config-flagmappings/cinder.headers index 70a35fda4b..191112cfe5 100644 --- a/tools/autogenerate-config-flagmappings/cinder.headers +++ b/tools/autogenerate-config-flagmappings/cinder.headers @@ -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