336 lines
14 KiB
ReStructuredText
336 lines
14 KiB
ReStructuredText
..
|
|
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
|
|
========================================
|
|
|
|
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
|
|
- MapRFS
|
|
- CephFS
|
|
|
|
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.
|
|
Share driver can use Share type extra-specs (scoped and un-scoped) to serve
|
|
new shares. See :doc:`../admin/capabilities_and_extra_specs` for more
|
|
information. At a minimum your driver must report:
|
|
|
|
|
|
- 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;
|
|
- qos: whether the backend supports quality of service for shares;
|
|
- replication_domain: string specifying a common group name for all backends
|
|
that can replicate between each other;
|
|
- replication_type: string specifying the type of replication supported by
|
|
the driver. Can be one of ('readable', 'writable' or 'dr').
|
|
|
|
Below is an example of drivers with multiple pools. "my" is used as an
|
|
example vendor prefix:
|
|
|
|
::
|
|
|
|
{
|
|
'driver_handles_share_servers': 'False', #\
|
|
'share_backend_name': 'My Backend', # backend level
|
|
'vendor_name': 'MY', # mandatory/fixed
|
|
'driver_version': '1.0', # stats & capabilities
|
|
'storage_protocol': 'NFS_CIFS', #/
|
|
#\
|
|
'my_capability_1': 'custom_val', # "my" optional vendor
|
|
'my_capability_2': True, # stats & capabilities
|
|
#/
|
|
'pools': [
|
|
{'pool_name':
|
|
'thin-dedupe-compression pool', #\
|
|
'total_capacity_gb': 500, # mandatory stats for
|
|
'free_capacity_gb': 230, # pools
|
|
'reserved_percentage': 0, #/
|
|
#\
|
|
'dedupe': True, # common capabilities
|
|
'compression': True, #
|
|
'snapshot_support': True, #
|
|
'create_share_from_snapshot_support': True,
|
|
'revert_to_snapshot_support': True,
|
|
'qos': True, # this backend supports QoS
|
|
'thin_provisioning': True, #
|
|
'max_over_subscription_ratio': 10, # (mandatory for thin)
|
|
'provisioned_capacity_gb': 270, # (mandatory for thin)
|
|
#
|
|
#
|
|
'replication_type': 'dr', # this backend supports
|
|
# replication_type 'dr'
|
|
#/
|
|
'my_dying_disks': 100, #\
|
|
'my_super_hero_1': 'Hulk', # "my" optional vendor
|
|
'my_super_hero_2': 'Spider-Man', # stats & capabilities
|
|
#/
|
|
#\
|
|
# can replicate to other
|
|
'replication_domain': 'asgard', # backends in
|
|
# replication_domain 'asgard'
|
|
#/
|
|
'ipv4_support': True,
|
|
'ipv6_support': True,
|
|
|
|
},
|
|
{'pool_name': 'thick pool',
|
|
'total_capacity_gb': 1024,
|
|
'free_capacity_gb': 1024,
|
|
'qos': False,
|
|
'snapshot_support': True,
|
|
'create_share_from_snapshot_support': False, # this pool does not
|
|
# allow creating
|
|
# shares from
|
|
# snapshots
|
|
'revert_to_snapshot_support': True,
|
|
'reserved_percentage': 0,
|
|
'dedupe': False,
|
|
'compression': False,
|
|
'thin_provisioning': False,
|
|
'replication_type': None,
|
|
'my_dying_disks': 200,
|
|
'my_super_hero_1': 'Batman',
|
|
'my_super_hero_2': 'Robin',
|
|
'ipv4_support': True,
|
|
'ipv6_support': True,
|
|
},
|
|
]
|
|
}
|
|
|
|
|
|
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
|
|
https://docs.openstack.org/manila/latest/admin/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.
|
|
|
|
Share Groups (since Ocata)
|
|
--------------------------
|
|
|
|
The share groups provides the ability to manage a group of shares together.
|
|
This feature is implemented at the manager level, every driver gets this feature
|
|
by default. If a driver wants to override the default behavior to support
|
|
additional functionalities such as consistent group snapshot, the driver
|
|
vendors may report this capability as a group capability, such as: Ordered
|
|
writes, Consistent snapshots, Group replication.
|
|
|
|
Drivers need to report group capabilities as part of the updated stats (e.g.
|
|
capacity) and filled in 'share_group_stats' node for their back end. Share group
|
|
type group-specs (scoped and un-scoped) are available for the driver
|
|
implementation to use as-needed. Below is an example of the share stats
|
|
payload from the driver having multiple pools and group capabilities. "my"
|
|
is used as an example vendor prefix:
|
|
|
|
::
|
|
|
|
{
|
|
'driver_handles_share_servers': 'False', #\
|
|
'share_backend_name': 'My Backend', # backend level
|
|
'vendor_name': 'MY', # mandatory/fixed
|
|
'driver_version': '1.0', # stats & capabilities
|
|
'storage_protocol': 'NFS_CIFS', #/
|
|
#\
|
|
'my_capability_1': 'custom_val', # "my" optional vendor
|
|
'my_capability_2': True, # stats & capabilities
|
|
#/
|
|
'share_group_stats': {
|
|
#\
|
|
'my_group_capability_1': 'custom_val', # "my" optional vendor
|
|
'my_group_capability_2': True, # stats & group capabilities
|
|
#/
|
|
'consistent_snapshot_support': 'host', #\
|
|
# common group capabilities
|
|
#/
|
|
},
|
|
]
|
|
}
|
|
|
|
|
|
.. note::
|
|
|
|
for more information please see :doc:`../admin/group_capabilities_and_extra_specs`
|
|
|
|
Share Replication
|
|
-----------------
|
|
|
|
Replicas of shares can be created for either data protection (for disaster
|
|
recovery) or for load sharing. In order to utilize this feature, drivers must
|
|
report the ``replication_type`` they support as a capability and implement
|
|
necessary methods.
|
|
|
|
More details can be found at: :doc:`../admin/shared-file-systems-share-replication`
|
|
|
|
Update "used_size" of shares
|
|
----------------------------
|
|
Drivers can update, for all the shares created on a particular backend, the
|
|
consumed space in GiB. While the polling interval for drivers to update this
|
|
information is configurable, drivers can choose to submit cached information
|
|
as necessary, but specify a time at which this information was "gathered_at".
|