diff --git a/doc/config-ref-rst/source/conf.py b/doc/config-ref-rst/source/conf.py index 8af35ff02d..3c598d0d01 100644 --- a/doc/config-ref-rst/source/conf.py +++ b/doc/config-ref-rst/source/conf.py @@ -21,7 +21,9 @@ # serve to show the default. import os -# import sys +import sys + +sys.path.append(os.path.dirname(__file__)) import openstackdocstheme @@ -38,7 +40,7 @@ import openstackdocstheme # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -# extensions = ['sphinx.ext.todo'] +extensions = ['ext.remote'] # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] diff --git a/doc/config-ref-rst/source/ext/__init__.py b/doc/config-ref-rst/source/ext/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/config-ref-rst/source/ext/remote.py b/doc/config-ref-rst/source/ext/remote.py new file mode 100644 index 0000000000..9331710053 --- /dev/null +++ b/doc/config-ref-rst/source/ext/remote.py @@ -0,0 +1,32 @@ +#!/usr/bin/env python + +# 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. + +import requests +from sphinx.directives import code + + +class RemoteCodeBlock(code.CodeBlock): + def run(self): + + r = requests.get(self.content[0]) + if r.status_code != 200: + raise Exception + + self.content = [r.text] + + return super(RemoteCodeBlock, self).run() + + +def setup(app): + app.add_directive('remote-code-block', RemoteCodeBlock) diff --git a/doc/config-ref-rst/source/shared-file-systems.rst b/doc/config-ref-rst/source/shared-file-systems.rst index 17811b2613..4feced022c 100644 --- a/doc/config-ref-rst/source/shared-file-systems.rst +++ b/doc/config-ref-rst/source/shared-file-systems.rst @@ -2,6 +2,14 @@ Shared File Systems =================== +The Shared File Systems service works with many different drivers that +you can configure by using these instructions. + .. toctree:: + shared-file-systems/overview.rst + shared-file-systems/drivers.rst + shared-file-systems/log-files.rst + shared-file-systems/sample-configuration-files.rst + shared-file-systems/misc.rst tables/conf-changes/manila.rst diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers.rst b/doc/config-ref-rst/source/shared-file-systems/drivers.rst new file mode 100644 index 0000000000..7feae007f6 --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers.rst @@ -0,0 +1,29 @@ +============= +Share drivers +============= + +.. toctree:: + + drivers/emc-isilon-driver.rst + drivers/emc-vnx-driver.rst + drivers/generic-driver.rst + drivers/glusterfs-driver.rst + drivers/glusterfs-native-driver.rst + drivers/hdfs-native-driver.rst + drivers/hpe-3par-share-driver.rst + drivers/huawei-nas-driver.rst + drivers/ibm-gpfs-driver.rst + drivers/netapp-cluster-mode-driver.rst + + +To use different share drivers for the Shared File Systems service, use the +parameters described in these sections. + +The share drivers are included in the `Shared File Systems repository +`_. +To set a share driver, use the ``share_driver`` flag. For example, to +use the generic reference driver: + +.. code-block:: ini + + share_driver = manila.share.drivers.generic.GenericShareDriver diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/emc-isilon-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/emc-isilon-driver.rst new file mode 100644 index 0000000000..5e2e925c39 --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/emc-isilon-driver.rst @@ -0,0 +1,3 @@ +================= +EMC Isilon driver +================= diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/emc-vnx-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/emc-vnx-driver.rst new file mode 100644 index 0000000000..3f964a764a --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/emc-vnx-driver.rst @@ -0,0 +1,3 @@ +============== +EMC VNX driver +============== diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/generic-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/generic-driver.rst new file mode 100644 index 0000000000..c30fdb92fe --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/generic-driver.rst @@ -0,0 +1,3 @@ +======================================= +Generic approach for share provisioning +======================================= diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/glusterfs-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/glusterfs-driver.rst new file mode 100644 index 0000000000..4a7118c634 --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/glusterfs-driver.rst @@ -0,0 +1,3 @@ +================ +GlusterFS driver +================ diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/glusterfs-native-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/glusterfs-native-driver.rst new file mode 100644 index 0000000000..c3845972aa --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/glusterfs-native-driver.rst @@ -0,0 +1,3 @@ +======================= +GlusterFS native driver +======================= diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/hdfs-native-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/hdfs-native-driver.rst new file mode 100644 index 0000000000..91e93d96fb --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/hdfs-native-driver.rst @@ -0,0 +1,3 @@ +================== +HDFS native driver +================== diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/hpe-3par-share-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/hpe-3par-share-driver.rst new file mode 100644 index 0000000000..34c0525469 --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/hpe-3par-share-driver.rst @@ -0,0 +1,3 @@ +=============== +HPE 3PAR driver +=============== diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/huawei-nas-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/huawei-nas-driver.rst new file mode 100644 index 0000000000..3b3f692d2c --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/huawei-nas-driver.rst @@ -0,0 +1,3 @@ +============= +Huawei driver +============= diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/ibm-gpfs-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/ibm-gpfs-driver.rst new file mode 100644 index 0000000000..648522be13 --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/ibm-gpfs-driver.rst @@ -0,0 +1,3 @@ +=============== +IBM GPFS driver +=============== diff --git a/doc/config-ref-rst/source/shared-file-systems/drivers/netapp-cluster-mode-driver.rst b/doc/config-ref-rst/source/shared-file-systems/drivers/netapp-cluster-mode-driver.rst new file mode 100644 index 0000000000..3dde6f5889 --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/drivers/netapp-cluster-mode-driver.rst @@ -0,0 +1,3 @@ +================================== +NetApp Clustered Data ONTAP driver +================================== diff --git a/doc/config-ref-rst/source/shared-file-systems/log-files.rst b/doc/config-ref-rst/source/shared-file-systems/log-files.rst new file mode 100644 index 0000000000..798ab9d29c --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/log-files.rst @@ -0,0 +1,27 @@ +===================================== +Log files used by Shared File Systems +===================================== + +The corresponding log file of each Shared File Systems service is stored +in the ``/var/log/manila/`` directory of the host on which each service +runs. + +.. list-table:: Log files used by Shared File Systems services + :header-rows: 1 + + * - Log file + - Service/interface (for CentOS, Fedora, openSUSE, Red Hat Enterprise + Linux, and SUSE Linux Enterprise) + - Service/interface (for Ubuntu and Debian) + * - ``api.log`` + - ``openstack-manila-api`` + - ``manila-api`` + * - ``manila-manage.log`` + - ``manila-manage`` + - ``manila-manage`` + * - ``scheduler.log`` + - ``openstack-manila-scheduler`` + - ``manila-scheduler`` + * - ``share.log`` + - ``openstack-manila-share`` + - ``manila-share`` diff --git a/doc/config-ref-rst/source/shared-file-systems/misc.rst b/doc/config-ref-rst/source/shared-file-systems/misc.rst new file mode 100644 index 0000000000..425c71b1bb --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/misc.rst @@ -0,0 +1,69 @@ +===================== +Configuration options +===================== + +These following options can be set in the ``manila.conf`` file. + +.. include:: ../tables/manila-amqp.rst + +.. include:: ../tables/manila-api.rst + +.. include:: ../tables/manila-auth_token.rst + +.. include:: ../tables/manila-auth.rst + +.. include:: ../tables/manila-ca.rst + +.. include:: ../tables/manila-common.rst + +.. include:: ../tables/manila-compute.rst + +.. include:: ../tables/manila-cors.rst + +.. include:: ../tables/manila-database.rst + +.. include:: ../tables/manila-emc.rst + +.. include:: ../tables/manila-ganesha.rst + +.. include:: ../tables/manila-glusterfs.rst + +.. include:: ../tables/manila-gpfs.rst + +.. include:: ../tables/manila-hdfs.rst + +.. include:: ../tables/manila-hds_hnas.rst + +.. include:: ../tables/manila-hp3par.rst + +.. include:: ../tables/manila-huawei.rst + +.. include:: ../tables/manila-logging.rst + +.. include:: ../tables/manila-netapp.rst + +.. include:: ../tables/manila-qpid.rst + +.. include:: ../tables/manila-quobyte.rst + +.. include:: ../tables/manila-quota.rst + +.. include:: ../tables/manila-rabbitmq.rst + +.. include:: ../tables/manila-redis.rst + +.. include:: ../tables/manila-rpc.rst + +.. include:: ../tables/manila-san.rst + +.. include:: ../tables/manila-scheduler.rst + +.. include:: ../tables/manila-share.rst + +.. include:: ../tables/manila-storage.rst + +.. include:: ../tables/manila-winrm.rst + +.. include:: ../tables/manila-zeromq.rst + +.. include:: ../tables/manila-zfssa.rst diff --git a/doc/config-ref-rst/source/shared-file-systems/overview.rst b/doc/config-ref-rst/source/shared-file-systems/overview.rst new file mode 100644 index 0000000000..210d9dbfcb --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/overview.rst @@ -0,0 +1,83 @@ +=============================================== +Introduction to the Shared File Systems service +=============================================== + +The Shared File Systems service provides shared file systems that +Compute instances can consume. + +The Shared File Systems service provides: + +- ``manila-api``. A WSGI app that authenticates and routes requests + throughout the Shared File Systems service. It supports the OpenStack + APIs. + +- ``manila-scheduler``. Schedules and routes requests to the appropriate + share service. The scheduler uses configurable filters and weighers + to route requests. The Filter Scheduler is the default and enables + filters on things like Capacity, Availability Zone, Share Types, and + Capabilities as well as custom filters. + +- ``manila-share``. Manages back-end devices that provide shared file + systems. A manila-share service can run in one of two modes, with or + without handling of share servers. Share servers export file shares + via share networks. When share servers are not used, the networking + requirements are handled outside of Manila. + +The Shared File Systems service contains the following components: + +**Back-end storage devices** + The Shared File Services service requires some form of back-end shared file + system provider that the service is built on. The reference implementation + uses the Block Storage service (Cinder) and a service VM to provide shares. + Additional drivers are used to access shared file systems from a variety of + vendor solutions. + +**Users and tenants (projects)** + The Shared File Systems service can be used by many different cloud + computing consumers or customers (tenants on a shared system), using + role-based access assignments. Roles control the actions that a user is + allowed to perform. In the default configuration, most actions do not + require a particular role unless they are restricted to administrators, but + this can be configured by the system administrator in the appropriate + ``policy.json`` file that maintains the rules. A user's access to manage + particular shares is limited by tenant. Guest access to mount and use shares + is secured by IP and/or user access rules. Quotas used to control resource + consumption across available hardware resources are per tenant. + + For tenants, quota controls are available to limit: + + - The number of shares that can be created. + + - The number of gigabytes that can be provisioned for shares. + + - The number of share snapshots that can be created. + + - The number of gigabytes that can be provisioned for share + snapshots. + + - The number of share networks that can be created. + + You can revise the default quota values with the Shared File Systems + CLI, so the limits placed by quotas are editable by admin users. + +**Shares, snapshots, and share networks** + The basic resources offered by the Shared File Systems service are shares, + snapshots and share networks: + + **Shares** + A share is a unit of storage with a protocol, a size, and an access list. + Shares are the basic primitive provided by Manila. All shares exist on a + backend. Some shares are associated with share networks and share + servers. The main protocols supported are NFS and CIFS, but other + protocols are supported as well. + + **Snapshots** + A snapshot is a point in time copy of a share. Snapshots can only be + used to create new shares (containing the snapshotted data). Shares + cannot be deleted until all associated snapshots are deleted. + + **Share networks** + A share network is a tenant-defined object that informs Manila about the + security and network configuration for a group of shares. Share networks + are only relevant for backends that manage share servers. A share network + contains a security service and network/subnet. diff --git a/doc/config-ref-rst/source/shared-file-systems/sample-configuration-files.rst b/doc/config-ref-rst/source/shared-file-systems/sample-configuration-files.rst new file mode 100644 index 0000000000..2d88b6d731 --- /dev/null +++ b/doc/config-ref-rst/source/shared-file-systems/sample-configuration-files.rst @@ -0,0 +1,49 @@ +============================================== +Shared File Systems sample configuration files +============================================== + +All the files in this section can be found in ``/etc/manila``. + +manila.conf +----------- + +The ``manila.conf`` file is installed in ``/etc/manila`` by default. +When you manually install the Shared File Systems service, the options +in the ``manila.conf`` file are set to default values. + +The ``manila.conf`` file contains most of the options to configure the +Shared File Systems service. + +.. literalinclude:: ../../../common/samples/manila.conf.sample + :language: ini + +api-paste.ini +------------- + +Use the ``api-paste.ini`` file to configure the Shared File Systems API +service. + +.. remote-code-block:: ini + + https://git.openstack.org/cgit/openstack/manila/plain/etc/manila/api-paste.ini + +policy.json +----------- + +The ``policy.json`` file defines additional access controls that apply +to the Shared File Systems service. + +.. remote-code-block:: json + + https://git.openstack.org/cgit/openstack/manila/plain/etc/manila/policy.json + +rootwrap.conf +------------- + +The ``rootwrap.conf`` file defines configuration values used by the +``rootwrap`` script when the Shared File Systems service must escalate +its privileges to those of the root user. + +.. remote-code-block:: ini + + https://git.openstack.org/cgit/openstack/manila/plain/etc/manila/rootwrap.conf