Docs: Add documentation on policy feature flags
This is to add documentation on policy feature flags, recently introduced in [0]. [0] Ia0d9847908a8e723446c16465d68cd7f622c04cc Depends-On: Ia47132fa596918e58f21ba9810c2c28ddcf0d584 Change-Id: I3e630c535074e3a9ce8e9b07a1909984d70cef12
This commit is contained in:
Felipe Monteiro
parent
dc7b175acb
commit
9ae705db16
64
HACKING.rst
64
HACKING.rst
|
|
@ -53,3 +53,67 @@ is also admin.
|
|||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -55,3 +55,46 @@ keyword.
|
|||
|
||||
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#1-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
|
||||
|
|
|
|||
|
|
@ -13,7 +13,6 @@ Patrole Configuration Guide
|
|||
|
||||
configuration
|
||||
usage
|
||||
sampleconf
|
||||
|
||||
Patrole Installation Guide
|
||||
--------------------------
|
||||
|
|
|
|||
|
|
@ -1,18 +0,0 @@
|
|||
.. _patrole-sampleconf:
|
||||
|
||||
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
|
||||
Loading…
Reference in New Issue