openstack
/
keystone-specs
Code Issues Proposed changes

Switch to stestr 

According to Openstack summit session [1],
stestr is maintained project to which all Openstack projects should migrate.
Let's switch to stestr as other projects have already moved to it.

This change also fixes a bunch of D001 violations where lines are too
long in .rst documents.

[1] https://etherpad.openstack.org/p/YVR-python-pti

Change-Id: Ic20ae60d9020896690c5e7f07124d7500ffd3d2d
This commit is contained in:
Vu Cong Tuan 2018-07-10 18:26:00 +07:00 committed by Lance Bragstad
parent b05d80a97a
commit 4fe55f0e82
6 changed files with 132 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -7,4 +7,4 @@ build
*.swp *.swp
*.swo *.swo
*.pyc *.pyc
.testrepository .stestr/

4
.stestr.conf Normal file
View File

@ -0,0 +1,4 @@
[DEFAULT]
test_path=./tests
top_dir=./

4
.testr.conf
View File

@ -1,4 +0,0 @@
[DEFAULT]
test_command=OS_STDOUT_CAPTURE=1 OS_STDERR_CAPTURE=1 OS_TEST_TIMEOUT=60 ${PYTHON:-python} -m subunit.run discover -t ./ . $LISTOPT $IDOPTION
test_id_option=--load-list $IDFILE
test_list_option=--list

2
requirements.txt
View File

@ -5,6 +5,6 @@ pbr>=2.0.0
sphinx!=1.6.1,>=1.5.1 sphinx!=1.6.1,>=1.5.1
sphinxcontrib-blockdiag sphinxcontrib-blockdiag
openstackdocstheme>=1.17.0 # Apache-2.0 openstackdocstheme>=1.17.0 # Apache-2.0
testrepository>=0.0.18 stestr>=2.0.0 # Apache-2.0
testtools>=0.9.34 testtools>=0.9.34
doc8 doc8

207
specs/keystone/rocky/define-default-roles.rst
View File

@ -71,15 +71,16 @@ use to adopt the proposed default roles in a future `community goal
Default Roles Default Roles
------------- -------------
**reader**: It should only be used for read-only APIs and operations. Alternatively **reader**: It should only be used for read-only APIs and operations.
referred to as ``readonly`` or ``observer``, this role fills an extremely popular need from operators. Alternatively referred to as ``readonly`` or ``observer``, this role fills
an extremely popular need from operators.
**member**: serves as the **member**: serves as the
general purpose ‘do-er’ role. It introduces granularity between the administrator(s) general purpose ‘do-er’ role. It introduces granularity between
and everyone else. the administrator(s) and everyone else.
**admin**: This role will be only be considered appropriate for operations deemed too **admin**: This role will be only be considered appropriate for operations
sensitive for anyone with a member role. deemed too sensitive for anyone with a member role.
The desired outcome of implementing the roles above is that projects should The desired outcome of implementing the roles above is that projects should
start moving away from the practice of hardcoding operations to specific role start moving away from the practice of hardcoding operations to specific role
@ -92,10 +93,10 @@ Scope Type (Refresher)
**project-scope**: Project-scope relates to authorization for operating in a **project-scope**: Project-scope relates to authorization for operating in a
specific tenancy of the cloud. specific tenancy of the cloud.
**system-scope**: System-scope relates to authorization for operating with APIs that **system-scope**: System-scope relates to authorization for operating with APIs
do not map nicely to the concept of Project scope. It is **not** meant to cover *all* that do not map nicely to the concept of Project scope. It is **not** meant to
APIs across a deployment. More information about system-scope can be found in the `specification cover *all* APIs across a deployment. More information about system-scope can
<http://specs.openstack.org/openstack/keystone-specs/specs/keystone/queens/system-scope.html>`_, be found in the `specification <http://specs.openstack.org/openstack/keystone-specs/specs/keystone/queens/system-scope.html>`_,
along with relevant historical context justifying the `need for system-scope along with relevant historical context justifying the `need for system-scope
<https://bugs.launchpad.net/keystone/+bug/968696>`_. <https://bugs.launchpad.net/keystone/+bug/968696>`_.
@ -103,62 +104,97 @@ Examples
-------- --------
`reader:` `reader:`
An example project-scoped application of this role would be listing project tags (``identity:get_project_tags``). An example project-scoped application of this role would be listing project
An example system-scoped application of this role would be listing service endpoints tags (``identity:get_project_tags``).
(``identity:list_endpoints``). An example system-scoped application of this role would be listing service
endpoints (``identity:list_endpoints``).
`member:` `member:`
An example project-scoped application of this role would be creating a project tag (``identity:update_project_tags``). An example project-scoped application of this role would be creating a project
tag (``identity:update_project_tags``).
An example system-scope application of this role would be updating an endpoint An example system-scope application of this role would be updating an endpoint
(``identity:update_endpoint``). (``identity:update_endpoint``).
`admin:` `admin:`
An example project-scoped administrator operation would be deleting project tags (``identity:delete_project_tags``). An example project-scoped administrator operation would be deleting project
An example system-scoped administrator operation would be creating an endpoint for a service tags (``identity:delete_project_tags``).
(``identity:create_endpoint``) or listing migrations (``os_compute_api:os-migrations``). An example system-scoped administrator operation would be creating an endpoint
for a service (``identity:create_endpoint``) or
listing migrations (``os_compute_api:os-migrations``).
The following table is neither a final nor a comprehensive list of all possible rules/policies. The following is neither a final nor a comprehensive list of all possible
It serves merely as a snippet of existing rules to showcase how policies, scope, and the new rules/policies. It serves merely as a snippet of existing rules to showcase how
default roles can work together to provide a richer policy experience. policies, scope, and the new default roles can work together to provide a
richer policy experience.
+-------------+------------------------------+---------------------------------+---------------------------------+ Project Reader
| | reader | member | admin | ~~~~~~~~~~~~~~
+=============+==============================+=================================+=================================+
| **Project** | * identity:list_project_tags | * identity:list_project_tags | * identity:list_project_tags |
| | * identity:get_project_tag | * identity:get_project_tag | * identity:get_project_tag |
| | | * identity:update_project_tags | * identity:update_project_tags |
| | | | * identity:create_project_tag |
| | | | * identity:delete_project_tags |
+-------------+------------------------------+---------------------------------+---------------------------------+
| **System** | * identity:list_endpoints | * identity:list_endpoints | * identity:list_endpoints |
| | * identity:get_endpoint | * identity:get_endpoint | * identity:get_endpoint |
| | | * identity:update_endpoint | * identity:update_endpoint |
| | | | * identity:create_endpoint |
| | | | * os_compute_api:os-hypervisors |
| | | | * os_compute_api:os-migrations |
+-------------+------------------------------+---------------------------------+---------------------------------+
* ``identity:list_project_tags``
* ``identity:get_project_tag``
Project Member
~~~~~~~~~~~~~~
* ``identity:list_project_tags``
* ``identity:get_project_tag``
* ``identity:update_project_tags``
Project Admin
~~~~~~~~~~~~~
* ``identity:list_project_tags``
* ``identity:get_project_tag``
* ``identity:update_project_tags``
* ``identity:create_project_tags``
* ``identity:delete_project_tags``
System Reader
~~~~~~~~~~~~~
* ``identity:list_endpoints``
* ``identity:get_endpoint``
System Member
~~~~~~~~~~~~~
* ``identity:list_endpoints``
* ``identity:get_endpoint``
* ``identity:update_endpoints``
System Admin
~~~~~~~~~~~~
* ``identity:list_endpoints``
* ``identity:get_endpoint``
* ``identity:update_endpoints``
* ``identity:create_endpoints``
* ``os-compute-api:os-hypervisors``
* ``os-compute-api:os-migrations``
Example snippets of various policy files, or rendered snippets, could look like Example snippets of various policy files, or rendered snippets, could look like
the following. the following.
.. note:: .. note::
The default roles discussed will be created by Keystone, during the bootstrap process, using `implied roles The default roles discussed will be created by Keystone, during the bootstrap
process, using `implied roles
<https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/implied_role.html>`_. <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/implied_role.html>`_.
As indicated in the above table, having ``admin`` role implies a user also has the same rights as As indicated in the above table, having ``admin`` role implies a user also
the ``member`` role. Therefore this user will also has the same rights as the ``reader`` role as has the same rights as the ``member`` role. Therefore this user will also has
``member`` implies ``reader``. the same rights as the ``reader`` role as ``member`` implies ``reader``.
This keeps policy files clean. For example: This keeps policy files clean. For example, the following are equivalent as a
result of implied roles:
"identity:list_endpoints": "role:reader OR role:member OR role:admin" is equivalent to "identity:list_endpoints": "role:reader OR role:member OR role:admin"
"identity:list_endpoints": "role:reader" as a result of the implied roles chain. "identity:list_endpoints": "role:reader"
The chain of implied roles will be documented alongside of the `policy-in-code defaults The chain of implied roles will be documented alongside of the
<https://github.com/openstack/keystone/blob/master/keystone/common/policies/base.py>`_ in addition to `policy-in-code defaults
general Keystone documentation updates noting as much. <https://github.com/openstack/keystone/blob/master/keystone/common/policies/base.py>`_
in addition to general Keystone documentation updates noting as much.
:: ::
@ -189,53 +225,60 @@ Let's assume the following role assignment exist:
Given the above assignments and policies, the following would be possible: Given the above assignments and policies, the following would be possible:
**Alice** can list or retrieve specific endpoints. Alice cannot do any project specific **Alice** can list or retrieve specific endpoints. Alice cannot do any project
operations since her authorization is limited to the deployment system. specific operations since her authorization is limited to the deployment
system.
**Bob** can retrieve specific endpoints, list them, and update them. He cannot create new **Bob** can retrieve specific endpoints, list them, and update them. He cannot
endpoints, or delete existing ones. Bob cannot do any project specific operations because his create new endpoints, or delete existing ones. Bob cannot do any project
specific operations because his authorization is limited to the deployment
system.
**Charlie** can retrieve specific endpoints, list, as well as create them.
Additionally, Charlie can list information on migrations as well as
hypervisors. He cannot perform any project specific operations because his
authorization is limited to the deployment system. authorization is limited to the deployment system.
**Charlie** can retrieve specific endpoints, list, as well as create them. Additionally, Charlie **Qiana** can list all tags and get details about a specific tag within Project
can list information on migrations as well as hypervisors. He cannot perform any project specific Alpha. She may not perform system specific policies because her authorization
operations because his authorization is limited to the deployment system. is on a single project.
**Qiana** can list all tags and get details about a specific tag within Project Alpha. She may not **Rebecca** can list all tags, get details about a specific tag, and update a
perform system specific policies because her authorization is on a single project. tag within Project Alpha. She cannot perform any system specific policies
because her authorization is on a single project.
**Rebecca** can list all tags, get details about a specific tag, and update a tag within Project **Steve** can list all tags, create new tags, get details about a specific tag,
Alpha. She cannot perform any system specific policies because her authorization is on a single update a tag, and delete tags within Project Alpha. He cannot perform any
project. system specific policies because his authorization is on a single project.
**Steve** can list all tags, create new tags, get details about a specific tag, update a tag, and
delete tags within Project Alpha. He cannot perform any system specific policies because his
authorization is on a single project.
Risk Mitigation Risk Mitigation
--------------- ---------------
**Scenario One -- A role serving the purposes described in this spec exists under another name**: **Scenario One -- A role serving the purposes described in this spec exists
Let us assume that Deployment A already has ``Role X`` which serves the purpose of the proposed here as under another name**: Let us assume that Deployment A already has ``Role X``
the ``reader`` role. In this instance, it is reasonable to assume that operators may have custom policy which serves the purpose of the proposed here as the ``reader`` role. In this
work in place and do not want to port immediately. instance, it is reasonable to assume that operators may have custom policy work
in place and do not want to port immediately.
This issue may be mitigated through the use of implied roles. Operators need simply to ensure that This issue may be mitigated through the use of implied roles. Operators need
``reader`` implies ``Role X``. Please review the documentation on `implied roles simply to ensure that ``reader`` implies ``Role X``. Please review the
<https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/implied_role.html>`_. for documentation on `implied roles
specific instructions on how make one role imply another. <https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/implied_role.html>`_.
for specific instructions on how make one role imply another.
**Scenario Two -- An existing ``reader``, ``member``, or ``admin`` role already exists**: Let us assume **Scenario Two -- An existing ``reader``, ``member``, or ``admin`` role already
that Deployment B already has a ``member`` role. Keystone will not attempt to overwrite any existing roles exists**: Let us assume that Deployment B already has a ``member`` role.
that have been populated. It will instead note that a role with the name ``member`` already exists in log Keystone will not attempt to overwrite any existing roles that have been
output. populated. It will instead note that a role with the name ``member`` already
exists in log output.
Alternatives Alternatives
------------ ------------
reader/writer/admin vs reader/member/admin. There was much debate regarding the naming reader/writer/admin vs reader/member/admin. There was much debate regarding the
conventions for these roles. We have opted to use `reader`, `member`, and `admin` as we naming conventions for these roles. We have opted to use `reader`, `member`,
believe they most accurately describe their purpose when the context of OpenStack is taken and `admin` as we believe they most accurately describe their purpose when the
into consideration. context of OpenStack is taken into consideration.
Implementation Implementation
============== ==============
@ -258,8 +301,8 @@ Work Items
* Implement scope_types for all policies in Keystone * Implement scope_types for all policies in Keystone
* Remove @protected decorator * Remove @protected decorator
* Document how operators may generate policy files with service specific roles * Document how operators may generate policy files with service specific roles
* Prepare Proof-of-Concept to demo and facilitate acceptance of an OpenStack Community Goal * Prepare Proof-of-Concept to demo and facilitate acceptance of an OpenStack
to promote default roles across the other services. Community Goal to promote default roles across the other services.
Dependencies Dependencies
============ ============
@ -297,6 +340,6 @@ Resources
.. note:: .. note::
This work is licensed under a Creative Commons Attribution 3.0 Unported License. This work is licensed under a Creative Commons Attribution 3.0 Unported
http://creativecommons.org/licenses/by/3.0/legalcode License. http://creativecommons.org/licenses/by/3.0/legalcode

2
tox.ini
View File

@ -9,7 +9,7 @@ setenv = VIRTUAL_ENV={envdir}
install_command = pip install -U {opts} {packages} install_command = pip install -U {opts} {packages}
deps = -r{toxinidir}/requirements.txt deps = -r{toxinidir}/requirements.txt
commands = commands =
python setup.py testr --slowest --testr-args='{posargs}' stestr run --slowest {posargs}
doc8 specs/ doc8 specs/
[testenv:venv] [testenv:venv]