Update Oracle ZFSSA drivers documentation

Create a page for Oracle ZFSSA Manila driver Update Oracle ZFSSA NFS and iSCSI driver pages Closes-Bug: #1633017 Closes-Bug: #1666336 Change-Id: I298ca6df7c3fc3693c4f7bf45d8833aa37dd5f6a
2017-02-21 06:23:11 -05:00 · 2017-02-21 06:23:11 -05:00 · 513c940578
commit 513c940578
parent b9c3636f66
5 changed files with 180 additions and 3 deletions
--- a/doc/config-reference/source/block-storage/drivers/zfssa-iscsi-driver.rst
+++ b/doc/config-reference/source/block-storage/drivers/zfssa-iscsi-driver.rst
@ -40,6 +40,7 @@ Configuration

      scope=stmf - allow_configure=true
      scope=nas - allow_clone=true, allow_createProject=true, allow_createShare=true, allow_changeSpaceProps=true, allow_changeGeneralProps=true, allow_destroy=true, allow_rollback=true, allow_takeSnap=true
+      scope=schema - allow_modify=true

   You can create a role with authorizations as follows:

@ -80,8 +81,11 @@ Configuration
   .. note::

      You can also run this `workflow
-      <https://java.net/projects/solaris-userland/sources/gate/content/components/openstack/cinder/files/zfssa/cinder.akwf>`__
+      <https://openstackci.oracle.com/openstack_docs/zfssa_cinder_workflow.akwf>`__
      to automate the above tasks.
+      Refer to `Oracle documentation
+      <https://docs.oracle.com/cd/E37831_01/html/E52872/godgw.html>`__
+      on how to download, view, and execute a workflow.

 #. Ensure that the ZFSSA iSCSI service is online. If the ZFSSA iSCSI service is
   not online, enable the service by using the BUI, CLI or REST API in the
@ -127,6 +131,33 @@ Configuration

      Do not use management interfaces for ``zfssa_target_interfaces``.

+#. Configure the cluster:
+
+   If a cluster is used as the cinder storage resource, the following
+   verifications are required on your Oracle ZFS Storage Appliance:
+
+   - Verify that both the pool and the network interface are of type
+     singleton and are not locked to the current controller. This
+     approach ensures that the pool and the interface used for data
+     always belong to the active controller, regardless of the current
+     state of the cluster.
+
+   - Verify that the management IP, data IP and storage pool belong to
+     the same head.
+
+   .. note::
+
+      Most configuration settings, including service properties, users, roles,
+      and iSCSI initiator definitions are replicated on both heads
+      automatically. If the driver modifies any of these settings, they will be
+      modified automatically on both heads.
+
+   .. note::
+
+      A short service interruption occurs during failback or takeover,
+      but once the process is complete, the ``cinder-volume`` service should be able
+      to access the pool through the data IP.
+
 ZFSSA assisted volume migration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

--- a/doc/config-reference/source/block-storage/drivers/zfssa-nfs-driver.rst
+++ b/doc/config-reference/source/block-storage/drivers/zfssa-nfs-driver.rst
@ -68,7 +68,7 @@ the BUI, CLI, and RESTful API.
   .. code-block:: none

      scope=svc - allow_administer=true, allow_restart=true, allow_configure=true
-      scope=nas - pool=pool_name, project=project_name, share=share_name, allow_clone=true, allow_createProject=true, allow_createShare=true, allow_changeSpaceProps=true, allow_changeGeneralProps=true, allow_destroy=true, allow_rollback=true, allow_takeSnap=true
+      scope=nas - pool=pool_name, project=project_name, share=share_name, allow_clone=true, allow_createProject=true, allow_createShare=true, allow_changeSpaceProps=true, allow_changeGeneralProps=true, allow_destroy=true, allow_rollback=true, allow_takeSnap=true, allow_changeAccessProps=true, allow_changeProtocolProps=true

   The following examples show how to create a role with authorizations.

@ -119,6 +119,8 @@ the BUI, CLI, and RESTful API.
      zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_destroy=true
      zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_rollback=true
      zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_takeSnap=true
+      zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_changeAccessProps=true
+      zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_changeProtocolProps=true
      zfssa:configuration roles OpenStackRole auth (uncommitted)> commit

 #. Create a new user or modify an existing one and assign the new role to
@ -164,6 +166,15 @@ the BUI, CLI, and RESTful API.
      listen_port = 80
      https_port = 443

+   .. note::
+
+      You can also run this `workflow
+      <https://openstackci.oracle.com/openstack_docs/zfssa_cinder_workflow.akwf>`__
+      to automate the above tasks.
+      Refer to `Oracle documentation
+      <https://docs.oracle.com/cd/E37831_01/html/E52872/godgw.html>`__
+      on how to download, view, and execute a workflow.
+
 #. Create a network interface to be used exclusively for data. An existing
   network interface may also be used. The following example illustrates how to
   make a network interface for data traffic flow only.
--- a/doc/config-reference/source/shared-file-systems/config-options.rst
+++ b/doc/config-reference/source/shared-file-systems/config-options.rst
@ -16,4 +16,3 @@ These options can also be set in the ``manila.conf`` file.
 .. include:: ../tables/manila-share.rst
 .. include:: ../tables/manila-tegile.rst
 .. include:: ../tables/manila-winrm.rst
-.. include:: ../tables/manila-zfssa.rst
--- a/doc/config-reference/source/shared-file-systems/drivers.rst
+++ b/doc/config-reference/source/shared-file-systems/drivers.rst
@ -16,6 +16,7 @@ Share drivers
   drivers/hdfs-native-driver.rst
   drivers/lvm-driver.rst
   drivers/zfs-on-linux-driver.rst
+   drivers/zfssa-manila-driver.rst
   drivers/emc-isilon-driver.rst
   drivers/emc-vnx-driver.rst
   drivers/emc-unity-driver.rst
--- a/doc/config-reference/source/shared-file-systems/drivers/zfssa-manila-driver.rst
+++ b/doc/config-reference/source/shared-file-systems/drivers/zfssa-manila-driver.rst
@ -0,0 +1,135 @@
+===================================
+Oracle ZFS Storage Appliance driver
+===================================
+The Oracle ZFS Storage Appliance driver, version 1.0.0, enables the
+Oracle ZFS Storage Appliance (ZFSSA) to be used seamlessly as a shared
+storage resource for the OpenStack File System service (manila). The driver
+provides the ability to create and manage NFS and CIFS shares
+on the appliance, allowing virtual machines to access the shares
+simultaneously and securely.
+
+Requirements
+~~~~~~~~~~~~
+Oracle ZFS Storage Appliance Software version 2013.1.2.0 or later.
+
+Supported operations
+~~~~~~~~~~~~~~~~~~~~
+
+- Create NFS and CIFS shares.
+- Delete NFS and CIFS shares.
+- Allow or deny IP access to NFS shares.
+- Create snapshots of a share.
+- Delete snapshots of a share.
+- Create share from snapshot.
+
+Restrictions
+~~~~~~~~~~~~
+
+- Access to CIFS shares are open and cannot be changed from manila.
+- Version 1.0.0 of the driver only supports Single SVM networking mode.
+
+Appliance configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Enable RESTful service on the ZFSSA Storage Appliance.
+
+#. Create a new user on the appliance with the following authorizations:
+
+   .. code-block:: none
+
+      scope=stmf - allow_configure=true
+      scope=nas - allow_clone=true, allow_createProject=true, allow_createShare=true, allow_changeSpaceProps=true, allow_changeGeneralProps=true, allow_destroy=true, allow_rollback=true, allow_takeSnap=true
+
+   You can create a role with authorizations as follows:
+
+   .. code-block:: none
+
+      zfssa:> configuration roles
+      zfssa:configuration roles> role OpenStackRole
+      zfssa:configuration roles OpenStackRole (uncommitted)> set description="OpenStack Manila Driver"
+      zfssa:configuration roles OpenStackRole (uncommitted)> commit
+      zfssa:configuration roles> select OpenStackRole
+      zfssa:configuration roles OpenStackRole> authorizations create
+      zfssa:configuration roles OpenStackRole auth (uncommitted)> set scope=stmf
+      zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_configure=true
+      zfssa:configuration roles OpenStackRole auth (uncommitted)> commit
+
+   You can create a user with a specific role as follows:
+
+   .. code-block:: none
+
+      zfssa:> configuration users
+      zfssa:configuration users> user cinder
+      zfssa:configuration users cinder (uncommitted)> set fullname="OpenStack Manila Driver"
+      zfssa:configuration users cinder (uncommitted)> set initial_password=12345
+      zfssa:configuration users cinder (uncommitted)> commit
+      zfssa:configuration users> select cinder set roles=OpenStackRole
+
+#. Create a storage pool.
+
+   An existing pool can also be used if required. You can create a pool
+   as follows:
+
+   .. code-block:: none
+
+      zfssa:> configuration storage
+      zfssa:configuration storage> config pool
+      zfssa:configuration storage verify> set data=2
+      zfssa:configuration storage verify> done
+      zfssa:configuration storage config> done
+
+#. Create a new project.
+
+   You can create a project as follows:
+
+   .. code-block:: none
+
+      zfssa:> shares
+      zfssa:shares> project proj
+      zfssa:shares proj (uncommitted)> commit
+
+#. Create a new or use an existing data IP address.
+
+   You can create an interface as follows:
+
+   .. code-block:: none
+
+      zfssa:> configuration net interfaces ip
+      zfssa:configuration net interfaces ip (uncommitted)> set v4addrs=127.0.0.1/24
+                           v4addrs = 127.0.0.1/24 (uncommitted)
+      zfssa:configuration net interfaces ip (uncommitted)> set links=vnic1
+                             links = vnic1 (uncommitted)
+      zfssa:configuration net interfaces ip (uncommitted)> set admin=false
+                             admin = false (uncommitted)
+      zfssa:configuration net interfaces ip (uncommitted)> commit
+
+   It is required that both interfaces used for data and management are
+   configured properly. The data interface must be different from the
+   management interface.
+
+#. Configure the cluster.
+
+   If a cluster is used as the manila storage resource, the following
+   verifications are required:
+
+   - Verify that both the newly created pool and the network interface are of
+     type singleton and are not locked to the current controller.
+     This approach ensures that the pool and the interface used for data
+     always belong to the active controller, regardless of the current state
+     of the cluster.
+
+   - Verify that the management IP, data IP and storage pool belong to the
+     same head.
+
+   .. note::
+
+      A short service interruption occurs during failback or takeover,
+      but once the process is complete, manila should be able
+      to access the pool through the data IP.
+
+Driver options
+~~~~~~~~~~~~~~
+
+The Oracle ZFSSA driver supports these options:
+
+.. include:: ../../tables/manila-zfssa.rst