From c9d8506f80faa3e9854dadd71305f450f78b0bb2 Mon Sep 17 00:00:00 2001 From: dingd Date: Wed, 11 Sep 2019 14:09:37 +0800 Subject: [PATCH] [Unity] Sync Unity related Docs 1. Add DHSS=False mode support 2. Update emc_unity_driver.rst and dell-emc-unity-driver.rst to almost same, easy for update doc change in the future Change-Id: If2ca14772e9083866f619e3f2c364fb530775eac Closes-bug: #1657605 --- doc/source/admin/emc_unity_driver.rst | 266 ------------ doc/source/admin/index.rst | 2 +- ...hare_back_ends_feature_support_mapping.rst | 2 +- .../drivers/dell-emc-unity-driver.rst | 380 +++++++++--------- 4 files changed, 192 insertions(+), 458 deletions(-) delete mode 100644 doc/source/admin/emc_unity_driver.rst diff --git a/doc/source/admin/emc_unity_driver.rst b/doc/source/admin/emc_unity_driver.rst deleted file mode 100644 index 8b07bbdd42..0000000000 --- a/doc/source/admin/emc_unity_driver.rst +++ /dev/null @@ -1,266 +0,0 @@ -.. - Copyright (c) 2014 EMC Corporation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - -Unity Driver -============ - -EMC manila driver framework (EMCShareDriver) utilizes the EMC storage products -to provide the shared filesystems to OpenStack. The EMC manila driver is a -plugin based driver which is designed to use different plugins to manage -different EMC storage products. - -Unity plugin is the plugin which manages the Unity Storage System to provide -shared filesystems. EMC driver framework with Unity plugin is referred to as -Unity driver in this document. - -This driver performs the operations on Unity by REST API. Each backend manages -one Unity Storage System. Multiple manila backends need to be configured to -manage multiple Unity Storage Systems. - -Requirements ------------- - -- Unity OE 4.0.1 or higher. -- StorOps 1.1.0 or higher is installed on Manila node. -- Following licenses are activated on Unity: - - * CIFS/SMB Support - * Network File System (NFS) - * Thin Provisioning - * Fiber Channel (FC) - * Internet Small Computer System Interface (iSCSI) - - -Supported Operations --------------------- - -In detail, users are allowed to do following operation with EMC Unity -Storage Systems. - -* Create/delete a NFS share. -* Create/delete a CIFS share. -* Extend the size of a share. -* Shrink the size of a share. -* Modify the host access privilege of a NFS share. -* Modify the user access privilege of a CIFS share. -* Take/Delete snapshot of a share. -* Create a new share from snapshot. -* Revert a share to a snapshot. - - -Supported Network Topologies ----------------------------- - -* flat -* VLAN - - -Pre-Configurations ------------------- - -On Manila Node -~~~~~~~~~~~~~~ - -StorOps library is required to run Unity driver. -Please install it with the pip command. -You may need root privilege to install python libraries. - -:: - - pip install storops - - -On Unity System -~~~~~~~~~~~~~~~ - -1. Configure System level NTP Server - -Configure the NTP server for your Unity at: - -.. code-block:: console - - Unisphere -> Settings -> Management -> System Time and NTP - -Select "Enable NTP synchronization" and add your NTP server(s). - -2. Configure System level DNS Server - -Configure the DNS server for your Unity at: - -.. code-block:: console - - Unisphere -> Settings -> Management -> DNS Server - -Select "Configure DNS server address manually" and add your DNS server(s). - - -Configurations --------------- - -Following configurations need to be configured in `/etc/manila/manila.conf` -for the Unity driver. - -.. code-block:: ini - - share_driver = manila.share.drivers.dell_emc.driver.EMCShareDriver - emc_share_backend = unity - emc_nas_server = - emc_nas_login = - emc_nas_password = - unity_server_meta_pool = - unity_share_data_pools = - unity_ethernet_ports = - driver_handles_share_servers = True/False - unity_share_server = - -- `emc_share_backend` - The plugin name. Set it to `unity` for the Unity driver. - -- `emc_nas_server` - The management IP for Unity. - -- `unity_server_meta_pool` - The name of the pool to persist the meta-data of NAS server. - This option is required. - -- `unity_share_data_pools` - Comma separated list specifying the name of the pools to be used - by this backend. Do not set this option if all storage pools - on the system can be used. - Wild card character is supported. - - Examples: - - .. code-block:: ini - - # Only use pool_1 - unity_share_data_pools = pool_1 - # Only use pools whose name stars from pool_ - unity_share_data_pools = pool_* - # Use all pools on Unity - unity_share_data_pools = * - -- `unity_ethernet_ports` - Comma separated list specifying the ethernet ports of Unity system - that can be used for share. Do not set this option if all ethernet ports - can be used. - Wild card character is supported. Both the normal ethernet port and link - aggregation port can be used by Unity share driver. - - - Examples: - - .. code-block:: ini - - # Only use spa_eth1 - unity_ethernet_ports = spa_eth1 - # Use port whose name stars from spa_ - unity_ethernet_ports = spa_* - # Use all Link Aggregation ports - unity_ethernet_ports = sp*_la_* - # Use all available ports - unity_ethernet_ports = * - -- `driver_handles_share_servers` - Unity driver requires this option to be as `True` or `False`. - Need to set `unity_share_server` when the value is `False`. - -- `unity_share_server` - One of NAS server names in Unity, it is used for share creation when - the driver is in `DHSS=False` mode. - -Restart of :term:`manila-share` service is needed for the configuration changes to take -effect. - -IPv6 support ------------- - -IPv6 support for Unity driver is introduced in Queens release. The feature is divided -into two parts: - -1. The driver is able to manage share or snapshot in the Neutron IPv6 network. -2. The driver is able to connect Unity management interface using its IPv6 address. - -Snapshot support ----------------- - -In the Mitaka and Newton release of OpenStack, Snapshot support is enabled by default for a newly created share type. -Starting with the Ocata release, the snapshot_support extra spec must be set to True in order to allow snapshots for -a share type. If the 'snapshot_support' extra_spec is omitted or if it is set to False, users would not be able to -create snapshots on shares of this share type. The feature is divided into two parts: - -1. The driver is able to create/delete snapshot of share. -2. The driver is able to create share from snapshot. - -Restrictions ------------- - -The Unity driver has following restrictions. - -- EMC Unity does not support the same IP in different VLANs. -- Only IP access type is supported for NFS. -- Only user access type is supported for CIFS. - - -API Implementations -------------------- - -Following driver features are implemented in the plugin. - -* create_share: Create a share and export it based on the protocol used - (NFS or CIFS). -* create_share_from_snapshot: Create a share from a snapshot - clone a - snapshot. -* delete_share: Delete a share. -* extend_share: Extend the maximum size of a share. -* shrink_share: Shrink the minimum size of a share. -* create_snapshot: Create a snapshot for the specified share. -* delete_snapshot: Delete the snapshot of the share. -* update_access: recover, add or delete user/host access to a share. -* allow_access: Allow access (read write/read only) of a user to a - CIFS share. Allow access (read write/read only) of a host to a NFS - share. -* deny_access: Remove access (read write/read only) of a user from - a CIFS share. Remove access (read write/read only) of a host from a - NFS share. -* ensure_share: Check whether share exists or not. -* update_share_stats: Retrieve share related statistics from Unity. -* get_network_allocations_number: Returns number of network allocations for - creating VIFs. -* setup_server: Set up and configures share server with given network - parameters. -* teardown_server: Tear down the share server. -* revert_to_snapshot: Revert a share to a snapshot. - - -The :mod:`manila.share.drivers.dell_emc.driver` Module ------------------------------------------------------- - -.. automodule:: manila.share.drivers.dell_emc.driver - :noindex: - :members: - :undoc-members: - :show-inheritance: - -The :mod:`manila.share.drivers.dell_emc.plugins.unity.connection` Module ------------------------------------------------------------------------- - -.. automodule:: manila.share.drivers.dell_emc.plugins.unity.connection - :noindex: - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 8d1414059d..94de5a3113 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -77,7 +77,7 @@ each back end. netapp_cluster_mode_driver emc_isilon_driver emc_vnx_driver - emc_unity_driver + ../configuration/shared-file-systems/drivers/dell-emc-unity-driver generic_driver glusterfs_driver glusterfs_native_driver diff --git a/doc/source/admin/share_back_ends_feature_support_mapping.rst b/doc/source/admin/share_back_ends_feature_support_mapping.rst index 1c3f4b667c..c45342156b 100644 --- a/doc/source/admin/share_back_ends_feature_support_mapping.rst +++ b/doc/source/admin/share_back_ends_feature_support_mapping.rst @@ -250,7 +250,7 @@ More information: :ref:`capabilities_and_extra_specs` +----------------------------------------+-----------+------------+--------+-------------+-------------------+--------------------+-----+----------------------------+--------------------+--------------------+--------------+--------------+ | EMC VNX | J | \- | \- | \- | \- | L | \- | J | \- | \- | P | Q | +----------------------------------------+-----------+------------+--------+-------------+-------------------+--------------------+-----+----------------------------+--------------------+--------------------+--------------+--------------+ -| EMC Unity | N | \- | \- | \- | N | \- | \- | N | \- | \- | P | Q | +| EMC Unity | N | T | \- | \- | N | \- | \- | N | S | \- | P | Q | +----------------------------------------+-----------+------------+--------+-------------+-------------------+--------------------+-----+----------------------------+--------------------+--------------------+--------------+--------------+ | EMC Isilon | \- | K | \- | \- | \- | L | \- | K | \- | \- | P | \- | +----------------------------------------+-----------+------------+--------+-------------+-------------------+--------------------+-----+----------------------------+--------------------+--------------------+--------------+--------------+ diff --git a/doc/source/configuration/shared-file-systems/drivers/dell-emc-unity-driver.rst b/doc/source/configuration/shared-file-systems/drivers/dell-emc-unity-driver.rst index 54da87931f..85e6b46d16 100644 --- a/doc/source/configuration/shared-file-systems/drivers/dell-emc-unity-driver.rst +++ b/doc/source/configuration/shared-file-systems/drivers/dell-emc-unity-driver.rst @@ -11,68 +11,51 @@ The Unity plug-in manages the Unity system to provide shared filesystems. The EMC driver framework with the Unity plug-in is referred to as the Unity driver in this document. -This driver performs the operations on Unity through RESTful APIs. Each back -end manages one Storage Processor of Unity. Configure multiple Shared File -Systems service back ends to manage multiple Unity systems. +This driver performs the operations on Unity through RESTful APIs. Each backend +manages one Storage Processor of Unity. Configure multiple Shared File +Systems service backends to manage multiple Unity systems. Requirements -~~~~~~~~~~~~ +------------ - Unity OE 4.1.x or higher. - - StorOps 1.1.0 or higher is installed on Manila node. - - Following licenses are activated on Unity: - - CIFS/SMB Support - - - Network File System (NFS) - - - Thin Provisioning - - - Fiber Channel (FC) - - - Internet Small Computer System Interface (iSCSI) + * CIFS/SMB Support + * Network File System (NFS) + * Thin Provisioning + * Fiber Channel (FC) + * Internet Small Computer System Interface (iSCSI) Supported shared filesystems and operations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------- -The driver supports CIFS and NFS shares. +In detail, users are allowed to do following operation with EMC Unity +Storage Systems. -The following operations are supported: - -- Create a share. - -- Delete a share. - -- Allow share access. - -- Deny share access. - -- Create a snapshot. - -- Delete a snapshot. - -- Create a share from a snapshot. - -- Extend a share. - -- Shrink a share. - -- Revert a share to a snapshot. +* Create/delete a NFS share. +* Create/delete a CIFS share. +* Extend the size of a share. +* Shrink the size of a share. +* Modify the host access privilege of a NFS share. +* Modify the user access privilege of a CIFS share. +* Create/Delete snapshot of a share. +* Create a new share from snapshot. +* Revert a share to a snapshot. -Supported network types -~~~~~~~~~~~~~~~~~~~~~~~ +Supported Network Topologies +---------------------------- -- ``Flat`` +* Flat This type is fully supported by Unity share driver, however flat networks are restricted due to the limited number of tenant networks that can be created from them. -- ``VLAN`` +* VLAN We recommend this type of network topology in Manila. In most use cases, VLAN is used to isolate the different tenants and provide @@ -80,15 +63,137 @@ Supported network types administrator needs to set a slot connected with Unity Ethernet port in ``Trunk`` mode or allow multiple VLANs from the slot. -- ``VXLAN`` +* VXLAN Unity native VXLAN is still unavailable. However, with the `HPB `_ (Hierarchical Port Binding) in Networking and Shared file system services, it is possible that Unity co-exists with VXLAN enabled network environment. +Pre-Configurations +------------------ + +On Manila Node +~~~~~~~~~~~~~~~ + +Python library ``storops`` is required to run Unity driver. +Install it with the ``pip`` command. +You may need root privilege to install python libraries. + +.. code-block:: console + + pip install storops + + +On Unity System +~~~~~~~~~~~~~~~~ + +#. Configure system level NTP server. + + Open ``Unisphere`` of your Unity system and navigate to: + + .. code-block:: console + + Unisphere -> Settings -> Management -> System Time and NTP + + Select ``Enable NTP synchronization`` and add your NTP server(s). + + The time on the Unity system and the Active Directory domains + used in security services should be in sync. We recommend + using the same NTP server on both the Unity system and Active + Directory domains. + +#. Configure system level DNS server. + + Open ``Unisphere`` of your Unity system and navigate to: + + .. code-block:: console + + Unisphere -> Settings -> Management -> DNS Server + + Select ``Configure DNS server address manually`` and add your DNS server(s). + + +Backend configurations +---------------------- + +Following configurations need to be configured in `/etc/manila/manila.conf` +for the Unity driver. + +.. code-block:: ini + + share_driver = manila.share.drivers.dell_emc.driver.EMCShareDriver + emc_share_backend = unity + emc_nas_server = + emc_nas_login = + emc_nas_password = + unity_server_meta_pool = + unity_share_data_pools = + unity_ethernet_ports = + driver_handles_share_servers = True/False + unity_share_server = + +- `emc_share_backend` + The plugin name. Set it to `unity` for the Unity driver. + +- `emc_nas_server` + The management IP for Unity. + +- `unity_server_meta_pool` + The name of the pool to persist the meta-data of NAS server. + This option is required. + +- `unity_share_data_pools` + Comma separated list specifying the name of the pools to be used + by this backend. Do not set this option if all storage pools + on the system can be used. + Wild card character is supported. + + Examples: + + .. code-block:: ini + + # Only use pool_1 + unity_share_data_pools = pool_1 + # Only use pools whose name stars from pool_ + unity_share_data_pools = pool_* + # Use all pools on Unity + unity_share_data_pools = * + +- `unity_ethernet_ports` + Comma separated list specifying the ethernet ports of Unity system + that can be used for share. Do not set this option if all ethernet ports + can be used. + Wild card character is supported. Both the normal ethernet port and link + aggregation port can be used by Unity share driver. + + + Examples: + + .. code-block:: ini + + # Only use spa_eth1 + unity_ethernet_ports = spa_eth1 + # Use port whose name stars from spa_ + unity_ethernet_ports = spa_* + # Use all Link Aggregation ports + unity_ethernet_ports = sp*_la_* + # Use all available ports + unity_ethernet_ports = * + +- `driver_handles_share_servers` + Unity driver requires this option to be as `True` or `False`. + Need to set `unity_share_server` when the value is `False`. + +- `unity_share_server` + One of NAS server names in Unity, it is used for share creation when + the driver is in `DHSS=False` mode. + +Restart of :term:`manila-share` service is needed for the configuration changes to take +effect. + Supported MTU size -~~~~~~~~~~~~~~~~~~ +------------------ Unity currently only supports 1500 and 9000 as the mtu size, the user can change the above mtu size from Unity Unisphere: @@ -110,7 +215,7 @@ into two parts: #. The driver is able to connect Unity management interface using its IPv6 address. Pre-Configurations for IPv6 support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------- The following parameters need to be configured in `/etc/manila/manila.conf` for the Unity driver: @@ -126,7 +231,7 @@ settings of Unity GUI for Unity and specify the address in `/etc/manila/manila.c emc_nas_server = Supported share creation in mode that driver does not create and destroy share servers (DHSS=False) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------------------------------------------------------------------- To create a file share in this mode, you need to: @@ -167,7 +272,7 @@ create snapshots on shares of this share type. The feature is divided into two p 2. The driver is able to create share from snapshot. Pre-Configurations for Snapshot support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------- The following extra specifications need to be configured with share type. @@ -188,7 +293,7 @@ Or you can update already existing share type with command: manila type-key ${share_type_name} set create_share_from_snapshot_support=True To snapshot a share and create share from the snapshot -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------------ Firstly, you need create a share from share type that has extra specifications(snapshot_support=True, create_share_from_snapshot_support=True). Then snapshot the share with command: @@ -205,152 +310,18 @@ Use command: manila create nfs 1 --name ${target_share_name} --metadata source=snapshot --description " " --snapshot-id ${source_snapshot_id} Supported security services -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- Unity share driver provides ``IP`` based authentication method support for ``NFS`` shares and ``user`` based authentication method for ``CIFS`` shares respectively. For ``CIFS`` share, Microsoft Active Directory is the only -supported security services. - -Pre-configurations -~~~~~~~~~~~~~~~~~~ - -On manila node --------------- - -Python library ``storops`` is required to run Unity driver. -Install it with the ``pip`` command. -You may need root privilege to install python libraries. - -.. code-block:: console - - pip install storops - -On Unity system ---------------- - -#. Configure system level NTP server. - - Open ``Unisphere`` of your Unity system and navigate to: - - .. code-block:: console - - Unisphere -> Settings -> Management -> System Time and NTP - - Select ``Enable NTP synchronization`` and add your NTP server(s). - - The time on the Unity system and the Active Directory domains - used in security services should be in sync. We recommend - using the same NTP server on both the Unity system and Active - Directory domains. - -#. Configure system level DNS server. - - Open ``Unisphere`` of your Unity system and navigate to: - - .. code-block:: console - - Unisphere -> Settings -> Management -> DNS Server - - Select ``Configure DNS server address manually`` and add your DNS server(s). - - -Back end configurations -~~~~~~~~~~~~~~~~~~~~~~~ - -Following configurations need to be configured in ``/etc/manila/manila.conf`` -for the Unity driver. - -.. code-block:: ini - - share_driver = manila.share.drivers.dell_emc.driver.EMCShareDriver - emc_share_backend = unity - emc_nas_server = - emc_nas_login = - emc_nas_password = - unity_server_meta_pool = - unity_share_data_pools = - unity_ethernet_ports = - driver_handles_share_servers = True/False - unity_share_server = - -- ``emc_share_backend`` - The plugin name. Set it to `unity` for the Unity driver. - -- ``emc_nas_server`` - The management IP for Unity. - -- ``emc_nas_login`` - The user with administrator privilege. - -- ``emc_nas_password`` - Password for the user. - -- ``unity_server_meta_pool`` - The name of the pool to persist the meta-data of NAS server. - This option is required. - -- ``unity_share_data_pools`` - Comma separated list specifying the name of the pools to be used - by this back end. Do not set this option if all storage pools - on the system can be used. - Wild card character is supported. - - Examples: - - .. code-block:: ini - - # Only use pool_1 - unity_share_data_pools = pool_1 - # Only use pools whose name stars from pool_ - unity_share_data_pools = pool_* - # Use all pools on Unity - unity_share_data_pools = * - -- ``unity_ethernet_ports`` - Comma separated list specifying the ethernet ports of Unity system - that can be used for share. Do not set this option if all ethernet ports - can be used. - Wild card character is supported. Both the normal ethernet port and link - aggregation port can be used by Unity share driver. - - - Examples: - - .. code-block:: ini - - # Only use spa_eth1 - unity_ethernet_ports = spa_eth1 - # Use port whose name stars from spa_ - unity_ethernet_ports = spa_* - # Use all Link Aggregation ports - unity_ethernet_ports = sp*_la_* - # Use all available ports - unity_ethernet_ports = * - - - .. note:: - - Refer to :ref:`unity_file_io_load_balance` for performance - impact. - -- ``driver_handles_share_servers`` - Unity driver requires this option to be as ``True`` or ``False``. - Need to set ``unity_share_server`` when the value is ``False``. - -- ``unity_share_server`` - One of NAS server names in Unity, it is used for share creation when - the driver is in ``DHSS=False`` mode. - -Restart of ``manila-share`` service is needed for the configuration -changes to take effect. - +supported security service. .. _unity_file_io_load_balance: IO Load balance -~~~~~~~~~~~~~~~ +--------------- The Unity driver automatically distributes the file interfaces per storage processor based on the option ``unity_ethernet_ports``. This balances IO @@ -362,20 +333,49 @@ balanced ports per storage processor. For example: # Use eth2 from both SPs unity_ethernet_ports = spa_eth2, spb_eth2 - Restrictions -~~~~~~~~~~~~ +------------ The Unity driver has following restrictions. - EMC Unity does not support the same IP in different VLANs. +- Only IP access type is supported for NFS. +- Only user access type is supported for CIFS. -- Only Active Directory security service is supported and it is - required to create CIFS shares. + +API Implementations +------------------- + +Following driver features are implemented in the plugin. + +* create_share: Create a share and export it based on the protocol used + (NFS or CIFS). +* create_share_from_snapshot: Create a share from a snapshot - clone a + snapshot. +* delete_share: Delete a share. +* extend_share: Extend the maximum size of a share. +* shrink_share: Shrink the minimum size of a share. +* create_snapshot: Create a snapshot for the specified share. +* delete_snapshot: Delete the snapshot of the share. +* update_access: recover, add or delete user/host access to a share. +* allow_access: Allow access (read write/read only) of a user to a + CIFS share. Allow access (read write/read only) of a host to a NFS + share. +* deny_access: Remove access (read write/read only) of a user from + a CIFS share. Remove access (read write/read only) of a host from a + NFS share. +* ensure_share: Check whether share exists or not. +* update_share_stats: Retrieve share related statistics from Unity. +* get_network_allocations_number: Returns number of network allocations for + creating VIFs. +* setup_server: Set up and configures share server with given network + parameters. +* teardown_server: Tear down the share server. +* revert_to_snapshot: Revert a share to a snapshot. Driver options -~~~~~~~~~~~~~~ +-------------- Configuration options specific to this driver: