e3873225d7
Switch to using config-table directive. Change-Id: I5fb17c6cf730a6c5c0149b60ec66af73fc24bab8
301 lines
11 KiB
ReStructuredText
301 lines
11 KiB
ReStructuredText
=======================================
|
|
Oracle ZFS Storage Appliance NFS driver
|
|
=======================================
|
|
|
|
The Oracle ZFS Storage Appliance (ZFSSA) NFS driver enables the ZFSSA to
|
|
be used seamlessly as a block storage resource. The driver enables you
|
|
to create volumes on a ZFS share that is NFS mounted.
|
|
|
|
Requirements
|
|
~~~~~~~~~~~~
|
|
|
|
Oracle ZFS Storage Appliance Software version ``2013.1.2.0`` or later.
|
|
|
|
Supported operations
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
- Create, delete, attach, detach, manage, and unmanage volumes.
|
|
|
|
- Create and delete snapshots.
|
|
|
|
- Create a volume from a snapshot.
|
|
|
|
- Extend a volume.
|
|
|
|
- Copy an image to a volume.
|
|
|
|
- Copy a volume to an image.
|
|
|
|
- Clone a volume.
|
|
|
|
- Volume migration.
|
|
|
|
- Local cache of a bootable volume
|
|
|
|
Appliance configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Appliance configuration using the command-line interface (CLI) is
|
|
described below. To access the CLI, ensure SSH remote access is enabled,
|
|
which is the default. You can also perform configuration using the
|
|
browser user interface (BUI) or the RESTful API. Please refer to the
|
|
`Oracle ZFS Storage Appliance
|
|
documentation <http://www.oracle.com/technetwork/documentation/oracle-unified-ss-193371.html>`__
|
|
for details on how to configure the Oracle ZFS Storage Appliance using
|
|
the BUI, CLI, and RESTful API.
|
|
|
|
#. Log in to the Oracle ZFS Storage Appliance CLI and enable the REST
|
|
service. REST service needs to stay online for this driver to function.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:>configuration services rest enable
|
|
|
|
#. Create a new storage pool on the appliance if you do not want to use an
|
|
existing one. This storage pool is named ``'mypool'`` for the sake of this
|
|
documentation.
|
|
|
|
#. Create a new project and share in the storage pool (``mypool``) if you do
|
|
not want to use existing ones. This driver will create a project and share
|
|
by the names specified in the ``cinder.conf`` file, if a project and share
|
|
by that name does not already exist in the storage pool (``mypool``).
|
|
The project and share are named ``NFSProject`` and ``nfs_share``' in the
|
|
sample ``cinder.conf`` file as entries below.
|
|
|
|
#. To perform driver operations, create a role with the following
|
|
authorizations:
|
|
|
|
.. code-block:: bash
|
|
|
|
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, allow_changeAccessProps=true, allow_changeProtocolProps=true
|
|
|
|
The following examples show how to create a role with authorizations.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:> configuration roles
|
|
zfssa:configuration roles> role OpenStackRole
|
|
zfssa:configuration roles OpenStackRole (uncommitted)> set description="OpenStack NFS Cinder 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=svc
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_administer=true
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_restart=true
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_configure=true
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> commit
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:> configuration roles OpenStackRole authorizations> set scope=nas
|
|
|
|
The following properties need to be set when the scope of this role needs to
|
|
be limited to a pool (``mypool``), a project (``NFSProject``) and a share
|
|
(``nfs_share``) created in the steps above. This will prevent the user
|
|
assigned to this role from being used to modify other pools, projects and
|
|
shares.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set pool=mypool
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set project=NFSProject
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set share=nfs_share
|
|
|
|
#. The following properties only need to be set when a share and project has
|
|
not been created following the steps above and wish to allow the driver to
|
|
create them for you.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_createProject=true
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_createShare=true
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_clone=true
|
|
zfssa:configuration roles OpenStackRole auth (uncommitted)> set allow_changeSpaceProps=true
|
|
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
|
|
the user.
|
|
|
|
The following example shows how to create a new user and assign the new
|
|
role to the user.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:> configuration users
|
|
zfssa:configuration users> user cinder
|
|
zfssa:configuration users cinder (uncommitted)> set fullname="OpenStack Cinder Driver"
|
|
zfssa:configuration users cinder (uncommitted)> set initial_password=12345
|
|
zfssa:configuration users cinder (uncommitted)> commit
|
|
zfssa:configuration users> select cinder set roles=OpenStackRole
|
|
|
|
#. Ensure that NFS and HTTP services on the appliance are online. Note the
|
|
HTTPS port number for later entry in the cinder service configuration file
|
|
(``cinder.conf``). This driver uses WebDAV over HTTPS to create snapshots
|
|
and clones of volumes, and therefore needs to have the HTTP service online.
|
|
|
|
The following example illustrates enabling the services and showing their
|
|
properties.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:> configuration services nfs
|
|
zfssa:configuration services nfs> enable
|
|
zfssa:configuration services nfs> show
|
|
Properties:
|
|
<status>= online
|
|
...
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:configuration services http> enable
|
|
zfssa:configuration services http> show
|
|
Properties:
|
|
<status>= online
|
|
require_login = true
|
|
protocols = http/https
|
|
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.
|
|
|
|
.. note::
|
|
|
|
For better performance and reliability, it is recommended to configure a
|
|
separate subnet exclusively for data traffic in your cloud environment.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:> configuration net interfaces
|
|
zfssa:configuration net interfaces> select igbx
|
|
zfssa:configuration net interfaces igbx> set admin=false
|
|
zfssa:configuration net interfaces igbx> commit
|
|
|
|
#. For clustered controller systems, the following verification is required in
|
|
addition to the above steps. Skip this step if a standalone system is used.
|
|
|
|
.. code-block:: console
|
|
|
|
zfssa:> configuration cluster resources list
|
|
|
|
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 both the network interface used for management and data, and the
|
|
storage pool belong to the same head.
|
|
|
|
.. note::
|
|
|
|
There will be a short service interruption during failback/takeover, but
|
|
once the process is complete, the driver should be able to access the
|
|
ZFSSA for data as well as for management.
|
|
|
|
Cinder service configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
#. Define the following required properties in the ``cinder.conf``
|
|
configuration file:
|
|
|
|
.. code-block:: ini
|
|
|
|
volume_driver = cinder.volume.drivers.zfssa.zfssanfs.ZFSSANFSDriver
|
|
san_ip = myhost
|
|
san_login = username
|
|
san_password = password
|
|
zfssa_data_ip = mydata
|
|
zfssa_nfs_pool = mypool
|
|
|
|
.. note::
|
|
|
|
Management interface ``san_ip`` can be used instead of ``zfssa_data_ip``,
|
|
but it is not recommended.
|
|
|
|
#. You can also define the following additional properties in the
|
|
``cinder.conf`` configuration file:
|
|
|
|
.. code:: ini
|
|
|
|
zfssa_nfs_project = NFSProject
|
|
zfssa_nfs_share = nfs_share
|
|
zfssa_nfs_mount_options =
|
|
zfssa_nfs_share_compression = off
|
|
zfssa_nfs_share_logbias = latency
|
|
zfssa_https_port = 443
|
|
|
|
.. note::
|
|
|
|
The driver does not use the file specified in the ``nfs_shares_config``
|
|
option.
|
|
|
|
ZFSSA local cache
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
The local cache feature enables ZFSSA drivers to serve the usage of
|
|
bootable volumes significantly better. With the feature, the first
|
|
bootable volume created from an image is cached, so that subsequent
|
|
volumes can be created directly from the cache, instead of having image
|
|
data transferred over the network multiple times.
|
|
|
|
The following conditions must be met in order to use ZFSSA local cache
|
|
feature:
|
|
|
|
- A storage pool needs to be configured.
|
|
|
|
- REST and NFS services need to be turned on.
|
|
|
|
- On an OpenStack controller, ``cinder.conf`` needs to contain
|
|
necessary properties used to configure and set up the ZFSSA NFS
|
|
driver, including the following new properties:
|
|
|
|
zfssa_enable_local_cache
|
|
(True/False) To enable/disable the feature.
|
|
|
|
zfssa_cache_directory
|
|
The directory name inside zfssa_nfs_share where cache volumes
|
|
are stored.
|
|
|
|
Every cache volume has two additional properties stored as WebDAV
|
|
properties. It is important that they are not altered outside of Block
|
|
Storage when the driver is in use:
|
|
|
|
image_id
|
|
stores the image id as in Image service.
|
|
|
|
updated_at
|
|
stores the most current timestamp when the image is
|
|
updated in Image service.
|
|
|
|
Driver options
|
|
~~~~~~~~~~~~~~
|
|
|
|
The Oracle ZFS Storage Appliance NFS driver supports these options:
|
|
|
|
.. config-table::
|
|
:config-target: ZFS Storage Appliance NFS
|
|
|
|
cinder.volume.drivers.zfssa.zfssanfs
|
|
|
|
This driver shares additional NFS configuration options with the generic
|
|
NFS driver. For a description of these, see :ref:`cinder-storage_nfs`.
|