openstack/manila
Code Issues Proposed changes

Merge "[Unity] Sync Unity related Docs"

Browse Source
This commit is contained in:
Zuul 2019-10-12 02:42:07 +00:00 committed by Gerrit Code Review
commit 99d10c72b1
4 changed files with 192 additions and 458 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

266
doc/source/admin/emc_unity_driver.rst
View File

@ -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 = <management IP address of the Unity system>
emc_nas_login = <user with administrator privilege>
emc_nas_password = <password>
unity_server_meta_pool = <pool name>
unity_share_data_pools = <comma separated pool names>
unity_ethernet_ports = <comma separated ports list>
driver_handles_share_servers = True/False
unity_share_server = <name of NAS server in Unity system>
- `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:

2
doc/source/admin/index.rst
View File

@ -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

2
doc/source/admin/share_back_ends_feature_support_mapping.rst
View File

@ -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 | \- |
+----------------------------------------+-----------+------------+--------+-------------+-------------------+--------------------+-----+----------------------------+--------------------+--------------------+--------------+--------------+

380
doc/source/configuration/shared-file-systems/drivers/dell-emc-unity-driver.rst
View File

@ -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
<http://specs.openstack.org/openstack/neutron-specs/specs/kilo/ml2-hierarchical-port-binding.html>`_
(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 = <management IP address of the Unity system>
emc_nas_login = <user with administrator privilege>
emc_nas_password = <password>
unity_server_meta_pool = <pool name>
unity_share_data_pools = <comma separated pool names>
unity_ethernet_ports = <comma separated ports list>
driver_handles_share_servers = True/False
unity_share_server = <name of NAS server in Unity system>
- `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 = <IPv6 address>
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 = <management IP address of the Unity system>
emc_nas_login = <user with administrator privilege>
emc_nas_password = <password>
unity_server_meta_pool = <pool name>
unity_share_data_pools = <comma separated pool names>
unity_ethernet_ports = <comma separated ports list>
driver_handles_share_servers = True/False
unity_share_server = <name of NAS server in Unity system>
- ``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: