"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/source/admin/capabilities_and_extra_specs.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).

capabilities_and_extra_specs.rst  (manila-8.1.3)	:	capabilities_and_extra_specs.rst  (manila-8.1.4)
.. _capabilities_and_extra_specs:		.. _capabilities_and_extra_specs:
Capabilities and Extra-Specs		Capabilities and Extra-Specs
============================		============================
Manila Administrators create share types with extra-specs to allow users		Cloud Administrators create :ref:`shared_file_systems_share_types` with
to request a type of share to create. The Administrator chooses a name		extra-specs to:
for the share type and decides how to communicate the significance of
the different share types in terms that the users should understand or
need to know. By design, most of the details of a share type (the extra-
specs) are not exposed to users -- only Administrators.
Share Types
Refer to the manila client command-line help for information on how to
create a share type and set "extra-spec" key/value pairs for a share type.
Extra-Specs
There are 3 types of extra-specs: required, scoped, and un-scoped.
Manila *requires* the driver_handles_share_servers extra-spec.
*Scoped* extra-specs use a prefix followed by a colon to define a namespace
for scoping the extra-spec. A prefix could be a vendor name or acronym
and is a hint that this extra-spec key/value only applies to that vendor's
driver. Scoped extra-specs are not used by the scheduler to determine
where a share is created (except for the special `capabilities` prefix).
It is up to each driver implementation to determine how to use scoped
extra-specs and to document them.
The prefix "capabilities" is a special prefix to indicate extra-specs that
are treated like un-scoped extra-specs. In the CapabilitiesFilter the
"capabilities:" is stripped from the key and then the extra-spec key and
value are used as an un-scoped extra-spec.
*Un-scoped* extra-specs have a key that either starts with "capabilities:" or
does not contain a colon. When the CapabilitiesFilter is enabled (it is
enabled by default), the scheduler will only create a share on a backend
that reports capabilities that match the share type's un-scoped extra-spec
keys.
The CapabilitiesFilter uses the following for matching operators:		- influence the scheduler's decision to place new shares, and
		- instruct the Shared File System service or its storage driver/s to perform
		certain special actions with respect to the users' shares.
		As an administrator, you can choose a descriptive name or provide good
		descriptions for your share types to convey the share type capabilities to
		end users. End users can view standard ``tenant-visible`` extra-specs that
		can let them seek required behavior and automate their applications
		accordingly. By design, however, all other extra-specs of a share type are not
		exposed to non-privileged users.
		Types of Extra-Specs
		--------------------
		The Shared File Systems service back-end storage drivers offer a wide range of
		capabilities. The variation in these capabilities allows cloud
		administrators to provide a storage service catalog to their end users.
		Share type extra-specs tie-in with these capabilities.
		Some back-end capabilities are very specific to a storage system, and are
		opaque to the Shared File System service or the end users. These
		capabilities are invoked with the help of "scoped" extra-specs. Using scoped
		extra-specs is a way to provide programmatic directives to the concerned
		storage driver to do something during share creation or share manipulation.
		You can learn about the opaque capabilities through driver documentation
		and configure these capabilities within share types as scoped
		extra-specs (e.g.: hpe3par:nfs_options). The Shared File System service
		scheduler ignores scoped extra-specs during its quest to find the right back
		end to provision shares.
		There are some back-end capabilities in manila that do matter to the scheduler.
		For our understanding, lets call these non-scoped or non-opaque capabilities.
		All non-scoped capabilities can be directly used as share types extra-specs.
		They are considered by the scheduler’s capabilities filter (and any custom
		filter defined by deployers).
		You can get a list of non-scoped capabilities from the scheduler by using:
		.. code-block:: console
		$ manila pool-list --detail
		The non-scoped capabilities can be of three types:
		- **Capabilities pertaining to a specific back end storage system driver**: For
		example, *huawei_smartcache*.
		No Shared File System service API relies on non-opaque back end specific
		capabilities.
		- **Common capabilities that are not visible to end users**: The manila
		community has standardized some cross-platform capabilities like
		*thin_provisioning*, *dedupe*, *compression*, *qos*, *ipv6_support* and
		*ipv4_support*. Values of these options do not matter to any Shared File
		System service APIs; however, they can signify something to the manila
		services themselves. For example when a back end supports thin_provisioning,
		the scheduler service performs over-provisioning, and if a back end does
		not report *ipv6_support* as True, the share-manager service drops IPv6
		access rules before invoking the storage driver to update access rules.
		- **Common capabilities that are visible to end users**: Some capabilities
		affect functionality exposed via the Shared File System service API. For
		example, not all back ends support snapshots, and even if they do, they
		may not support all of the snapshot operations. For example, cloning
		snapshots into new shares, reverting shares in-place to snapshots, etc.
		The support for these capabilities determines whether users would be able
		to perform certain control-plane operations with manila. For example, a back
		end driver may report *snapshot_support=True* allowing end users to
		create share snapshots, however, the driver can report
		*create_share_from_snapshot_support=False*.
		This reporting allows cloud administrators to create share types that
		support snapshots but not creating shares from snapshots. When a user uses
		such a share type, they will not be able to clone snapshots into new shares.
		Tenant-visible capabilities aid manila in validating requests and failing
		fast on requests it cannot accommodate. They also help level set the user
		expectations on some failures. For example, if snapshot_support is set to
		False on the share type, since users can see this, they will not invoke
		the create snapshot API, and even if they do, they will understand the
		HTTP 400 (and error message) in better context.
		.. important::
		All extra-specs are optional, except one: *driver_handles_share_servers*.
		Scheduler's treatment of non-scoped extra specs
		-----------------------------------------------
		The CapabilitiesFilter in the Shared File System scheduler uses the following
		for matching operators:
* No operator		* No operator
This defaults to doing a python ==. Additionally it will match boolean values.		This defaults to doing a python ==. Additionally it will match boolean values.
* **<=, >=, ==, !=**		* **<=, >=, ==, !=**
This does a float conversion and then uses the python operators as expected.		This does a float conversion and then uses the python operators as expected.
* **<in>**		* **<in>**
skipping to change at line 77		skipping to change at line 129
would be "<is> True".		would be "<is> True".
* **=**		* **=**
This does a float conversion and chooses a host that has equal to or greater		This does a float conversion and chooses a host that has equal to or greater
than the resource specified. This operator behaves this way for historical		than the resource specified. This operator behaves this way for historical
reasons.		reasons.
* **s==, s!=, s>=, s>, s<=, s<**		* **s==, s!=, s>=, s>, s<=, s<**
The "s" indicates it is a string comparison. These choose a host that satisfie		The "s" indicates it is a string comparison. These choose a host that
s		satisfies the comparison of strings in capability and specification. For
the comparison of strings in capability and specification. For example,		example, if "capabilities:replication_type s== dr", a host that reports
if "capabilities:replication_type s== dr", a host that reports		replication_type of "dr" will be chosen. If "share_backend_name s!=
replication_type of "dr" will be chosen.		cephfs" is used, any host not named "cephfs" can be chosen.
For vendor-specific capabilities (which need to be visible to the		For vendor-specific non-scoped capabilities (which need to be visible to the
CapabilityFilter), it is recommended to use the vendor prefix followed		scheduler), drivers are recommended to use the vendor prefix followed
by an underscore. This is not a strict requirement, but will provide a		by an underscore. This is not a strict requirement, but can provide a
consistent look along-side the scoped extra-specs and will be a clear		consistent look along-side the scoped extra-specs and will be a clear
indicator of vendor capabilities vs. common capabilities.		indicator of vendor capabilities vs. common capabilities.
Common Capabilities		Common Capabilities
-------------------		-------------------
For capabilities that apply to multiple backends a common capability can		Common capabilities apply to multiple backends.
be created. Like all other backend reported capabilities, these capabilities		Like all other backend reported capabilities, these capabilities
can be used verbatim as extra_specs in share types used to create shares.		can be used verbatim as extra_specs in share types used to create shares.
* `driver_handles_share_servers` is a special, required, user-visible common		Share type common capability extra-specs that are visible to end users:
capability. Added in Kilo.		-----------------------------------------------------------------------
* `dedupe` - indicates that a backend/pool can provide shares using some		* **driver_handles_share_servers** is a special, required common
deduplication technology. The default value of the dedupe capability (if a		capability. When set to True, the scheduler matches requests with back ends
driver doesn't report it) is False. In Liberty, drivers cannot report to the		that can isolate user workloads with dedicated share servers exporting
scheduler that they support both dedupe and non-deduped share. For each pool		shares on user provided share networks.
it's either always on or always off, even if the drivers can technically
support both dedupe and non-deduped in a pool. Since Mitaka, the logic is
changed to allow a driver to report dedupe=[True, False] if it can support
both dedupe and non-deduped in a pool. Administrators can make a share type
use deduplication by setting this extra-spec to '<is> True'. Administrators
can prevent a share type from using deduplication by setting this extra-spec
to '<is> False'. Added in Liberty.
* `compression` - indicates that a backend/pool can provide shares using some		* **snapshot_support** indicates whether snapshots are supported for shares
compression technology. The default value of the compression capability (if a		created on the pool/backend. When administrators do not set this capability
driver doesn't report it) is False. In Liberty, drivers cannot report to the		as an extra-spec in a share type, the scheduler can place new shares of that
scheduler that they support both compression and non-compression. For each		type in pools without regard for whether snapshots are supported, and those
pool it's either always on or always off, even if the drivers can technically		shares will not support snapshots.
support both compression and non-compression in a pool. Since Mitaka, the
logic is changed to allow a driver to report compression=[True, False] if it
can support both compression and non-compression in a pool. Administrators
can make a share type use compression by setting this extra-spec to
'<is> True'. Administrators can prevent a share type from using compression
by setting this extra-spec to '<is> False'. Added in Liberty.
* `thin_provisioning` - shares will not be space guaranteed and
overprovisioning will be enabled. This capability defaults to False.
Backends/pools that support thin provisioning must report True for this
capability. Administrators can make a share type use thin provisioned shares
by setting this extra-spec to '<is> True'. If a driver reports
thin_provisioning=False (the default) then it's assumed that the driver is
doing thick provisioning and overprovisioning is turned off.
This was added in Liberty. In Liberty and Mitaka, the driver was required
to configure one pool for thin and another pool for thick and report
thin_provisioning as either True or False even if an array can technically
support both thin and thick provisioning in a pool. In Newton, the logic is
changed to allow a driver to report thin_provisioning=[True, False] if it
can support both thin and thick provisioning in a pool. To provision a thick
share on a back end that supports both thin and thick provisioning, set one
of the following in extra specs:
::		* **create_share_from_snapshot_support** indicates whether a backend can
		create a new share from a snapshot. When administrators do not set this
		capability as an extra-spec in a share type, the scheduler can place new
		shares of that type in pools without regard for whether creating shares
		from snapshots is supported, and those shares will not support creating
		shares from snapshots.
{'thin_provisioning': 'False'}		* **revert_to_snapshot_support** indicates that a driver is capable of
{'thin_provisioning': '<is> False'}		reverting a share in place to its most recent snapshot. When administrators
{'capabilities:thin_provisioning': 'False'}		do not set this capability as an extra-spec in a share type, the scheduler
{'capabilities:thin_provisioning': '<is> False'}		can place new shares of that type in pools without regard for whether
		reverting shares to snapshots is supported, and those shares will not support
		reverting shares to snapshots.
* `qos` - indicates that a backend/pool can provide shares using some		* **mount_snapshot_support** indicates that a driver is capable of exporting
QoS (Quality of Service) specification. The default value of the qos		share snapshots for mounting. Users can provide and revoke access to
capability (if a driver doesn't report it) is False. Administrators		mountable snapshots just like they can with their shares.
can make a share type use QoS by setting this extra-spec to '<is> True' and
also setting the relevant QoS-related extra specs for the drivers being used.
Administrators can prevent a share type from using QoS by setting this
extra-spec to '<is> False'. Different drivers have different ways of specifyin
g
QoS limits (or guarantees) and this extra spec merely allows the scheduler to
filter by pools that either have or don't have QoS support enabled. Added in
Mitaka.
* `replication_type` - indicates the style of replication supported for the		* **replication_type** indicates the style of replication supported for the
backend/pool. This extra_spec will have a string value and could be one		backend/pool. This extra_spec will have a string value and could be one
of :term:`writable`, :term:`readable` or :term:`dr`. `writable` replication		of :term:`writable`, :term:`readable` or :term:`dr`. `writable` replication
type involves synchronously replicated shares where all replicas are		type involves synchronously replicated shares where all replicas are
writable. Promotion is not supported and not needed. `readable` and `dr`		writable. Promotion is not supported and not needed. `readable` and `dr`
replication types involve a single `active` or `primary` replica and one or		replication types involve a single `active` or `primary` replica and one or
more `non-active` or secondary replicas per share. In `readable` type of		more `non-active` or secondary replicas per share. In `readable` type of
replication, `non-active` replicas have one or more export_locations and		replication, `non-active` replicas have one or more export_locations and
can thus be mounted and read while the `active` replica is the only one		can thus be mounted and read while the `active` replica is the only one
that can be written into. In `dr` style of replication, only		that can be written into. In `dr` style of replication, only
the `active` replica can be mounted, read from and written into. Added in		the `active` replica can be mounted, read from and written into.
Mitaka.
* `snapshot_support` - indicates whether snapshots are supported for shares		* **availability_zones** indicates a comma separated list of availability
created on the pool/backend. When administrators do not set this capability		zones that can be used for provisioning. Users can always provide a specific
as an extra-spec in a share type, the scheduler can place new shares of that		availability zone during share creation, and they will receive a
type in pools without regard for whether snapshots are supported, and those		synchronous failure message if they attempt to create a share in an
shares will not support snapshots.		availability zone that the share type does not permit. If you do not set
		this extra-spec, the share type is assumed to be serviceable in all
		availability zones known to the Shared File Systems service.
* `create_share_from_snapshot_support` - indicates whether a backend can create		Share type common capability extra-specs that are not visible to end users:
a new share from a snapshot. When administrators do not set this capability		---------------------------------------------------------------------------
as an extra-spec in a share type, the scheduler can place new shares of that
type in pools without regard for whether creating shares from snapshots is
supported, and those shares will not support creating shares from snapshots.
* `revert_to_snapshot_support` - indicates that a driver is capable of
reverting a share in place to its most recent snapshot. When administrators
do not set this capability as an extra-spec in a share type, the scheduler
can place new shares of that type in pools without regard for whether
reverting shares to snapshots is supported, and those shares will not support
reverting shares to snapshots.
* `ipv4_support` - indicates whether a back end can create a share that can be		* **dedupe** indicates that a backend/pool can provide shares using some
accessed via IPv4 protocol. If administrators do not set this capability		deduplication technology. The default value of the dedupe capability (if a
as an extra-spec in a share type, the scheduler can place new shares of that		driver doesn't report it) is False. Drivers can support both dedupe and
type in pools without regard for whether IPv4 is supported.		non-deduped shares in a single storage pool by reporting ``dedupe=[True,
		False]``. You can make a share type use deduplication by setting this
		extra-spec to '<is> True', or prevent it by setting this extra-spec
		to '<is> False'.
* `ipv6_support` - indicates whether a back end can create a share that can be		* **compression** indicates that a backend/pool can provide shares using some
accessed via IPv6 protocol. If administrators do not set this capability		compression technology. The default value of the compression capability (if a
as an extra-spec in a share type, the scheduler can place new shares of that		driver doesn't report it) is False. Drivers can support compressed and
type in pools without regard for whether IPv6 is supported.		non-compressed shares in a single storage pool by reporting
		``compression=[True, False]``. You can make a share type use compression
		by setting this extra-spec to '<is> True', or prevent it by setting this
		extra-spec to '<is> False'.
		* **thin_provisioning** can be enabled where shares will not be
		guaranteed space allocations and overprovisioning will be enabled. This
		capability defaults to False. Back ends/pools that support thin
		provisioning report True for this capability. Administrators can make a
		share type use thin provisioned shares by setting this extra-spec
		to '<is> True'. If a driver reports thin_provisioning=False (the default)
		then it's assumed that the driver is doing thick provisioning and
		overprovisioning is turned off. A driver can support thin provisioned
		and thick provisioned shares in the same pool by reporting
		``thin_provisioning=[True, False]``.
Reporting Capabilities		To provision a thick
Drivers report capabilities as part of the updated stats (e.g. capacity)		share on a back end that supports both thin and thick provisioning, set one
for their backend/pools. This is how a backend/pool advertizes its ability		of the following in extra specs:
to provide a share that matches the capabilities requested in the share
type extra-specs.
Developer impact
Developers should update their drivers to include all backend and pool
capacities and capabilities in the share stats it reports to scheduler.
Below is an example having multiple pools. "my" is used as an
example vendor prefix:
::		::
{		{'thin_provisioning': 'False'}
'driver_handles_share_servers': 'False', #\		{'thin_provisioning': '<is> False'}
'share_backend_name': 'My Backend', # backend level		{'capabilities:thin_provisioning': 'False'}
'vendor_name': 'MY', # mandatory/fixed		{'capabilities:thin_provisioning': '<is> False'}
'driver_version': '1.0', # stats & capabilities
'storage_protocol': 'NFS_CIFS', #/		* **qos** indicates that a backend/pool can provide shares using some
#\		QoS (Quality of Service) specification. The default value of the qos
'my_capability_1': 'custom_val', # "my" optional vendor		capability (if a driver doesn't report it) is False. You can make a share
'my_capability_2': True, # stats & capabilities		type use QoS by setting this extra-spec to '<is> True' and also setting
#/		the relevant QoS-related extra specs for the drivers being used.
'pools': [		Administrators can prevent a share type from using QoS by setting this
{'pool_name':		extra-spec to '<is> False'. Different drivers have different ways of
'thin-dedupe-compression pool', #\		specifying QoS limits (or guarantees) and this extra spec merely allows
'total_capacity_gb': 500, # mandatory stats for		the scheduler to filter by pools that either have or don't have QoS
'free_capacity_gb': 230, # pools		support enabled.
'reserved_percentage': 0, #/
#\		* **ipv4_support** indicates whether a back end can create a share that
'dedupe': True, # common capabilities		can be accessed via IPv4 protocol. If administrators do not set this
'compression': True, #		capability as an extra-spec in a share type, the scheduler can place new
'snapshot_support': True, #		shares of that type in pools without regard for whether IPv4 is supported.
'create_share_from_snapshot_support': True,
'revert_to_snapshot_support': True,		* **ipv6_support** - indicates whether a back end can create a share that
'qos': True, # this backend supports QoS		can be accessed via IPv6 protocol. If administrators do not set this
'thin_provisioning': True, #		capability as an extra-spec in a share type, the scheduler can place new
'max_over_subscription_ratio': 10, # (mandatory for thin)		shares of that type in pools without regard for whether IPv6 is supported.
'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,
},
]
}
Work Flow
1) Share Backends report how many pools and what those pools look like and
are capable of to scheduler;
2) When request comes in, scheduler picks a pool that fits the need best to
serve the request, it passes the request to the backend where the target
pool resides;
3) Share driver gets the message and lets the target pool serve the request
as scheduler instructed. Share type extra-specs (scoped and un-scoped)
are available for the driver implementation to use as-needed.
End of changes. 18 change blocks.
142 lines changed or deleted		165 lines changed or added

---