Propose spec for deprecated policies

Add a specification that details the work for deprecating policies
and why it is important.

Change-Id: If94e2bb0da83bb054fc052501d46b6ef3d243014
This commit is contained in:
Lance Bragstad 2017-09-01 17:48:14 +00:00
parent f097914f43
commit 4fffcfd4bc
1 changed files with 226 additions and 0 deletions

View File

@ -0,0 +1,226 @@
==================
Policy Deprecation
==================
https://blueprints.launchpad.net/oslo?searchtext=policy-deprecation
Several OpenStack projects have moved their policies into code and treat them
like configuration. This has numerous benefits for both developers and
operators. Moving policy into code and documenting it is targeted as a
community-wide `goal
<https://governance.openstack.org/tc/goals/queens/policy-in-code.html>`_ for
the Queens release.
Problem description
===================
Policy management in OpenStack has always been a source of operator and
developer pain. It's hard for operators to know what policies were changed or
added across releases without manually diffing policy files. Developers are
unable to programmatically communicate changes to policy files for their users.
Now that projects will be moving policies into code, we have the opportunity to
use oslo.policy to advertise deprecations and future removal of policies. This
gives developers a programmatic way to make much needed changes to policy and
communicate those changes to operators in a way they already know how to
consume. This is consistent with how we deprecate other things in OpenStack,
like configuration options.
Use Cases
---------
The following list describes the cases that need to be covered by the
deprecation functionality in oslo.policy:
* Changing the semantics of a policy in a backwards incompatible way
* Renaming a policy
* Removal of a policy in a backwards incompatible way but with a transition
plan
These can be explained further in actual use cases and examples:
1. As a developer, I need to be able to change the default role or rule for a
policy using oslo.policy
2. As a developer, I need to be able to rename a policy using oslo.policy
3. As an operator, I need to know if a policy's default role or rule is
changing so I can either copy-paste the old policy into my policy file or
create the role required by the new default
4. As an operator, I need to know if a policy that I'm overriding is going to
be renamed or removed so that APIs in my deployment aren't accidentally
unprotected or exposed in an insecure way
Example 1
^^^^^^^^^
The policy, ``"foo:create_bar": "role:fizz"``, needs to change its policy value
to ``"role:bang"``. An operator can do one of two things when upgrading. The
first option is to copy-paste the original policy into the policy file and
override the new default for ``foo:create_bar``. The second option is for the
operator to create role ``bang`` in their deployment so that the new default is
useable after the upgrade. The same process can be applied to ``rule``
evaluations in-place of ``role``.
Example 2
^^^^^^^^^
The policy, ``"foo:post_bar": "role:fizz"``, should be replaced with
``"foo:create_bar": "role:fizz"`` to be consistent with other policies used by
the service. So long as the role or rule check remains consistent there should
be no operator impact to operators using the default. The newer version of the
service will start using ``create_bar`` for policy enforcement, phasing out the
usage of ``post_bar``.
If an operator is overriding the policy for ``post_bar``, a message should be
logged saying that ``post_bar`` is no longer going to be an enforcible policy
and that ``create_bar`` should be used instead. This will give operators a
chance to fix their policy before ``post_bar`` goes away completely. This
ensures that operators don't accidentally expose ``create_bar`` if they are
using a custom policy to protect it.
Example 3
^^^^^^^^^
The policy, ``"foo:bar": "role:bazz"``, should be broken into:
* ``"foo:get_bar": "role:bazz"``
* ``"foo:list_bars": "role:bazz"``
* ``"foo:create_bar": "role:bazz"``
* ``"foo:update_bar": "role:bazz"``
* ``"foo:delete_bar": "role:bazz"``
This gives developers or operators the ability to associate different roles to
different operations of ``bar`` instances, instead of all operations on ``bar``
requiring the ``bazz`` role.
Proposed change
===============
The oslo.policy library exposes a ``DocumentedRuleDefault`` object that
policies are registered as. We can extend this object to support an optional
``deprecated`` attribute, or set of attributes that communicate information
about the deprecation. This won't require projects to change their current
policy definitions or implementations. The following are the attributes that
would be useful to expose to projects so they can improve policy:
* ``deprecated_for_removal``: This is a boolean values that denotes if the
policy is deprecated or not
* ``deprecated_reason``: This is a string containing justification for the
removal or deprecation of the policy
* ``deprecated_since``: The release in which the policy was officially
deprecated
These additional attributes should be very similar, if not the same as the
deprecated functionality of oslo.config. This change will likely be limited to
the oslo.policy library, specifically the ``DocumentedRuleDefault`` object.
Policies that are flagged for deprecation will emit log warnings similar to
using a deprecated configuration option. Likewise, deprecated policies will be
marked as such in generated sample policy files.
Alternatives
------------
Developers can continue to rely on release notes and mailing lists to
communicate policy changes to operators. This is considered suboptimal since it
is prone to human error, lacks consistency across projects, and isn't
programmable. As a result, policies are rarely changed from their original
definitions, which is very problematic since policies never evolve with the
project.
This is really the only alternative we have today, but since it doesn't really
help improve policy it could be argued as not an alternative at all.
Impact on Existing APIs
-----------------------
The API for ``DocumentedRuleDefault`` or ``RuleDefault`` will be improved to
support communicating deprecated policies.
Security impact
---------------
Projects consuming this change can use it to improve security by offering more
secure default rules.
Performance Impact
------------------
None.
Configuration Impact
--------------------
No new configuration options should be required to consume or leverage this
functionality. This should be available for projects to use once they have a
version of oslo.policy that supports deprecated information in
``DocumentedRuleDefault``.
Developer Impact
----------------
Developers will not be impacted unless they are looking to improve or modify
policies for their project. If that is the case, they can use the new
functionality to describe the reason for the deprecation, when it will be
removed, and what is replacing it.
Testing Impact
--------------
We need to ensure that deprecated policies emit some sort of warning when they
are invoked. This can likely be done in oslo.policy's tests, but it can also be
done in project consuming the tests as well. One thing to discuss might be
adding a criteria that requires a unit test for deprecating a policy.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Lance Bragstad <lbragstad@gmail.com> lbragstad
Other contributors:
None
Milestones
----------
Target Milestone for completion: queens-1
Making this available early in the Queens release will allow projects to
deprecate policies before Queens is released.
Work Items
----------
* Implement deprecated functionality in ``RuleDefault`` or
``DocumentedRuleDefault`` objects
Documentation Impact
====================
It is likely that many projects will use this functionality to deprecate and
improve their existing policies. The usage of these deprecated flags should be
well documented.
Dependencies
============
None.
References
==========
None.
.. note::
This work is licensed under a Creative Commons Attribution 3.0
Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode