Retire patrole
Patrole project is not active anymore and its gate is broken. We waited for couple of cycle to see if there is any interest in this project and anyone can maintain it. But we did not get any new maintainers and current QA team does not have bandwidth/interest to continue maintaining it. This project was for RBAc testing which is moving towards unit/functional tests on service side as well as tempest plugins tests. In QA 2023.2 PTG, we decided to retire this project - https://etherpad.opendev.org/p/qa-bobcat-ptg Change-Id: I7721cf06104e5871ec27cdd87d4608dace60a8b7
This commit is contained in:
Ghanshyam Mann
parent
aa7bc0dd9a
commit
b540700061
@ -1,6 +0,0 @@
|
||||
[run]
|
||||
branch = True
|
||||
source = patrole
|
||||
|
||||
[report]
|
||||
ignore_errors = True
|
||||
65
.gitignore
vendored
65
.gitignore
vendored
@ -1,65 +0,0 @@
|
||||
*.py[cod]
|
||||
|
||||
# C extensions
|
||||
*.so
|
||||
|
||||
# Packages
|
||||
*.egg*
|
||||
*.egg-info
|
||||
dist
|
||||
build
|
||||
eggs
|
||||
parts
|
||||
bin
|
||||
var
|
||||
sdist
|
||||
develop-eggs
|
||||
.installed.cfg
|
||||
lib
|
||||
lib64
|
||||
|
||||
# Installer logs
|
||||
pip-log.txt
|
||||
|
||||
# Unit test / coverage reports
|
||||
cover/
|
||||
.coverage*
|
||||
!.coveragerc
|
||||
.tox
|
||||
nosetests.xml
|
||||
.testrepository
|
||||
.venv
|
||||
|
||||
# Translations
|
||||
*.mo
|
||||
|
||||
# Mr Developer
|
||||
.mr.developer.cfg
|
||||
.project
|
||||
.pydevproject
|
||||
|
||||
# Complexity
|
||||
output/*.html
|
||||
output/*/index.html
|
||||
|
||||
# Sphinx
|
||||
doc/build
|
||||
doc/source/_static/patrole.conf.sample
|
||||
doc/source/framework/code/
|
||||
|
||||
# pbr generates these
|
||||
AUTHORS
|
||||
ChangeLog
|
||||
|
||||
# Editors
|
||||
*~
|
||||
.*.swp
|
||||
.*sw?
|
||||
*.idea
|
||||
|
||||
# Files created by releasenotes build
|
||||
releasenotes/build
|
||||
|
||||
# Misc
|
||||
.stestr
|
||||
*.log
|
||||
5
.mailmap
5
.mailmap
@ -1,5 +0,0 @@
|
||||
# Format is:
|
||||
# <preferred e-mail> <other e-mail 1>
|
||||
# <preferred e-mail> <other e-mail 2>
|
||||
Felipe Monteiro <felipe.carneiro.monteiro@gmail.com> <fm577c@att.com>
|
||||
Felipe Monteiro <felipe.carneiro.monteiro@gmail.com> <felipe.monteiro@att.com>
|
||||
@ -1,3 +0,0 @@
|
||||
[DEFAULT]
|
||||
test_path=./patrole_tempest_plugin/tests/unit
|
||||
group_regex=([^\.]*\.)*
|
||||
246
.zuul.yaml
246
.zuul.yaml
@ -1,246 +0,0 @@
|
||||
- job:
|
||||
name: patrole-base
|
||||
parent: devstack-tempest
|
||||
description: |
|
||||
Patrole base job for admin,member and reader roles. This job executes RBAC tests
|
||||
for all the "core" services that Tempest covers, excluding Swift.
|
||||
required-projects:
|
||||
- name: opendev.org/openstack/tempest
|
||||
- name: opendev.org/openstack/patrole
|
||||
timeout: 7800
|
||||
roles:
|
||||
- zuul: opendev.org/openstack/devstack
|
||||
# Define common irrelevant files to use everywhere else
|
||||
irrelevant-files: &patrole-irrelevant-files
|
||||
- ^(test-|)requirements.txt$
|
||||
- ^.*\.rst$
|
||||
- ^doc/.*
|
||||
- ^etc/.*$
|
||||
- ^patrole_tempest_plugin/tests/unit/.*$
|
||||
- ^patrole_tempest_plugin/hacking/.*$
|
||||
- ^releasenotes/.*
|
||||
- ^setup.cfg$
|
||||
vars:
|
||||
tempest_plugins:
|
||||
- patrole
|
||||
devstack_plugins:
|
||||
patrole: https://opendev.org/openstack/patrole.git
|
||||
devstack_services:
|
||||
tempest: true
|
||||
neutron: true
|
||||
neutron-trunk: true
|
||||
tempest_test_regex: (?!.*\[.*\bslow\b.*\])(^patrole_tempest_plugin\.tests\.api)
|
||||
# run the tempest all tox environment target with patrole regex
|
||||
tox_envlist: all
|
||||
# allows job to use the tempest version installed with devstack instead of pypi
|
||||
# according to the requirements.txt
|
||||
tox_extra_args: --sitepackages
|
||||
|
||||
- job:
|
||||
name: patrole-base-multinode
|
||||
parent: tempest-multinode-full-py3
|
||||
description: |-
|
||||
Patrole base job for multinode and "slow" tests where "slow" tests include:
|
||||
|
||||
* Tests that take more than ~30 seconds to run.
|
||||
* Tests that experience spurious failures related to servers, volumes,
|
||||
backups and similar resources failing to build.
|
||||
timeout: 7800
|
||||
branches:
|
||||
- master
|
||||
required-projects:
|
||||
- opendev.org/openstack/devstack-gate
|
||||
- opendev.org/openstack/tempest
|
||||
- opendev.org/openstack/patrole
|
||||
irrelevant-files: *patrole-irrelevant-files
|
||||
vars:
|
||||
tempest_plugins:
|
||||
- patrole
|
||||
devstack_plugins:
|
||||
patrole: https://opendev.org/openstack/patrole.git
|
||||
devstack_services:
|
||||
tempest: true
|
||||
neutron: true
|
||||
tempest_concurrency: 1
|
||||
tempest_test_regex: (?=.*\[.*\bslow\b.*\])(^patrole_tempest_plugin\.tests\.api)
|
||||
tox_envlist: all
|
||||
tox_extra_args: --sitepackages
|
||||
|
||||
- job:
|
||||
name: patrole-admin
|
||||
parent: patrole-base
|
||||
description: Patrole job for admin role.
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: admin
|
||||
# https://storyboard.openstack.org/#!/story/2009048
|
||||
tempest_exclude_regex: patrole_tempest_plugin.tests.api.volume.test_volume_actions_rbac.VolumesActionsV3RbacTest.test_force_detach_volume_from_instance
|
||||
|
||||
- job:
|
||||
name: patrole-member
|
||||
parent: patrole-base
|
||||
description: Patrole job for member role.
|
||||
# This currently works from stable/pike onward.
|
||||
branches: ^(?!stable/ocata).*$
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: member
|
||||
# https://storyboard.openstack.org/#!/story/2009216
|
||||
tempest_exclude_regex: patrole_tempest_plugin.tests.api.volume.test_volume_types_extra_specs_rbac.VolumeTypesExtraSpecsRbacTest.test_show_volume_type_extra_specs
|
||||
|
||||
- job:
|
||||
name: patrole-reader
|
||||
parent: patrole-base
|
||||
description: Patrole job for reader role.
|
||||
# This currently works from stable/stein onward.
|
||||
branches: ^(?!stable/(ocata|pike|queens|rocky)).*$
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: reader
|
||||
# https://storyboard.openstack.org/#!/story/2009216
|
||||
tempest_exclude_regex: patrole_tempest_plugin.tests.api.volume.test_volume_types_extra_specs_rbac.VolumeTypesExtraSpecsRbacTest.test_show_volume_type_extra_specs
|
||||
|
||||
- job:
|
||||
name: patrole-member-wallaby
|
||||
parent: patrole-member
|
||||
override-checkout: stable/wallaby
|
||||
|
||||
- job:
|
||||
name: patrole-member-victoria
|
||||
parent: patrole-member
|
||||
override-checkout: stable/victoria
|
||||
|
||||
- job:
|
||||
name: patrole-member-ussuri
|
||||
parent: patrole-member
|
||||
nodeset: openstack-single-node-bionic
|
||||
override-checkout: stable/ussuri
|
||||
vars:
|
||||
# https://storyboard.openstack.org/#!/story/2009048
|
||||
tempest_exclude_regex: patrole_tempest_plugin.tests.api.volume.test_volume_actions_rbac.VolumesActionsV3RbacTest.test_force_detach_volume_from_instance
|
||||
|
||||
- job:
|
||||
name: patrole-multinode-admin
|
||||
parent: patrole-base-multinode
|
||||
voting: false
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: admin
|
||||
|
||||
- job:
|
||||
name: patrole-multinode-member
|
||||
parent: patrole-base-multinode
|
||||
voting: false
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: member
|
||||
|
||||
- job:
|
||||
name: patrole-multinode-reader
|
||||
parent: patrole-base-multinode
|
||||
voting: false
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: reader
|
||||
|
||||
- job:
|
||||
name: patrole-py35-member
|
||||
parent: patrole-base
|
||||
description: Patrole py35 job for member role.
|
||||
vars:
|
||||
devstack_localrc:
|
||||
# Use member for py35 because arguably negative testing is more
|
||||
# important than admin, which is already covered by patrole-admin job.
|
||||
RBAC_TEST_ROLES: member
|
||||
USE_PYTHON3: true
|
||||
devstack_services:
|
||||
s-account: false
|
||||
s-container: false
|
||||
s-object: false
|
||||
s-proxy: false
|
||||
# Without Swift, c-bak cannot run (in the gate at least).
|
||||
c-bak: false
|
||||
|
||||
- job:
|
||||
name: patrole-extension-base
|
||||
parent: patrole-base
|
||||
description: |
|
||||
Patrole plugin job for admin and member roles which runs RBAC tests for
|
||||
neutron-tempest-plugin APIs (if the plugin is installed).
|
||||
|
||||
Covers Neutron extension functionality only. Should not be used for
|
||||
supporting Neutron plugins like fwaas.
|
||||
required-projects:
|
||||
- name: opendev.org/openstack/tempest
|
||||
- name: opendev.org/openstack/patrole
|
||||
- name: opendev.org/openstack/neutron-tempest-plugin
|
||||
vars:
|
||||
tempest_plugins:
|
||||
- patrole
|
||||
- neutron-tempest-plugin
|
||||
devstack_plugins:
|
||||
neutron: https://opendev.org/openstack/neutron.git
|
||||
patrole: https://opendev.org/openstack/patrole.git
|
||||
neutron-tempest-plugin: https://opendev.org/openstack/neutron-tempest-plugin.git
|
||||
devstack_services:
|
||||
tempest: true
|
||||
neutron: true
|
||||
neutron-segments: true
|
||||
neutron-qos: true
|
||||
tempest_test_regex: (?=.*ExtRbacTest)(^patrole_tempest_plugin\.tests\.api)
|
||||
|
||||
- job:
|
||||
name: patrole-extension-admin
|
||||
parent: patrole-extension-base
|
||||
voting: false
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: admin
|
||||
|
||||
- job:
|
||||
name: patrole-extension-member
|
||||
parent: patrole-extension-base
|
||||
voting: false
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: member
|
||||
|
||||
- job:
|
||||
name: patrole-extension-reader
|
||||
parent: patrole-extension-base
|
||||
voting: false
|
||||
vars:
|
||||
devstack_localrc:
|
||||
RBAC_TEST_ROLES: reader
|
||||
|
||||
- project:
|
||||
templates:
|
||||
- openstack-cover-jobs
|
||||
- openstack-python3-yoga-jobs
|
||||
- check-requirements
|
||||
- publish-openstack-docs-pti
|
||||
- release-notes-jobs-python3
|
||||
check:
|
||||
jobs:
|
||||
- patrole-admin
|
||||
- patrole-member
|
||||
- patrole-reader
|
||||
- patrole-member-wallaby
|
||||
- patrole-member-victoria
|
||||
- patrole-member-ussuri
|
||||
- patrole-multinode-admin
|
||||
- patrole-multinode-member
|
||||
- patrole-multinode-reader
|
||||
- patrole-extension-admin
|
||||
- patrole-extension-member
|
||||
- patrole-extension-reader
|
||||
gate:
|
||||
jobs:
|
||||
- patrole-admin
|
||||
- patrole-member
|
||||
- patrole-reader
|
||||
periodic-stable:
|
||||
jobs:
|
||||
- patrole-member-wallaby
|
||||
- patrole-member-victoria
|
||||
- patrole-member-ussuri
|
||||
@ -1,19 +0,0 @@
|
||||
The source repository for this project can be found at:
|
||||
|
||||
https://opendev.org/openstack/patrole
|
||||
|
||||
Pull requests submitted through GitHub are not monitored.
|
||||
|
||||
To start contributing to OpenStack, follow the steps in the contribution guide
|
||||
to set up and use Gerrit:
|
||||
|
||||
https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
|
||||
|
||||
Bugs should be filed on Storyboard:
|
||||
|
||||
https://storyboard.openstack.org/#!/project/1040
|
||||
|
||||
For more specific information about contributing to this repository, see the
|
||||
Patrole contributor guide:
|
||||
|
||||
https://docs.openstack.org/patrole/latest/contributor/contributing.html
|
||||
170
HACKING.rst
170
HACKING.rst
@ -1,170 +0,0 @@
|
||||
Patrole Coding Guide
|
||||
====================
|
||||
|
||||
- Step 1: Read the OpenStack Style Commandments: `<https://docs.openstack.org/hacking/latest/>`__
|
||||
- Step 2: Review Tempest's Style Commandments: `<https://docs.openstack.org/tempest/latest/HACKING.html>`__
|
||||
- Step 3: Read on
|
||||
|
||||
Patrole Specific Commandments
|
||||
------------------------------
|
||||
|
||||
Patrole borrows the following commandments from Tempest; refer to
|
||||
`Tempest's Commandments <https://docs.openstack.org/tempest/latest/HACKING.html>`__
|
||||
for more information:
|
||||
|
||||
.. note::
|
||||
|
||||
The original Tempest Commandments do not include Patrole-specific paths.
|
||||
Patrole-specific paths replace the Tempest-specific paths within Patrole's
|
||||
hacking checks.
|
||||
|
||||
- [T102] Cannot import OpenStack python clients in
|
||||
``patrole_tempest_plugin/tests/api``
|
||||
- [T105] Tests cannot use setUpClass/tearDownClass
|
||||
- [T107] Check that a service tag isn't in the module path
|
||||
- [T108] Check no hyphen at the end of rand_name() argument
|
||||
- [T109] Cannot use testtools.skip decorator; instead use
|
||||
``decorators.skip_because`` from ``tempest.lib``
|
||||
- [T113] Check that tests use ``data_utils.rand_uuid()`` instead of
|
||||
``uuid.uuid4()``
|
||||
- [N322] Method's default argument shouldn't be mutable
|
||||
|
||||
The following are Patrole's specific Commandments:
|
||||
|
||||
- [P100] The ``rbac_rule_validation.action`` decorator must be applied to
|
||||
all RBAC tests
|
||||
- [P101] RBAC test filenames must end with "_rbac.py"; for example,
|
||||
test_servers_rbac.py, not test_servers.py
|
||||
- [P102] RBAC test class names must end in 'RbacTest'
|
||||
- [P103] ``self.client`` must not be used as a client alias; this allows for
|
||||
code that is more maintainable and easier to read
|
||||
- [P104] RBAC `extension test class`_ names must end in 'ExtRbacTest'
|
||||
|
||||
.. _extension test class: https://git.openstack.org/cgit/openstack/patrole/plain/patrole_tempest_plugin/tests/api/network/README.rst
|
||||
|
||||
Supported OpenStack Components
|
||||
------------------------------
|
||||
|
||||
Patrole only offers **in-tree** integration testing coverage for the following
|
||||
components:
|
||||
|
||||
* Cinder
|
||||
* Glance
|
||||
* Keystone
|
||||
* Neutron
|
||||
* Nova
|
||||
|
||||
Patrole currently has no stable library, so reliance upon Patrole's framework
|
||||
for external RBAC testing should be done with caution. Nonetheless, even when
|
||||
Patrole has a stable library, it will only offer in-tree RBAC testing for
|
||||
the components listed above.
|
||||
|
||||
Role Overriding
|
||||
---------------
|
||||
|
||||
Correct role overriding is vital to correct RBAC testing within Patrole. If a
|
||||
test does not call ``self.override_role()`` within the RBAC test, followed
|
||||
by the API endpoint that enforces the expected policy action, then the test is
|
||||
**not** a valid Patrole test: The API endpoint under test will be performed
|
||||
with admin role, which is always wrong unless ``CONF.patrole.rbac_test_role``
|
||||
is also admin.
|
||||
|
||||
.. todo::
|
||||
|
||||
Patrole does not have a hacking check for role overriding, but one may be
|
||||
added in the future.
|
||||
|
||||
Branchless Patrole Considerations
|
||||
---------------------------------
|
||||
|
||||
Like Tempest, Patrole is branchless. This is to better ensure API and RBAC
|
||||
consistency between releases because API and RBAC behavior should not change
|
||||
between releases. This means that the stable branches are also gated by the
|
||||
Patrole master branch, which also means that proposed commits to Patrole must
|
||||
work against both the master and all the currently supported stable branches
|
||||
of the projects. As such there are a few special considerations that have to
|
||||
be accounted for when pushing new changes to Patrole.
|
||||
|
||||
1. New Tests for new features
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Patrole, like Tempest, *implicitly* tests new features because new policies
|
||||
oftentimes accompany new features. The same `Tempest philosophy`_ regarding
|
||||
feature flags and new features also applies to Patrole.
|
||||
|
||||
.. _Tempest philosophy: https://docs.openstack.org/tempest/latest/HACKING.html#new-tests-for-new-features
|
||||
|
||||
2. New Tests for new policies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When adding tests for new policies that were not in previous releases of the
|
||||
projects, the new test must be properly skipped with a feature flag. This
|
||||
involves using the ``testtools.skip(Unless|If)`` decorator above the test
|
||||
to check if the required policy is enabled. Similarly, a feature flag must
|
||||
be used whenever an OpenStack service covered by Patrole changes one of its
|
||||
policies in a backwards-incompatible way. If there isn't a method of selecting
|
||||
the new policy from the config file then there won't be a mechanism to disable
|
||||
the test with older stable releases and the new test won't be able to merge.
|
||||
|
||||
Introduction of a new feature flag requires specifying a default value for the
|
||||
corresponding config option that is appropriate in the latest OpenStack
|
||||
release. Because Patrole is branchless, the feature flag's default value will
|
||||
need to be overridden to a value that is appropriate in earlier releases in
|
||||
which the feature isn't available. In DevStack, this can be accomplished by
|
||||
modifying Patrole's lib installation script for previous branches (because
|
||||
DevStack is branched).
|
||||
|
||||
3. Bug fix on core project needing Patrole changes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When trying to land a bug fix which changes a tested API you'll have to use the
|
||||
following procedure:
|
||||
|
||||
#. Propose change to the project, get a +2 on the change even with the
|
||||
test failing Patrole side.
|
||||
#. Propose skip to the relevant Patrole test which will only be approved
|
||||
after the corresponding change in the project has a +2.
|
||||
#. Land project change in master and all open stable branches
|
||||
(if required).
|
||||
#. Land changed test in Patrole.
|
||||
|
||||
Otherwise the bug fix won't be able to land in the project.
|
||||
|
||||
4. New Tests for existing features or policies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The same `Tempest logic`_ regarding new tests for existing features or
|
||||
policies also applies to Patrole.
|
||||
|
||||
.. _Tempest logic: https://docs.openstack.org/tempest/latest/HACKING.html#new-tests-for-existing-features
|
||||
|
||||
|
||||
Black Box vs. White Box Testing
|
||||
-------------------------------
|
||||
|
||||
Tempest is a `black box testing framework`_, meaning that it is concerned with
|
||||
testing public API endpoints and doesn't concern itself with testing internal
|
||||
implementation details. Patrole, as a Tempest plugin, also falls underneath
|
||||
the category of black box testing. However, even with policy in code
|
||||
documentation, some degree of white box testing is required in order to
|
||||
correctly write RBAC tests.
|
||||
|
||||
This is because :ref:`policy-in-code` documentation, while useful in many
|
||||
respects, is usually quite brief and its main purpose is to help operators
|
||||
understand how to customize policy configuration rather than to help
|
||||
developers understand complex policy authorization work flows. For example,
|
||||
policy in code documentation doesn't make deriving
|
||||
:ref:`multiple policies <multiple-policies>` easy. Such documentation also
|
||||
doesn't usually mention that a specific parameter needs to be set, or that a
|
||||
particular microversion must be enabled, or that a particular set of
|
||||
prerequisite API or policy actions must be executed, in order for the policy
|
||||
under test to be enforced by the server. This means that test writers must
|
||||
account for the internal RBAC implementation in API code in order to correctly
|
||||
understand the complete RBAC work flow within an API.
|
||||
|
||||
Besides, as mentioned :ref:`elsewhere <design-principles>` in this
|
||||
documentation, not all services currently implement policy in code, making
|
||||
some degree of white box testing a "necessary evil" for writing robust RBAC
|
||||
tests.
|
||||
|
||||
.. _black box testing framework: https://docs.openstack.org/tempest/latest/HACKING.html#negative-tests
|
||||
176
LICENSE
176
LICENSE
@ -1,176 +0,0 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
261
README.rst
261
README.rst
@ -1,251 +1,10 @@
|
||||
Patrole - RBAC Integration Tempest Plugin
|
||||
=========================================
|
||||
|
||||
Patrole is a set of integration tests to be run against a live OpenStack
|
||||
cluster. It has a battery of tests dedicated to validating the correctness and
|
||||
integrity of the cloud's RBAC implementation.
|
||||
|
||||
More importantly, Patrole is a security validation tool for verifying that
|
||||
Role-Based Access Control is correctly configured and enforced in an OpenStack
|
||||
cloud. It runs `Tempest`_-based API tests using specified RBAC roles, thus
|
||||
allowing deployments to verify that only intended roles have access to those
|
||||
APIs.
|
||||
|
||||
Patrole is currently undergoing heavy development. As more projects move
|
||||
toward policy in code, Patrole will align its testing with the appropriate
|
||||
documentation.
|
||||
|
||||
* Free software: Apache license
|
||||
* Documentation: https://docs.openstack.org/patrole/latest
|
||||
* Source: https://opendev.org/openstack/patrole
|
||||
* Bugs: https://storyboard.openstack.org/#!/project/openstack/patrole
|
||||
* Release notes: https://docs.openstack.org/releasenotes/patrole/
|
||||
|
||||
Team and repository tags
|
||||
------------------------
|
||||
|
||||
.. image:: https://governance.openstack.org/tc/badges/patrole.svg
|
||||
:target: https://governance.openstack.org/tc/reference/tags/index.html
|
||||
|
||||
.. _design-principles:
|
||||
|
||||
Design Principles
|
||||
-----------------
|
||||
|
||||
As a `Tempest plugin`_, Patrole borrows some design principles from `Tempest design principles`_,
|
||||
but not all, as its testing scope is confined to policies.
|
||||
|
||||
* *Stability*. Patrole uses OpenStack public interfaces. Tests in Patrole
|
||||
should only touch public OpenStack APIs.
|
||||
* *Atomicity*. Patrole tests should be atomic: they should test policies in
|
||||
isolation. Unlike Tempest, a Patrole test strives to only call a single
|
||||
endpoint at a time. This is because it is important to validate each policy
|
||||
is authorized correctly and the best way to do that is to validate each
|
||||
policy alone, to avoid test contamination.
|
||||
* *Complete coverage*. Patrole should validate all policy in code defaults. For
|
||||
testing, Patrole uses the API-to-policy mapping contained in each project's
|
||||
`policy in code`_ documentation where applicable.
|
||||
|
||||
For example, Nova's policy in code documentation is located in the
|
||||
`Nova repository`_ under ``nova/policies``. Likewise, Keystone's policy in
|
||||
code documentation is located in the `Keystone repository`_ under
|
||||
``keystone/common/policies``. The other OpenStack services follow the same
|
||||
directory layout pattern with respect to policy in code.
|
||||
|
||||
.. note::
|
||||
|
||||
Realistically this is not always possible because some services have
|
||||
not yet moved to policy in code.
|
||||
|
||||
* *Customizable*. Patrole should be able to validate custom policy overrides to
|
||||
ensure that those overrides enhance rather than undermine the cloud's RBAC
|
||||
configuration. In addition, Patrole should be able to validate any role.
|
||||
* *Self-cleaning*. Patrole should attempt to clean up after itself; whenever
|
||||
possible we should tear down resources when done.
|
||||
|
||||
.. note::
|
||||
|
||||
Patrole modifies roles dynamically in the background, which affects
|
||||
pre-provisioned credentials. Work is currently underway to clean up
|
||||
modifications made to pre-provisioned credentials.
|
||||
|
||||
* *Self-testing*. Patrole should be self-testing.
|
||||
|
||||
.. _Tempest plugin: https://docs.openstack.org/tempest/latest/plugin.html
|
||||
.. _Tempest design principles: https://docs.openstack.org/tempest/latest/overview.html#design-principles
|
||||
.. _policy in code: https://specs.openstack.org/openstack/oslo-specs/specs/newton/policy-in-code.html
|
||||
.. _Nova repository: https://opendev.org/openstack/nova/src/branch/master/nova/policies
|
||||
.. _Keystone repository: https://opendev.org/openstack/keystone/src/branch/master/keystone/common/policies
|
||||
|
||||
Features
|
||||
--------
|
||||
* Validation of default policy definitions located in policy.json files.
|
||||
* Validation of in-code policy definitions.
|
||||
* Validation of custom policy file definitions that override default policy
|
||||
definitions.
|
||||
* Built-in positive and negative testing. Positive and negative testing
|
||||
are performed using the same tests and role-switching.
|
||||
* Valdation of custom roles as well as default OpenStack roles.
|
||||
|
||||
.. note::
|
||||
|
||||
Patrole does not yet support policy.yaml files, the new file format for
|
||||
policy files in OpenStack.
|
||||
|
||||
How It Works
|
||||
------------
|
||||
Patrole leverages ``oslo.policy`` (OpenStack's policy enforcement engine) to
|
||||
determine whether a given role is allowed to perform a policy action, given a
|
||||
specific role and OpenStack service. The output from ``oslo.policy`` (the
|
||||
expected result) and the actual result from test execution are compared to
|
||||
each other: if both results match, then the test passes; else it fails.
|
||||
|
||||
Terminology
|
||||
^^^^^^^^^^^
|
||||
* Expected Result - The expected result of a given test.
|
||||
* Actual Result - The actual result of a given test.
|
||||
* Final Result - A match between both expected and actual results. A mismatch
|
||||
in the expected result and the actual result will result in a test failure.
|
||||
|
||||
* Expected: Pass | Actual: Pass - Test Case Success
|
||||
* Expected: Pass | Actual: Fail - Test Case Under-Permission Failure
|
||||
* Expected: Fail | Actual: Pass - Test Case Over-Permission Failure
|
||||
* Expected: Fail | Actual: Fail (Expected exception) - Test Case Success
|
||||
* Expected: Fail | Actual: Fail (Unexpected exception) - Test Case Failure
|
||||
|
||||
Quickstart
|
||||
----------
|
||||
To run Patrole, you must first have `Tempest`_ installed and configured
|
||||
properly. Please reference `Tempest_quickstart`_ guide to do so. Follow all
|
||||
the steps outlined therein. Afterward, proceed with the steps below.
|
||||
|
||||
#. You first need to install Patrole. This is done with pip after you check out
|
||||
the Patrole repo::
|
||||
|
||||
$ git clone https://opendev.org/openstack/patrole
|
||||
$ pip install patrole/
|
||||
|
||||
This can be done within a venv.
|
||||
|
||||
.. note::
|
||||
|
||||
You may also install Patrole from source code by running::
|
||||
|
||||
pip install -e patrole/
|
||||
|
||||
#. Next you must properly configure Patrole, which is relatively
|
||||
straightforward. For details on configuring Patrole refer to the
|
||||
`Patrole Configuration <https://docs.openstack.org/patrole/latest/configuration.html#patrole-configuration>`_.
|
||||
|
||||
#. Once the configuration is done you're now ready to run Patrole. This can
|
||||
be done using the `tempest_run`_ command. This can be done by running::
|
||||
|
||||
$ tempest run --regex '^patrole_tempest_plugin\.tests\.api'
|
||||
|
||||
There is also the option to use testr directly, or any `testr`_ based test
|
||||
runner, like `ostestr`_. For example, from the workspace dir run::
|
||||
|
||||
$ stestr --regex '(?!.*\[.*\bslow\b.*\])(^patrole_tempest_plugin\.tests\.api))'
|
||||
|
||||
will run the same set of tests as the default gate jobs.
|
||||
|
||||
You can also run Patrole tests using `tox`_, but as Patrole needs access to
|
||||
global packages use ``--sitepackages`` argument. To do so, ``cd`` into the
|
||||
**Tempest** directory and run::
|
||||
|
||||
$ tox -eall --sitepackages -- patrole_tempest_plugin.tests.api
|
||||
|
||||
.. note::
|
||||
|
||||
It is possible to run Patrole via ``tox -eall`` in order to run Patrole
|
||||
isolated from other plugins. This can be accomplished by including the
|
||||
installation of services that currently use policy in code -- for example,
|
||||
Nova and Keystone. For example::
|
||||
|
||||
$ tox -evenv-tempest -- pip install /opt/stack/patrole /opt/stack/keystone /opt/stack/nova
|
||||
$ tox -eall -- patrole_tempest_plugin.tests.api
|
||||
|
||||
#. Log information from tests is captured in ``tempest.log`` under the Tempest
|
||||
repository. Some Patrole debugging information is captured in that log
|
||||
related to expected test results and `Role Overriding <https://docs.openstack.org/patrole/latest/test_writing_guide.html#role-overriding>`_.
|
||||
|
||||
More detailed RBAC testing log output is emitted to ``patrole.log`` under
|
||||
the Patrole repository. To configure Patrole's logging, see the
|
||||
`Patrole Configuration Guide <https://docs.openstack.org/patrole/latest/configuration.html#patrole-configuration>`_.
|
||||
|
||||
.. _Tempest: https://opendev.org/openstack/tempest/
|
||||
.. _Tempest_quickstart: https://docs.openstack.org/tempest/latest/overview.html#quickstart
|
||||
.. _tempest_run: https://docs.openstack.org/tempest/latest/run.html
|
||||
.. _testr: https://testrepository.readthedocs.org/en/latest/MANUAL.html
|
||||
.. _ostestr: https://docs.openstack.org/os-testr/latest/
|
||||
.. _tox: https://tox.readthedocs.io/en/latest/
|
||||
|
||||
RBAC Tests
|
||||
----------
|
||||
|
||||
To change the roles that the patrole tests are being run as, edit
|
||||
``rbac_test_roles`` in the ``patrole`` section of tempest.conf: ::
|
||||
|
||||
[patrole]
|
||||
rbac_test_roles = member,reader
|
||||
...
|
||||
|
||||
.. note::
|
||||
|
||||
The ``rbac_test_roles`` is service-specific. member, for example,
|
||||
is an arbitrary role, but by convention is used to designate the default
|
||||
non-admin role in the system. Most Patrole tests should be run with
|
||||
**admin** and **member** roles. However, other services may use entirely
|
||||
different roles or role combinations.
|
||||
|
||||
For more information about RBAC, reference the `rbac-overview`_
|
||||
documentation page.
|
||||
|
||||
For information regarding which projects Patrole offers RBAC testing for,
|
||||
reference the `HACKING`_ documentation page.
|
||||
|
||||
.. _rbac-overview: https://docs.openstack.org/patrole/latest/rbac-overview.html
|
||||
.. _HACKING: https://docs.openstack.org/patrole/latest/HACKING.html#supported-openstack-components
|
||||
|
||||
Unit Tests
|
||||
----------
|
||||
|
||||
Patrole also has a set of unit tests which test the Patrole code itself. These
|
||||
tests can be run by specifying the test discovery path::
|
||||
|
||||
$ stestr --test-path ./patrole_tempest_plugin/tests/unit run
|
||||
|
||||
By setting ``--test-path`` option to ``./patrole_tempest_plugin/tests/unit``
|
||||
it specifies that test discovery should only be run on the unit test directory.
|
||||
|
||||
Alternatively, there are the py27 and py35 tox jobs which will run the unit
|
||||
tests with the corresponding version of Python.
|
||||
|
||||
One common activity is to just run a single test; you can do this with tox
|
||||
simply by specifying to just run py27 or py35 tests against a single test::
|
||||
|
||||
$ tox -e py27 -- -n patrole_tempest_plugin.tests.unit.test_rbac_utils.RBACUtilsTest.test_override_role_with_missing_admin_role
|
||||
|
||||
Or all tests in the test_rbac_utils.py file::
|
||||
|
||||
$ tox -e py27 -- -n patrole_tempest_plugin.tests.unit.test_rbac_utils
|
||||
|
||||
You may also use regular expressions to run any matching tests::
|
||||
|
||||
$ tox -e py27 -- test_rbac_utils
|
||||
|
||||
For more information on these options and details about stestr, please see the
|
||||
`stestr documentation <http://stestr.readthedocs.io/en/latest/MANUAL.html>`_.
|
||||
|
||||
Release Versioning
|
||||
------------------
|
||||
`Patrole Release Notes <https://docs.openstack.org/releasenotes/patrole/>`_
|
||||
shows which changes have been released for each version.
|
||||
|
||||
Patrole's release versioning follows Tempest's conventions. Like Tempest,
|
||||
Patrole is branchless and uses versioning instead.
|
||||
|
||||
Storyboard
|
||||
----------
|
||||
Bugs and enhancements are tracked via Patrole's
|
||||
`Storyboard Page <https://storyboard.openstack.org/#!/project/openstack/patrole>`_.
|
||||
This project is no longer maintained.
|
||||
|
||||
The contents of this repository are still available in the Git
|
||||
source code management system. To see the contents of this
|
||||
repository before it reached its end of life, please check out the
|
||||
previous commit with "git checkout HEAD^1".
|
||||
|
||||
For any further questions, please email
|
||||
openstack-discuss@lists.openstack.org or join #openstack-dev on
|
||||
OFTC.
|
||||
|
||||
189
REVIEWING.rst
189
REVIEWING.rst
@ -1,189 +0,0 @@
|
||||
Reviewing Patrole Code
|
||||
======================
|
||||
To start read the `OpenStack Common Review Checklist
|
||||
<https://docs.openstack.org/infra/manual/developers.html#peer-review>`_
|
||||
|
||||
|
||||
Ensuring code is executed
|
||||
-------------------------
|
||||
Any new test or change to an existing test has to be verified in the gate. This
|
||||
means that the first thing to check with any change is that a gate job actually
|
||||
runs it. Tests which aren't executed either because of configuration or skips
|
||||
should not be accepted.
|
||||
|
||||
|
||||
Execution time
|
||||
--------------
|
||||
Along with checking that the jobs log that a new test is actually executed,
|
||||
also pay attention to the execution time of that test. Patrole already runs
|
||||
hundreds of tests per job in its check and gate pipelines and it is important
|
||||
that the overall runtime of the jobs be constrained as much as possible.
|
||||
Consider applying the ``@decorators.attr(type='slow')``
|
||||
`test attribute decorator`_ to a test if its runtime is longer than 30 seconds.
|
||||
|
||||
.. _test attribute decorator: https://docs.openstack.org/tempest/latest/HACKING.html#test-attributes
|
||||
|
||||
|
||||
Unit Tests
|
||||
----------
|
||||
For any change that adds new functionality to common functionality unit tests
|
||||
are required. This is to ensure we don't introduce future regressions and to
|
||||
test conditions which we may not hit in the gate runs.
|
||||
|
||||
|
||||
API Stability
|
||||
-------------
|
||||
Tests should only be added for published stable APIs. If a patch contains
|
||||
tests for an API which hasn't been marked as stable or for an API which
|
||||
doesn't conform to the `API stability guidelines
|
||||
<https://wiki.openstack.org/wiki/Governance/Approved/APIStability>`_ then it
|
||||
should not be approved.
|
||||
|
||||
Similarly, tests should only be added for policies that are covered by
|
||||
`policy in code documentation
|
||||
<https://specs.openstack.org/openstack/keystone-specs/specs/keystone/pike/policy-in-code.html>`_.
|
||||
Any existing tests that test policies not covered by such documentation
|
||||
are either:
|
||||
|
||||
* part of a service that has not yet migrated to policy in code; or
|
||||
* legacy in the sense that they were created prior to policy in code
|
||||
|
||||
For the first bullet, the tests should not be considered stable, but should be
|
||||
kept around to maintain coverage. These tests are a best-effort attempt at
|
||||
offering RBAC test coverage for the service that has not yet migrated to
|
||||
policy in code.
|
||||
|
||||
For the second bullet, the tests should be updated to conform to policy in
|
||||
code documentation, if applicable.
|
||||
|
||||
|
||||
Reject Copy and Paste Test Code
|
||||
-------------------------------
|
||||
When creating new tests that are similar to existing tests it is tempting to
|
||||
simply copy the code and make a few modifications. This increases code size and
|
||||
the maintenance burden. Such changes should not be approved if it is easy to
|
||||
abstract the duplicated code into a function or method.
|
||||
|
||||
|
||||
Tests overlap
|
||||
-------------
|
||||
When a new test is being proposed, question whether this feature is not already
|
||||
tested with Patrole. Patrole has more than 600 tests, spread amongst many
|
||||
directories, so it's easy to introduce test duplication.
|
||||
|
||||
Test Duplication
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Test duplication means:
|
||||
|
||||
* testing an API endpoint in more than one test
|
||||
* testing the same policy in more than one test
|
||||
|
||||
For the first bullet, try to avoid calling the same API inside the
|
||||
``self.override_role()`` call.
|
||||
|
||||
.. note::
|
||||
|
||||
If the same API is tested against different policies, consider combining
|
||||
the different tests into only 1 test, that tests the API against all
|
||||
the policies it enforces.
|
||||
|
||||
For the second bullet, try to avoid testing the same policies across multiple
|
||||
tests.
|
||||
|
||||
.. note::
|
||||
|
||||
This is not always possible since policy granularity doesn't exist for all
|
||||
APIs. In cases where policy granularity doesn't exist, make sure that the
|
||||
policy overlap only exists for the non-granular APIs that enforce the same
|
||||
policy.
|
||||
|
||||
|
||||
Being explicit
|
||||
--------------
|
||||
When tests are being added that depend on a configurable feature or extension,
|
||||
polling the API to discover that it is enabled should not be done. This will
|
||||
just result in bugs being masked because the test can be skipped automatically.
|
||||
Instead the config file should be used to determine whether a test should be
|
||||
skipped or not. Do not approve changes that depend on an API call to determine
|
||||
whether to skip or not.
|
||||
|
||||
|
||||
Multi-Policy Guidelines
|
||||
-----------------------
|
||||
|
||||
Care should be taken when using multiple policies in an RBAC test. The
|
||||
following guidelines should be followed before deciding to add multiple
|
||||
policies to a Patrole test.
|
||||
|
||||
.. _general-multi-policy-guidelines:
|
||||
|
||||
General Multi-policy API Code Guidelines
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The list below enumerates guidelines beginning with those with the highest
|
||||
priority and ending with those with the lowest priority. A higher priority
|
||||
item takes precedence over lower priority items.
|
||||
|
||||
#. Order the policies in the ``rules`` parameter chronologically with respect
|
||||
to the order they're called by the API endpoint under test.
|
||||
#. Only use policies that map to the API by referencing the appropriate policy
|
||||
in code documentation.
|
||||
#. Only include the minimum number of policies needed to test the API
|
||||
correctly: don't add extraneous policies.
|
||||
#. If possible, only use policies that directly relate to the API. If the
|
||||
policies are used across multiple APIs, try to omit it. If a "generic"
|
||||
policy needs to be added to get the test to pass, then this is fair game.
|
||||
#. Limit the number of policies to a reasonable number, such as 3.
|
||||
|
||||
Neutron Multi-policy API Code Guidelines
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Because Neutron can raise a 403 or 404 following failed authorization, Patrole
|
||||
uses the ``expected_error_codes`` parameter to accommodate this behavior.
|
||||
Each policy action enumerated in ``rules`` must have a corresponding entry
|
||||
in ``expected_error_codes``. Each expected error code must be either a 403 or a
|
||||
404, which indicates that, when policy enforcement fails for the corresponding
|
||||
policy action, that error code is expected by Patrole. For more information
|
||||
about these parameters, see :ref:`rbac-validation`.
|
||||
|
||||
The list below enumerates additional multi-policy guidelines that apply in
|
||||
particular to Neutron. A higher priority item takes precedence over lower
|
||||
priority items.
|
||||
|
||||
#. Order the expected error codes in the ``expected_error_codes`` parameter
|
||||
chronologically with respect to the order each corresponding policy in
|
||||
``rules`` is authorized by the API under test.
|
||||
#. Ensure the :ref:`neutron-multi-policy-validation` is followed when
|
||||
determining the expected error code for each corresponding policy.
|
||||
|
||||
The same guidelines under :ref:`general-multi-policy-guidelines` should be
|
||||
applied afterward.
|
||||
|
||||
|
||||
Release Notes
|
||||
-------------
|
||||
Release notes are how we indicate to users and other consumers of Patrole what
|
||||
has changed in a given release. There are certain types of changes that
|
||||
require release notes and we should not approve them without including a release
|
||||
note. These include but aren't limited to, any addition, deprecation or removal
|
||||
from the framework code, any change to configuration options (including
|
||||
deprecation), major feature additions, and anything backwards incompatible or
|
||||
would require a user to take note or do something extra.
|
||||
|
||||
|
||||
Deprecated Code
|
||||
---------------
|
||||
Sometimes we have some bugs in deprecated code. Basically, we leave it. Because
|
||||
we don't need to maintain it. However, if the bug is critical, we might need to
|
||||
fix it. When it will happen, we will deal with it on a case-by-case basis.
|
||||
|
||||
|
||||
When to approve
|
||||
---------------
|
||||
* Every patch can be approved with single +2 which means single reviewer can approve.
|
||||
* It's OK to hold off on an approval until a subject matter expert reviews it.
|
||||
* If a patch has already been approved but requires a trivial rebase to merge,
|
||||
you do not have to wait for a +2, since the patch has already had +2's. With
|
||||
single +2 rule, this means that author can also approve this case if he/she has
|
||||
approve rights.
|
||||
@ -1,25 +0,0 @@
|
||||
====================
|
||||
Enabling in Devstack
|
||||
====================
|
||||
|
||||
.. warning::
|
||||
|
||||
The ``stack.sh`` script must be run in a disposable VM that is not
|
||||
being created automatically. See the `README file`_ in the DevStack
|
||||
repository for more information.
|
||||
|
||||
1. Download DevStack::
|
||||
|
||||
git clone https://git.openstack.org/openstack-dev/devstack.git
|
||||
cd devstack
|
||||
|
||||
2. Patrole can be installed like any other DevStack plugin by including the
|
||||
``enable_plugin`` directive inside local.conf::
|
||||
|
||||
> cat local.conf
|
||||
[[local|localrc]]
|
||||
enable_plugin patrole https://git.openstack.org/openstack/patrole
|
||||
|
||||
3. Run ``stack.sh`` found in the DevStack repo.
|
||||
|
||||
.. _README file: https://git.openstack.org/cgit/openstack-dev/devstack/plain/README.rst
|
||||
@ -1,179 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Plugin file for Patrole Tempest plugin
|
||||
# --------------------------------------
|
||||
|
||||
# Dependencies:
|
||||
# ``functions`` file
|
||||
# ``DEST`` must be defined
|
||||
|
||||
# Save trace setting
|
||||
XTRACE=$(set +o | grep xtrace)
|
||||
set -o xtrace
|
||||
|
||||
function install_patrole_tempest_plugin {
|
||||
setup_package $PATROLE_DIR -e
|
||||
|
||||
if [[ ${DEVSTACK_SERIES} == 'pike' ]]; then
|
||||
IFS=',' read -ra roles_array <<< "$RBAC_TEST_ROLES"
|
||||
RBAC_TEST_ROLES=""
|
||||
for i in "${roles_array[@]}"; do
|
||||
if [[ $i == "member" ]]; then
|
||||
i="Member"
|
||||
fi
|
||||
RBAC_TEST_ROLES="$i,$RBAC_TEST_ROLES"
|
||||
done
|
||||
|
||||
# Policies used by Patrole testing that were changed in a backwards-incompatible way.
|
||||
# TODO(felipemonteiro): Remove these once stable/pike becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled create_port_fixed_ips_ip_address_policy False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled update_port_fixed_ips_ip_address_policy False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled limits_extension_used_limits_policy False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled volume_extension_volume_actions_attach_policy False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled volume_extension_volume_actions_reserve_policy False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled volume_extension_volume_actions_unreserve_policy False
|
||||
|
||||
# TODO(cl566n): Remove these once stable/pike becomes EOL.
|
||||
# These policies were removed in Stein but are available in Pike.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_stein False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_keystone_policies_stein False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled added_cinder_policies_stein False
|
||||
|
||||
# TODO(rb560u): Remove this once stable/pike becomes EOL.
|
||||
# Make the 'test_list_trusts' test backwards compatible.
|
||||
# The Keystone Trust API is enforced differently depending on passed
|
||||
# arguments
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled keystone_policy_enforcement_train False
|
||||
|
||||
# TODO(rb560u): Remove this once stable/pike becomes EOL.
|
||||
# These policies were removed in Ussuri but are available in Pike.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_ussuri False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_victoria False
|
||||
|
||||
# TODO(gmann): Remove these once stable/victoria becomes EOL.
|
||||
# These policies were removed in Wallaby.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_wallaby False
|
||||
fi
|
||||
|
||||
if [[ ${DEVSTACK_SERIES} == 'queens' ]]; then
|
||||
IFS=',' read -ra roles_array <<< "$RBAC_TEST_ROLES"
|
||||
RBAC_TEST_ROLES=""
|
||||
for i in "${roles_array[@]}"; do
|
||||
if [[ $i == "member" ]]; then
|
||||
i="Member"
|
||||
fi
|
||||
RBAC_TEST_ROLES="$i,$RBAC_TEST_ROLES"
|
||||
done
|
||||
|
||||
# TODO(cl566n): Remove these once stable/queens becomes EOL.
|
||||
# These policies were removed in Stein but are available in Queens.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_stein False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_keystone_policies_stein False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled added_cinder_policies_stein False
|
||||
|
||||
# TODO(rb560u): Remove this once stable/queens becomes EOL.
|
||||
# Make the 'test_list_trusts' test backwards compatible.
|
||||
# The Keystone Trust API is enforced differently depending on passed
|
||||
# arguments
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled keystone_policy_enforcement_train False
|
||||
|
||||
# TODO(rb560u): Remove this once stable/queens becomes EOL.
|
||||
# These policies were removed in Ussuri but are available in Queens.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_ussuri False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_victoria False
|
||||
|
||||
# TODO(gmann): Remove these once stable/victoria becomes EOL.
|
||||
# These policies were removed in Wallaby.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_wallaby False
|
||||
|
||||
# TODO(gmann): Remove these once stable/xena becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_cinder_policies_xena False
|
||||
fi
|
||||
|
||||
if [[ ${DEVSTACK_SERIES} == 'rocky' ]]; then
|
||||
# TODO(cl566n): Policies used by Patrole testing. Remove these once stable/rocky becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_stein False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled added_cinder_policies_stein False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_keystone_policies_stein False
|
||||
|
||||
# TODO(rb560u): Remove this once stable/rocky becomes EOL.
|
||||
# Make the 'test_list_trusts' test backwards compatible.
|
||||
# The Keystone Trust API is enforced differently depending on passed
|
||||
# arguments
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled keystone_policy_enforcement_train False
|
||||
|
||||
# TODO(rb560u): Remove this once stable/rocky becomes EOL.
|
||||
# These policies were removed in Ussuri but are available in Rocky.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_ussuri False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_victoria False
|
||||
|
||||
# TODO(gmann): Remove these once stable/victoria becomes EOL.
|
||||
# These policies were removed in Wallaby.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_wallaby False
|
||||
|
||||
# TODO(gmann): Remove these once stable/xena becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_cinder_policies_xena False
|
||||
fi
|
||||
|
||||
if [[ ${DEVSTACK_SERIES} == 'stein' ]]; then
|
||||
# TODO(rb560u): Remove this once stable/stein becomes EOL.
|
||||
# Make the 'test_list_trusts' test backwards compatible.
|
||||
# The Keystone Trust API is enforced differently depending on passed
|
||||
# arguments
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled keystone_policy_enforcement_train False
|
||||
|
||||
# TODO(rb560u): Remove this once stable/stein becomes EOL.
|
||||
# These policies were removed in Ussuri but are available in Stein.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_ussuri False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_victoria False
|
||||
|
||||
# TODO(gmann): Remove these once stable/victoria becomes EOL.
|
||||
# These policies were removed in Wallaby.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_wallaby False
|
||||
# TODO(gmann): Remove these once stable/xena becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_cinder_policies_xena False
|
||||
fi
|
||||
|
||||
if [[ ${DEVSTACK_SERIES} == 'train' ]]; then
|
||||
# Remove this once stable/train becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_ussuri False
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_victoria False
|
||||
# TODO(gmann): Remove these once stable/victoria becomes EOL.
|
||||
# These policies were removed in Wallaby.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_wallaby False
|
||||
# TODO(gmann): Remove these once stable/xena becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_cinder_policies_xena False
|
||||
fi
|
||||
|
||||
if [[ ${DEVSTACK_SERIES} == 'ussuri' ]]; then
|
||||
# Remove this once stable/ussuri becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_nova_policies_victoria False
|
||||
# TODO(gmann): Remove these once stable/victoria becomes EOL.
|
||||
# These policies were removed in Wallaby.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_wallaby False
|
||||
# TODO(gmann): Remove these once stable/xena becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_cinder_policies_xena False
|
||||
fi
|
||||
|
||||
if [[ ${DEVSTACK_SERIES} == 'victoria' ]]; then
|
||||
# TODO(gmann): Remove these once stable/victoria becomes EOL.
|
||||
# These policies were removed in Wallaby.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled removed_nova_policies_wallaby False
|
||||
# TODO(gmann): Remove these once stable/xena becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_cinder_policies_xena False
|
||||
fi
|
||||
if [[ ${DEVSTACK_SERIES} == 'wallaby' ]]; then
|
||||
# TODO(gmann): Remove these once stable/xena becomes EOL.
|
||||
iniset $TEMPEST_CONFIG policy-feature-enabled changed_cinder_policies_xena False
|
||||
fi
|
||||
iniset $TEMPEST_CONFIG patrole rbac_test_roles $RBAC_TEST_ROLES
|
||||
}
|
||||
|
||||
if is_service_enabled tempest; then
|
||||
if [[ "$1" == "stack" && "$2" == "test-config" ]]; then
|
||||
echo_summary "Installing Patrole Tempest plugin"
|
||||
install_patrole_tempest_plugin
|
||||
fi
|
||||
fi
|
||||
|
||||
# Restore xtrace
|
||||
$XTRACE
|
||||
@ -1,8 +0,0 @@
|
||||
# Settings needed for the Patrole Tempest plugin
|
||||
# ----------------------------------------------
|
||||
|
||||
PATROLE_DIR=$DEST/patrole
|
||||
TEMPEST_DIR=$DEST/tempest
|
||||
TEMPEST_CONFIG_DIR=${TEMPEST_CONFIG_DIR:-$TEMPEST_DIR/etc}
|
||||
TEMPEST_CONFIG=$TEMPEST_CONFIG_DIR/tempest.conf
|
||||
RBAC_TEST_ROLE=${RBAC_TEST_ROLE:-admin}
|
||||
@ -1,8 +0,0 @@
|
||||
# The order of packages is significant, because pip processes them in the order
|
||||
# of appearance. Changing the order has an impact on the overall integration
|
||||
# process, which may cause wedges in the gate later.
|
||||
sphinx>=2.0.0,!=2.1.0 # BSD
|
||||
openstackdocstheme>=2.2.0 # Apache-2.0
|
||||
reno>=3.1.0 # Apache-2.0
|
||||
sphinxcontrib-apidoc>=0.2.0 # BSD
|
||||
sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
|
||||
@ -1,5 +0,0 @@
|
||||
====================
|
||||
Patrole Coding Guide
|
||||
====================
|
||||
|
||||
.. include:: ../../HACKING.rst
|
||||
@ -1,5 +0,0 @@
|
||||
======================
|
||||
Reviewing Patrole Code
|
||||
======================
|
||||
|
||||
.. include:: ../../REVIEWING.rst
|
||||
@ -1,110 +0,0 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
# 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.
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
sys.path.insert(0, os.path.abspath('../../'))
|
||||
sys.path.insert(0, os.path.abspath('../'))
|
||||
sys.path.insert(0, os.path.abspath('./'))
|
||||
|
||||
# -- General configuration ----------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx.ext.viewcode',
|
||||
'sphinxcontrib.rsvgconverter',
|
||||
'openstackdocstheme',
|
||||
'oslo_config.sphinxconfiggen',
|
||||
'sphinxcontrib.apidoc',
|
||||
]
|
||||
|
||||
# sphinxcontrib.apidoc options
|
||||
apidoc_module_dir = '../../patrole_tempest_plugin'
|
||||
apidoc_output_dir = 'framework/code'
|
||||
apidoc_excluded_paths = [
|
||||
'hacking',
|
||||
'hacking/*',
|
||||
'tests',
|
||||
'tests/*',
|
||||
'config.py',
|
||||
'plugin.py',
|
||||
'version.py'
|
||||
]
|
||||
apidoc_separate_modules = True
|
||||
|
||||
config_generator_config_file = '../../etc/config-generator.patrole.conf'
|
||||
sample_config_basename = '_static/patrole'
|
||||
|
||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||
# text edit cycles.
|
||||
# execute "export SPHINX_DEBUG=1" in your terminal to disable
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
|
||||
copyright = u'2017, Patrole Developers'
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
add_function_parentheses = True
|
||||
|
||||
# If true, the current module name will be prepended to all description
|
||||
# unit titles (such as .. function::).
|
||||
add_module_names = True
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
||||
# Sphinx are currently 'default' and 'sphinxdoc'.
|
||||
# html_theme_path = ["."]
|
||||
html_theme = 'openstackdocs'
|
||||
|
||||
# openstackdocstheme options
|
||||
openstackdocs_repo_name = 'openstack/patrole'
|
||||
openstackdocs_pdf_link = True
|
||||
openstackdocs_bug_project = 'patrole'
|
||||
openstackdocs_bug_tag = ''
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'patroledoc'
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
#intersphinx_mapping = {'http://docs.python.org/': None}
|
||||
|
||||
# -- Options for LaTeX output -------------------------------------------------
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass
|
||||
# [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'doc-patrole.tex', u'Patrole: Tempest Plugin for RBAC Testing',
|
||||
u'OpenStack Foundation', 'manual'),
|
||||
]
|
||||
|
||||
# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
|
||||
latex_use_xindy = False
|
||||
@ -1,94 +0,0 @@
|
||||
.. _patrole-configuration:
|
||||
|
||||
Patrole Configuration Guide
|
||||
===========================
|
||||
|
||||
Patrole can be customized by updating Tempest's ``tempest.conf`` configuration
|
||||
file. All Patrole-specific configuration options should be included under
|
||||
the ``patrole`` group.
|
||||
|
||||
RBAC Test Roles
|
||||
---------------
|
||||
|
||||
The RBAC test roles govern the list of roles to be used when running Patrole
|
||||
tests. For example, setting ``rbac_test_roles`` to "admin" will execute all
|
||||
RBAC tests using admin credentials. Changing the ``rbac_test_roles`` value
|
||||
will `override` Tempest's primary credentials to use that role.
|
||||
|
||||
This implies that, if ``rbac_test_roles`` is "admin", regardless of the Tempest
|
||||
credentials used by a client, the client will be calling APIs using the admin
|
||||
role. That is, ``self.os_primary.servers_client`` will run as though it were
|
||||
``self.os_admin.servers_client``.
|
||||
|
||||
Similarly, setting ``rbac_test_roles`` with various roles, results in
|
||||
Tempest's primary credentials being overridden by the roles specified by
|
||||
``rbac_test_roles``.
|
||||
|
||||
.. note::
|
||||
|
||||
Only the roles of the primary Tempest credentials ("os_primary") are
|
||||
modified. The ``user_id`` and ``project_id`` remain unchanged.
|
||||
|
||||
Custom Policy Files
|
||||
-------------------
|
||||
|
||||
Patrole supports testing custom policy file definitions, along with default
|
||||
policy definitions. Default policy definitions are used if custom file
|
||||
definitions are not specified. If both are specified, the custom policy
|
||||
definition takes precedence (that is, replaces the default definition,
|
||||
as this is the default behavior in OpenStack).
|
||||
|
||||
The ``custom_policy_files`` option allows a user to specify a comma-separated
|
||||
list of custom policy file locations that are on the same host as Patrole.
|
||||
Each policy file must include the name of the service that is being tested:
|
||||
for example, if "compute" tests are executed, then Patrole will use the first
|
||||
policy file contained in ``custom_policy_files`` that contains the "nova"
|
||||
keyword.
|
||||
|
||||
.. note::
|
||||
|
||||
Patrole currently does not support policy files located on a host different
|
||||
than the one on which it is running.
|
||||
|
||||
Policy Feature Flags
|
||||
--------------------
|
||||
|
||||
Patrole's ``[policy-feature-enabled]`` configuration group includes one option
|
||||
per supported policy feature flag. These feature flags are introduced when an
|
||||
OpenStack service introduces a new policy or changes a policy in a
|
||||
backwards-incompatible way. Since Patrole is branchless, it copes with the
|
||||
unexpected policy change by making the relevant policy change as well, but
|
||||
also introduces a new policy feature flag so that the test won't break N-1/N-2
|
||||
releases where N is the currently supported release.
|
||||
|
||||
The default value for the feature flag is enabled for N and disabled for any
|
||||
releases prior to N in which the feature is not available. This is done by
|
||||
overriding the default value of the feature flag in DevStack's ``lib/patrole``
|
||||
installation script. The change is made in Tempest's DevStack script because
|
||||
Patrole's DevStack plugin is hosted in-repo, which is branch-less (whereas
|
||||
the former is branched).
|
||||
|
||||
After the backwards-incompatible change no longer affects any supported
|
||||
release, then the corresponding policy feature flag is removed.
|
||||
|
||||
For more information on feature flags, reference the relevant
|
||||
`Tempest documentation`_.
|
||||
|
||||
.. _Tempest documentation: https://docs.openstack.org/tempest/latest/HACKING.html#new-tests-for-new-features
|
||||
|
||||
Sample Configuration File
|
||||
-------------------------
|
||||
|
||||
The following is a sample Patrole configuration for adaptation and use. It is
|
||||
auto-generated from Patrole when this documentation is built, so
|
||||
if you are having issues with an option, please compare your version of
|
||||
Patrole with the version of this documentation.
|
||||
|
||||
Note that the Patrole configuration options actually live inside the Tempest
|
||||
configuration file; at runtime, Tempest populates its own configuration
|
||||
file with Patrole groups and options, assuming that Patrole is correctly
|
||||
installed and recognized as a plugin.
|
||||
|
||||
The sample configuration can also be viewed in `file form <_static/patrole.conf.sample>`_.
|
||||
|
||||
.. literalinclude:: _static/patrole.conf.sample
|
||||
@ -1,57 +0,0 @@
|
||||
============================
|
||||
So You Want to Contribute...
|
||||
============================
|
||||
|
||||
For general information on contributing to OpenStack, please check out the
|
||||
`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
|
||||
It covers all the basics that are common to all OpenStack projects: the accounts
|
||||
you need, the basics of interacting with our Gerrit review system, how we
|
||||
communicate as a community, etc.
|
||||
|
||||
Below will cover the more project specific information you need to get started
|
||||
with Tempest.
|
||||
|
||||
Communication
|
||||
~~~~~~~~~~~~~
|
||||
* IRC channel ``#openstack-qa`` at OFTC
|
||||
* Mailing list (prefix subjects with ``[qa]`` for faster responses)
|
||||
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
|
||||
|
||||
Contacting the Core Team
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Please refer to the `Patrole Core Team
|
||||
<https://review.opendev.org/#/admin/groups/1673,members>`_ contacts.
|
||||