diff --git a/doc/source/devref/driver_requirements.rst b/doc/source/devref/driver_requirements.rst new file mode 100644 index 0000000000..76cb9df7aa --- /dev/null +++ b/doc/source/devref/driver_requirements.rst @@ -0,0 +1,200 @@ +.. + Copyright (c) 2015 Hitachi Data Systems + 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. + +Manila minimum requirements and features since Mitaka +===================================================== + +In order for a driver to be accepted into Manila code base, there are certain +minimum requirements and features that must be met, in order to ensure +interoperability and standardized Manila functionality among cloud providers. + +At least one driver mode (:term:`DHSS` true/false) +-------------------------------------------------- + +Driver modes determine if the driver is managing network resources +(:term:`DHSS` = true) in an automated way, in order to segregate tenants and +private networks by making use of Manila Share Networks, or if it is up to the +administrator to manually configure all networks (:term:`DHSS` = false) and be +responsible for segregation, if that is desired. At least one driver mode must +be supported. In :term:`DHSS` = true mode, Share Server entities are used, so +the driver must implement functions that setup and teardown such servers. + +At least one file system sharing protocol +----------------------------------------- + +In order to serve shares as a shared file system service, the driver must +support at least one file system sharing protocol, which can be a new protocol +or one of the currently supported protocols. The current list of supported +protocols is as follows: + +- NFS +- CIFS +- GlusterFS +- HDFS + +Access rules +------------ + +Access rules control how shares are accessible, by whom, and what the level of +access is. Access rule operations include allowing access and denying access +to a given share. The authentication type should be based on IP, User and/or +Certificate. Drivers must support read-write and read-only access levels for each +supported protocol, either through individual access rules or separate export +locations. + +Shares +------ + +Share servicing is the core functionality of a shared file system service, so +a driver must be able to create and delete shares. + +Share extending +--------------- + +In order to best satisfy cloud service requirements, shares must be elastic, so +drivers must implement a share extend function that allows shares' size to be +increased. + +Capabilities +------------ + +In order for Manila to function accordingly to the driver being used, the +driver must provide a set of information to Manila, known as capabilities, as +follows: + +- share_backend_name: a name for the backend; +- driver_handles_share_servers: driver mode, whether this driver instance + handles share servers, possible values are true or false; +- vendor_name: driver vendor name; +- driver_version: current driver instance version; +- storage_protocol: list of shared file system protocols supported by this + driver instance; +- total_capacity_gb: total amount of storage space provided, in GB; +- free_capacity_gb: amount of storage space available for use, in GB; +- reserved_percentage: percentage of total storage space to be kept from being + used. + +Certain features, if supported by drivers, need to be reported in order to +function correctly in Manila, such as: + +- dedupe: whether the backend supports deduplication; +- compression: whether the backend supports compressed shares; +- thin_provisioning: whether the backend is overprovisioning shares; +- pools: list of storage pools managed by this driver instance. + +.. note:: for more information please see http://docs.openstack.org/developer/manila/devref/capabilities_and_extra_specs.html + +Continuous Integration systems +------------------------------ + +Every driver vendor must supply a CI system that tests its drivers +continuously for each patch submitted to OpenStack gerrit. This allows for +better QA and quicker response and notification for driver vendors when a +patch submitted affects an existing driver. The CI system must run all +applicable tempest tests, test all patches Jenkins has posted +1 and post its +test results. + +.. note:: for more information please see http://docs.openstack.org/infra/system-config/third_party.html + +Unit tests +---------- + +All drivers submitted must be contemplated with unit tests covering at least +90% of the code, preferably 100% if possible. Unit tests must use mock +framework and be located in-tree using a structure that mirrors the functional +code, such as directory names and filenames. See template below: + + :: + + manila/[tests/]path/to/brand/new/[test_]driver.py + +Documentation +------------- + +Drivers submitted must provide and maintain related documentation on +openstack-manuals, containing instructions on how to properly install and +configure. The intended audience for this manual is cloud operators and +administrators. Also, driver maintainers must update the Manila share features +support mapping documentation found at +http://docs.openstack.org/developer/manila/devref/share_back_ends_feature_support_mapping.html + + +Manila optional requirements and features since Mitaka +====================================================== + +Additional to the minimum required features supported by Manila, other optional +features can be supported by drivers as they are already supported in Manila +and can be accessed through the API. + +Snapshots +--------- + +Share Snapshots allow for data respective to a particular point in time to be +saved in order to be used later. In Manila API, share snapshots taken can only +be restored by creating new shares from them, thus the original share remains +unaffected. If Snapshots are supported by drivers, they must be +crash-consistent. + +Managing/Unmanaging shares +-------------------------- + +If :term:`DHSS` = false mode is used, then drivers may implement a function +that supports reading existing shares in the backend that were not created by +Manila. After the previously existing share is registered in Manila, it is +completely controlled by Manila and should not be handled externally anymore. +Additionally, a function that de-registers such shares from Manila but do +not delete from backend may also be supported. + +Share shrinking +--------------- + +Manila API supports share shrinking, thus a share can be shrunk in a similar +way it can be extended, but the driver is responsible for making sure no data +is compromised. + +Share ensuring +-------------- + +In some situations, such as when the driver is restarted, Manila attempts to +perform maintenance on created shares, on the purpose of ensuring previously +created shares are available and being serviced correctly. The driver can +implement this function by checking shares' status and performing maintenance +operations if needed, such as re-exporting. + + +Manila experimental features since Mitaka +========================================= + +Some features are initially released as experimental and can be accessed by +including specific additional HTTP Request headers. Those features are not +recommended for production cloud environments while in experimental stage. + +Share Migration +--------------- + +Shares can be migrated between different backends and pools. Manila implements +migration using an approach that works for any manufacturer, but driver vendors +can implement a better optimized migration function for when migration involves +backends or pools related to the same vendor. + +Consistency Groups +------------------ + +Shares can be created within Consistency Groups in order to guarantee snapshot +consistency of multiple shares. In order to make use of this feature, driver +vendors must report this capability and implement its functions to work +according to the backend, so the feature can be properly invoked through +Manila API. \ No newline at end of file diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index 2c0ee5e59e..50df89f9d9 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -40,6 +40,7 @@ Background Concepts for Manila threading i18n rpc + driver_requirements pool-aware-manila-scheduler Other Resources