Policy sample file generation
It is useful to deployers to have a sample configuration file outlining all
available options, and it is a burden on projects to try to keep that sample
file up to date. It would be preferable to generate that file from policies
registered in the project in the same way that it’s done for configuration
Projects which provide a sample policy file need to manually keep that up to
date with what’s being checked in the code. In practice it can often be out of
date. If all used policies are already registered in code that sample file
should just be generated.
The proposal is to add a few helpers to oslo.policy. These are intended to help
deployers maintain and trim their policy files.
- An oslo-policy-sample-generator along the same lines as the
oslo-config-generator that exists in oslo.config. A console script
‘oslo-policy-sample-generator’ will be added to oslo.policy. This script
will look at the namespace(s) in an oslo.policy.policies entry point and
from there load in a list of oslo_policy.policy.RuleDefault objects. The
sample file will be generated from this list. RuleDefault objects may
include a description string which will be included as a comment. Output
will be in the yaml format since it can include comments.
- A method for generating a policy file that contains the effective configured
policy. This will merge rules defined in a policy file with registered
default rules and output a full policy file with the result. By referencing
this file a deployer can know exactly how a rule is set.
- A method for retrieving a list of policies loaded from a policy file which
match the default registered rules. These are policies that are not
necessary to be in a policy file so this output will help deployers trim
their file overrides.
- A method for generating a yaml version of a policy file. This will read in
the current policy file(s) and output a yaml version of those rules. This
can be used to convert from a json format poliy file to yaml format. It must
be noted that rules are not sorted so the output may not be directly
diffable against the output of #1 or #2 above.
Files to change:
- olso_policy/generator.py (new file)
- setup.cfg (register an entry point)
Policy sample files could continue to be maintained manually.
Impact on Existing APIs
A new “oslo-policy-sample-generator” console script would be registered in
setup.cfg. This doesn’t affect existing APIs, it is purely additive.
None. This is done outside of a service running and serving requests.
Sample policy.yaml files can be generated. This does not affect any current
configuration, it is a tool to help those who would like to configure their
Projects wishing to take advantage of this will need to register all policy
checks in order to be included in the sample file. Developers should add this
registration for existing policy checks, and register new policy checks when
they are added.
There is no direct testing impact here. However this does enable other projects
to have a test job which ensure that the sample file can be generated. Details
on how this might be accomplished will be documented as part of this change.
- Primary assignee:
- Other contributors:
- Target Milestone for completion:
- Add an oslo_policy/generator.py modeled after the one on oslo.config.
- Add policy sample generation.
- Add generation of effective policy.
- Add method for determining default rule definitions in a policy file.
- Add generation of yaml policy file from current policy file(s).
- Add an entry_point to oslo.policy setup.cfg to create a console script.
- Document how a consuming project might configure themselves to use the file
generation ability, or setup a tox target to be used for testing.
Nova would like to use this
Anticipated API Stabilization
The ability to generate policy files will be documented in developer facing
documentation. Any deployer facing changes will be the responsibility of
consuming projects to document as they switch over to using policy