Expose `user visible` extra specs
so that regular users can know the abstract back end independent capabilities and features in volume types. Implements: https://blueprints.launchpad.net/cinder/+spec/expose-user-visible-extra-specs APIImpact DocImpact Co-Authored-By: Tom Barron <tpb@dyncloud.net> Co-Authored-By: Alan Bishop <abishop@redhat.com> Change-Id: Id236326dca9ee08aad8427ea6cb400e25e7ac09e
This commit is contained in:
Tom Barron
Alan Bishop
parent
eff52b7353
commit
7d0785fa5a
433
specs/xena/expose-cinder-user-visible-extra-specs-spec.rst
Normal file
433
specs/xena/expose-cinder-user-visible-extra-specs-spec.rst
Normal file
@ -0,0 +1,433 @@
|
||||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=================================================
|
||||
Expose user-visible extra specs in volume types
|
||||
=================================================
|
||||
|
||||
https://blueprints.launchpad.net/cinder/+spec/expose-user-visible-extra-specs
|
||||
|
||||
This spec proposes definition of a class of *user visible* extra specs.
|
||||
These will be shown to regular users (members or readers in a keystone
|
||||
project) when they list extra specs or show volume types or extra specs.
|
||||
|
||||
Problem description
|
||||
-------------------
|
||||
|
||||
Cinder only allows cloud administrators to see the extra specs in volume
|
||||
types. This makes sense for specs that control knobs for use by drivers,
|
||||
that select a particular backend, or that would otherwise reveal backend
|
||||
specifics. But it is problematic for backend independent extra specs
|
||||
like ``multiattach`` or ``RESKEY:availability_zones`` – specs that
|
||||
carry critical information for regular users when they select volume
|
||||
types to use as they create volumes.
|
||||
|
||||
The traditional response to this problem has been that cloud
|
||||
administrators should add this critical information to the volume-type
|
||||
``description`` field or provide it in the user documentation for their
|
||||
cloud.
|
||||
|
||||
Whatever one thinks of the adequacy of that response when the cloud
|
||||
users are human beings, it clearly fails when the end user is an
|
||||
automated agent.
|
||||
|
||||
Use Cases
|
||||
---------
|
||||
|
||||
OpenShift cluster storage operators are automated agents that set up
|
||||
Kubernetes Storage Classes on underlying infrastructure. When that
|
||||
infrastructure is provided by OpenStack, the Cinder CSI operator will
|
||||
create a Storage Class corresponding to each Cinder volume type.
|
||||
OpenShift users in turn reference these Storage Classes in Persistent
|
||||
Volume Claims when dynamically provisioning Persistent Volumes for use
|
||||
by containerized applications.
|
||||
|
||||
When provisioning a persistent volume via Cinder CSI with ReadWriteMany
|
||||
access mode, the persistent volume claim should specify ``block``
|
||||
volumeMode (default is ``filesystem``) and reference a Storage Class
|
||||
corresponding to a Cinder volume type with a ``"multiattach": "<is> True"``
|
||||
extra spec.
|
||||
|
||||
Because OpenShift administrators and all the software that runs on their
|
||||
behalf are in the general case just regular OpenStack users rather
|
||||
than OpenStack administrators, they currently lack the ability to
|
||||
discover extra specs for volume types corresponding to their Storage
|
||||
Classes and are hindered in their ability to “do the right thing” for
|
||||
OpenShift users.
|
||||
|
||||
Cinder CSI now has a ``topology`` feature as well where it will likely
|
||||
make sense to be able to see ``RESKEY:availability_zones`` extra specs when
|
||||
setting up Storage Classes corresponding to volume types.
|
||||
|
||||
Proposed change
|
||||
---------------
|
||||
|
||||
Define a set of ``user visible`` extra specs in the Cinder code and modify the
|
||||
REST API view for showing extra specs to reveal these in policy based
|
||||
request contexts. The initial set of ``user visible`` extra specs is
|
||||
sufficient to establish a framework, and meet the immediate needs described in
|
||||
the use cases. The set is intentionally small, and leverages existing extra
|
||||
specs. The following extra spec keys are to be treated as ``user visible``:
|
||||
|
||||
- ``multiattach``
|
||||
- ``RESKEY:availability_zones``
|
||||
- ``replication_enabled``
|
||||
|
||||
The set of ``user visible`` extra specs will be a fixed list defined in the
|
||||
Cinder code, and can be extended but only by enhancing the code. Future
|
||||
updates can support additional volume characteristics that can be expressed with
|
||||
an extra spec. For example, it might be useful for users to know whether a
|
||||
volume type provides volumes that support online extend, but there currently
|
||||
is no extra spec associated with that feature.
|
||||
|
||||
The REST API behavior will be policy based, and not require a new
|
||||
microversion. The existing policies for accessing extra specs will remain, but
|
||||
the default values will be changed to grant access to any authorized user. A
|
||||
new policy will determine whether access is granted to all extra specs, or
|
||||
just ``user visible`` extra specs. The policies will allow users to view
|
||||
extra specs, but the view will be restricted to the extra specs that are
|
||||
considered ``user visible``. A new policy will control access to all extra
|
||||
specs, including the ones that are ``user visible``.
|
||||
|
||||
The current policies (and their default values) for accessing extra specs are:
|
||||
|
||||
========================================= ==========
|
||||
Policy Default
|
||||
========================================= ==========
|
||||
volume_extension:access_types_extra_specs admin-only
|
||||
volume_extension:types_extra_specs:index admin-only
|
||||
volume_extension:types_extra_specs:show admin-only
|
||||
========================================= ==========
|
||||
|
||||
The proposed policies, and their new default values, will be:
|
||||
|
||||
================================================= ==========
|
||||
Policy Default
|
||||
================================================= ==========
|
||||
volume_extension:access_types_extra_specs any authorized user
|
||||
volume_extension:types_extra_specs:index any authorized user
|
||||
volume_extension:types_extra_specs:show any authorized user
|
||||
volume_extension:types_extra_specs:read_sensitive admin-only
|
||||
================================================= ==========
|
||||
|
||||
The new ``volume_extension:types_extra_specs:read_sensitive`` policy will
|
||||
govern whether access is granted to all extra specs, or is limited to just
|
||||
``user visible`` extra specs. Hereafter in this spec, the new policy will
|
||||
be abbreviated as ``read_sensitive``.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
Build a new API to return user visible capabilities and features from
|
||||
volume types without exposing them as “extra specs.” Although this
|
||||
alternative would also solve the problem, it requires more code to
|
||||
write, test, and document.
|
||||
|
||||
Control exposure of each individual extra spec entirely by policy. It is
|
||||
not clear how to do this without significant changes to the existing
|
||||
REST API. Nor in our opinion is it desirable. There are clear cut
|
||||
examples of backend independent capabilities and features that are
|
||||
properly the business of any user who is authorized to create volumes, so
|
||||
users should have a reasonable expectation that these can be discovered
|
||||
without burdening the cloud administrator with the task of constructing
|
||||
policies for them one by one.
|
||||
|
||||
The new ``volume_extension:types_extra_specs:read_sensitive`` policy is
|
||||
introduced, but the existing policies remain defaulting to admin-only. The
|
||||
downside is this would require cloud administrators to modify the default
|
||||
policies for the ``user visible`` extra specs to be available to non-
|
||||
administrative API requests. However, the entire premise is that ``user
|
||||
visible`` extra specs are, by definition, intended to be visible to users.
|
||||
Cloud administrators shouldn't need to opt-in to reap the benefits of this
|
||||
feature. Cloud administrators who wish to retain the current behavior, where
|
||||
users are not authorized to see any extra specs, may do so by explicitly
|
||||
setting these policies to admin-only (the previous default value).
|
||||
|
||||
- volume_extension:access_types_extra_specs
|
||||
- volume_extension:types_extra_specs:index
|
||||
- volume_extension:types_extra_specs:show
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
|
||||
The REST API affected by this spec are:
|
||||
|
||||
#. /v3/{project_id}/types
|
||||
#. /v3/{project_id}/types/{volume_type_id}
|
||||
#. /v3/{project_id}/types/{volume_type_id}/extra_specs
|
||||
#. /v3/{project_id}/types/{volume_type_id}/extra_specs/{key}
|
||||
|
||||
The following examples document the behavior for a volume type with two
|
||||
extra specs:
|
||||
|
||||
- ``multiattach`` (a ``user visible`` extra spec)
|
||||
- ``volume_backend_name`` (which will be visible only when the context
|
||||
satisfies the ``read_sensitive`` policy)
|
||||
|
||||
GET /v3/{project_id}/types
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This REST API returns a list of volume types, and the following example
|
||||
shows just a single volume type.
|
||||
When the context doesn't satisfy the ``read_sensitive`` policy, the
|
||||
``extra_specs`` field is included but only ``user visible`` entries are
|
||||
present.
|
||||
|
||||
================================================= =======
|
||||
Policy Context
|
||||
================================================= =======
|
||||
volume_extension:access_types_extra_specs True
|
||||
volume_extension:types_extra_specs:read_sensitive False
|
||||
================================================= =======
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"volume_types": [
|
||||
{
|
||||
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
|
||||
"qos_specs_id": null,
|
||||
"name": "vol-type-001",
|
||||
"description": "volume type 0001",
|
||||
"os-volume-type-access:is_public": true,
|
||||
"is_public": true,
|
||||
"extra_specs": {
|
||||
"multiattach": "<is> True"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
When the ``read_sensitive`` policy is satisfied (by default, this will be the
|
||||
case only for administrators) the full list of ``extra_specs`` is returned.
|
||||
|
||||
================================================= =======
|
||||
Policy Context
|
||||
================================================= =======
|
||||
volume_extension:access_types_extra_specs True
|
||||
volume_extension:types_extra_specs:read_sensitive True
|
||||
================================================= =======
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"volume_types": [
|
||||
{
|
||||
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
|
||||
"qos_specs_id": null,
|
||||
"name": "vol-type-001",
|
||||
"description": "volume type 0001",
|
||||
"os-volume-type-access:is_public": true,
|
||||
"is_public": true,
|
||||
"extra_specs": {
|
||||
"multiattach": "<is> True",
|
||||
"volume_backend_name": "SecretName"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
GET /v3/{project_id}/types/{volume_type_id}
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The REST API shows the details for the specified volume type, and the behavior
|
||||
is similar to the to the /v3/{project_id}/types API.
|
||||
|
||||
- The ``extra_specs`` field will contain any ``user visible`` extra specs.
|
||||
- When the ``read_sensitive`` policy is satisfied, the full list of
|
||||
``extra_specs`` is returned.
|
||||
|
||||
GET /v3/{project_id}/types/{volume_type_id}/extra_specs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The policy will be updated to allow any authorized user access to this
|
||||
API. But, similar to above, for non ``read_sensitive`` requests the list of
|
||||
``extra_specs`` will be limited to those that are ``user visible``.
|
||||
|
||||
================================================= =======
|
||||
Policy Context
|
||||
================================================= =======
|
||||
volume_extension:types_extra_specs:index True
|
||||
volume_extension:types_extra_specs:read_sensitive False
|
||||
================================================= =======
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"extra_specs": {
|
||||
"multiattach": "<is> True"
|
||||
}
|
||||
}
|
||||
|
||||
If there are no ``user visible`` extra specs defined for the specified
|
||||
volume type, then an empty dictionary will be returned.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"extra_specs": {}
|
||||
}
|
||||
|
||||
When made by an administrator, the response will be the complete set of extra
|
||||
specs (no change from current behavior).
|
||||
|
||||
================================================= =======
|
||||
Policy Context
|
||||
================================================= =======
|
||||
volume_extension:types_extra_specs:index True
|
||||
volume_extension:types_extra_specs:read_sensitive True
|
||||
================================================= =======
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"extra_specs": {
|
||||
"multiattach": "<is> True",
|
||||
"volume_backend_name": "SecretName"
|
||||
}
|
||||
}
|
||||
|
||||
GET /v3/{project_id}/types/{volume_type_id}/extra_specs/{key}
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When the specified extra-specs {key} is in the ``user visible`` set, the value
|
||||
will be returned regardless of whether the requester satisfies the
|
||||
``read_sensitive`` policy.
|
||||
|
||||
================================================= =======
|
||||
Policy Context
|
||||
================================================= =======
|
||||
volume_extension:types_extra_specs:show True
|
||||
volume_extension:types_extra_specs:read_sensitive N/A
|
||||
================================================= =======
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"multiattach": "<is> True"
|
||||
}
|
||||
|
||||
The response to requests for extra specs that are not ``user visible`` will
|
||||
depend on the context. If the request satisfies the ``read_sensitive`` policy
|
||||
then the appropriate response is returned.
|
||||
|
||||
================================================= =======
|
||||
Policy Context
|
||||
================================================= =======
|
||||
volume_extension:types_extra_specs:show True
|
||||
volume_extension:types_extra_specs:read_sensitive True
|
||||
================================================= =======
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"volume_backend_name": "SecretName"
|
||||
}
|
||||
|
||||
But if the request does not satisfy the ``read_sensitive`` policy then the
|
||||
API will return 404 NOTFOUND. Returning 404 (instead of 403) prevents leakage
|
||||
of the names of ``read_sensitive`` extra spec keys.
|
||||
|
||||
================================================= =======
|
||||
Policy Context
|
||||
================================================= =======
|
||||
volume_extension:types_extra_specs:show True
|
||||
volume_extension:types_extra_specs:read_sensitive False
|
||||
================================================= =======
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
{
|
||||
"itemNotFound": {
|
||||
"code": 404
|
||||
"message": "Volume Type 6685584b-1eac-4da6-b5c3-555430cf68ff has no extra specs with key volume_backend_name."
|
||||
}
|
||||
}
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
None. The set of ``user visible`` extra specs is hard coded and does not
|
||||
include extra specs that reveal back end details.
|
||||
|
||||
Active/Active HA impact
|
||||
-----------------------
|
||||
|
||||
None. REST API layer change with no locking or exclusion or service
|
||||
restart implications.
|
||||
|
||||
Notifications impact
|
||||
--------------------
|
||||
|
||||
None – no asynchronous operations involved.
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
Cinderclient and OSC and Horizon should not need changes. Regular
|
||||
users will see some new information but no new fields are required.
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
None
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
No impact on OpenStack deployment tools or deployment planning/design.
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
No impact on OpenStack development outside the scope of this change.
|
||||
|
||||
Implementation
|
||||
--------------
|
||||
|
||||
Assignee(s)
|
||||
~~~~~~~~~~~
|
||||
|
||||
Primary assignee: abishop
|
||||
|
||||
Work Items
|
||||
~~~~~~~~~~
|
||||
|
||||
- Define list of user visible extra specs.
|
||||
- Define the ``read_sensitive`` policy, and modify the existing default
|
||||
policy rules that govern access to extra specs to allow access to any
|
||||
authorized user.
|
||||
- Update the API responses per this spec.
|
||||
- Modify unit tests to check for exposure of exactly and only the
|
||||
user visible extra specs without ``read_sensitive`` authorization.
|
||||
- Tempest tests
|
||||
|
||||
Dependencies
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Testing
|
||||
~~~~~~~
|
||||
|
||||
- New tempest tests in cinder-tempest-plugin
|
||||
|
||||
Documentation Impact
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Add section to Cinder Administration that defines and lists user
|
||||
visible extra specs. Describe the new ``read_sensitive`` policy, and
|
||||
explain the policy settings that will give an operator "legacy" behavior.
|
||||
- Update API reference
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
None
|
||||
Loading…
Reference in New Issue
Block a user