"Fossies" - the Fresh Open Source Software Archive 
Source code changes of the file "doc/source/contributor/driver_requirements.rst" between
manila-8.1.3.tar.gz and manila-8.1.4.tar.gz
About: OpenStack Manila provides “Shared Filesystems as a service”. The "Stein" series (maintained release).
| driver_requirements.rst (manila-8.1.3) | : | driver_requirements.rst (manila-8.1.4) | ||
|---|---|---|---|---|
| skipping to change at line 17 | skipping to change at line 17 | |||
| a copy of the License at | a copy of the License at | |||
| http://www.apache.org/licenses/LICENSE-2.0 | http://www.apache.org/licenses/LICENSE-2.0 | |||
| Unless required by applicable law or agreed to in writing, software | Unless required by applicable law or agreed to in writing, software | |||
| distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |||
| WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |||
| License for the specific language governing permissions and limitations | License for the specific language governing permissions and limitations | |||
| under the License. | under the License. | |||
| Manila minimum requirements and features since Mitaka | Manila minimum requirements and features | |||
| ===================================================== | ======================================== | |||
| In order for a driver to be accepted into manila code base, there are certain | 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 | minimum requirements and features that must be met, in order to ensure | |||
| interoperability and standardized manila functionality among cloud providers. | interoperability and standardized manila functionality among cloud providers. | |||
| At least one driver mode (:term:`DHSS` true/false) | At least one driver mode (:term:`DHSS` true/false) | |||
| -------------------------------------------------- | -------------------------------------------------- | |||
| Driver modes determine if the driver is managing network resources | Driver modes determine if the driver is managing network resources | |||
| (:term:`DHSS` = true) in an automated way, in order to segregate tenants and | (:term:`DHSS` = true) in an automated way, in order to segregate tenants and | |||
| skipping to change at line 77 | skipping to change at line 77 | |||
| --------------- | --------------- | |||
| In order to best satisfy cloud service requirements, shares must be elastic, so | 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 | drivers must implement a share extend function that allows shares' size to be | |||
| increased. | increased. | |||
| Capabilities | Capabilities | |||
| ------------ | ------------ | |||
| In order for manila to function accordingly to the driver being used, the | 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 | driver must provide a set of information to manila, known as capabilities. | |||
| follows: | 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; | - share_backend_name: a name for the backend; | |||
| - driver_handles_share_servers: driver mode, whether this driver instance | - driver_handles_share_servers: driver mode, whether this driver instance | |||
| handles share servers, possible values are true or false; | handles share servers, possible values are true or false; | |||
| - vendor_name: driver vendor name; | - vendor_name: driver vendor name; | |||
| - driver_version: current driver instance version; | - driver_version: current driver instance version; | |||
| - storage_protocol: list of shared file system protocols supported by this | - storage_protocol: list of shared file system protocols supported by this | |||
| driver instance; | driver instance; | |||
| - total_capacity_gb: total amount of storage space provided, in GB; | - total_capacity_gb: total amount of storage space provided, in GB; | |||
| - free_capacity_gb: amount of storage space available for use, in GB; | - free_capacity_gb: amount of storage space available for use, in GB; | |||
| skipping to change at line 105 | skipping to change at line 107 | |||
| - dedupe: whether the backend supports deduplication; | - dedupe: whether the backend supports deduplication; | |||
| - compression: whether the backend supports compressed shares; | - compression: whether the backend supports compressed shares; | |||
| - thin_provisioning: whether the backend is overprovisioning shares; | - thin_provisioning: whether the backend is overprovisioning shares; | |||
| - pools: list of storage pools managed by this driver instance; | - pools: list of storage pools managed by this driver instance; | |||
| - qos: whether the backend supports quality of service for shares; | - qos: whether the backend supports quality of service for shares; | |||
| - replication_domain: string specifying a common group name for all backends | - replication_domain: string specifying a common group name for all backends | |||
| that can replicate between each other; | that can replicate between each other; | |||
| - replication_type: string specifying the type of replication supported by | - replication_type: string specifying the type of replication supported by | |||
| the driver. Can be one of ('readable', 'writable' or 'dr'). | the driver. Can be one of ('readable', 'writable' or 'dr'). | |||
| .. note:: for more information please see https://docs.openstack.org/manila/late | Below is an example of drivers with multiple pools. "my" is used as an | |||
| st/admin/capabilities_and_extra_specs.html | 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 | Continuous Integration systems | |||
| ------------------------------ | ------------------------------ | |||
| Every driver vendor must supply a CI system that tests its drivers | Every driver vendor must supply a CI system that tests its drivers | |||
| continuously for each patch submitted to OpenStack gerrit. This allows for | continuously for each patch submitted to OpenStack gerrit. This allows for | |||
| better QA and quicker response and notification for driver vendors when a | better QA and quicker response and notification for driver vendors when a | |||
| patch submitted affects an existing driver. The CI system must run all | 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 | applicable tempest tests, test all patches Jenkins has posted +1 and post its | |||
| test results. | test results. | |||
| skipping to change at line 127 | skipping to change at line 200 | |||
| .. note:: for more information please see http://docs.openstack.org/infra/system -config/third_party.html | .. note:: for more information please see http://docs.openstack.org/infra/system -config/third_party.html | |||
| Unit tests | Unit tests | |||
| ---------- | ---------- | |||
| All drivers submitted must be contemplated with unit tests covering at least | 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 | 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 | framework and be located in-tree using a structure that mirrors the functional | |||
| code, such as directory names and filenames. See template below: | code, such as directory names and filenames. See template below: | |||
| :: | :: | |||
| manila/[tests/]path/to/brand/new/[test_]driver.py | manila/[tests/]path/to/brand/new/[test_]driver.py | |||
| Documentation | Documentation | |||
| ------------- | ------------- | |||
| Drivers submitted must provide and maintain related documentation on | Drivers submitted must provide and maintain related documentation on | |||
| openstack-manuals, containing instructions on how to properly install and | openstack-manuals, containing instructions on how to properly install and | |||
| configure. The intended audience for this manual is cloud operators and | configure. The intended audience for this manual is cloud operators and | |||
| administrators. Also, driver maintainers must update the manila share features | administrators. Also, driver maintainers must update the manila share features | |||
| skipping to change at line 208 | skipping to change at line 281 | |||
| Share Groups (since Ocata) | Share Groups (since Ocata) | |||
| -------------------------- | -------------------------- | |||
| The share groups provides the ability to manage a group of shares together. | 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 | 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 | by default. If a driver wants to override the default behavior to support | |||
| additional functionalities such as consistent group snapshot, the driver | additional functionalities such as consistent group snapshot, the driver | |||
| vendors may report this capability as a group capability, such as: Ordered | vendors may report this capability as a group capability, such as: Ordered | |||
| writes, Consistent snapshots, Group replication. | 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 capabi | ||||
| lities | ||||
| #/ | ||||
| 'consistent_snapshot_support': 'host', #\ | ||||
| # common group capabil | ||||
| ities | ||||
| #/ | ||||
| }, | ||||
| ] | ||||
| } | ||||
| .. note:: | .. note:: | |||
| for more information please see | for more information please see :doc:`../admin/group_capabilities_and_extra_sp | |||
| `group capabilities <https://docs.openstack.org/manila/latest/admin/group_capa | ecs` | |||
| bilities_and_extra_specs.html>`_ | ||||
| Share Replication | Share Replication | |||
| ----------------- | ----------------- | |||
| Replicas of shares can be created for either data protection (for disaster | 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 | recovery) or for load sharing. In order to utilize this feature, drivers must | |||
| report the ``replication_type`` they support as a capability and implement | report the ``replication_type`` they support as a capability and implement | |||
| necessary methods. | necessary methods. | |||
| More details can be found at: | More details can be found at: :doc:`../admin/shared-file-systems-share-replicati | |||
| https://docs.openstack.org/manila/latest/admin/shared-file-systems-share-replica | on` | |||
| tion.html | ||||
| Update "used_size" of shares | Update "used_size" of shares | |||
| ---------------------------- | ---------------------------- | |||
| Drivers can update, for all the shares created on a particular backend, the | 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 | consumed space in GiB. While the polling interval for drivers to update this | |||
| information is configurable, drivers can choose to submit cached information | information is configurable, drivers can choose to submit cached information | |||
| as necessary, but specify a time at which this information was "gathered_at". | as necessary, but specify a time at which this information was "gathered_at". | |||
| End of changes. 7 change blocks. | ||||
| 13 lines changed or deleted | 116 lines changed or added | |||