Jump to: navigation, search

Openstack-Common/Self-Documenting Policies

Self-Documenting Policies


Provide an alternate policy specification file format based on ConfigParser, then use this format to allow for grouped policies (section "[compute_extensions]" variable "admin_actions:pause" would correspond to "compute_extensions:admin_actions:pause"). Additionally, allow pre-declaration of policy rules with a default policy and help text, which could then be dumped into an example policy configuration file a la nova/tools/conf/generate_sample.sh.

Alternate Policy File Format

The first alteration provided under this blueprint is to use ConfigParser to build a new policy specification format. For backwards-compatibility, of course, the JSON format will continue to be supported, so to help disambiguate file formats, alternate configuration options will be used to specify which policy file to load when using the .ini-style configuration. In using the .ini format, section and value names will be combined with a colon, with an exception for the special "[RULES]" section. (This may entail some extensions to the ConfigParser instance used for loading the policy configuration; I believe variable: value is an accepted syntax for specifying values in stock ConfigParser.) Variable values will, of course, be policy language strings (e.g., role:admin or project_id:%(project_id)s). (Value interpolation will also have to be turned off, of course.) As an example, consider this policy.json snippet, drawn from Nova:

#!highlight js
    "admin_api": "is_admin:True",
    "admin_or_owner":  "is_admin:True or project_id:%(project_id)s",
    "compute_extension:accounts": "rule:admin_api",
    "compute_extension:admin_actions": "rule:admin_api",
    "compute_extension:admin_actions:pause": "rule:admin_or_owner",
    "compute_extension:admin_actions:unpause": "rule:admin_or_owner",
    "compute_extension:admin_actions:suspend": "rule:admin_or_owner",
    "compute_extension:admin_actions:resume": "rule:admin_or_owner",
    "compute_extension:aggregates": "rule:admin_api",
    "compute_extension:certificates": "",
    "compute_extension:cloudpipe": "rule:admin_api",
    "compute_extension:console_output": "",

In this proposed policy file format, it would look like this:

#!highlight ini
admin_api = is_admin:True
admin_or_owner = is_admin:True or project_id:%(project_id)s

accounts = rule:admin_api
admin_actions = rule:admin_api
aggregates = rule:admin_api
certificates = @
cloudpipe = rule:admin_api
console_output = @

pause = rule:admin_or_owner
unpause = rule:admin_or_owner
suspend = rule:admin_or_owner
resume = rule:admin_or_owner

Policy Pre-declaration

The proposed policy pre-declaration piece of the blueprint allows for policies to be declared with a reasonable default and help text, and is somewhat dependent on the file format proposal. The idea is to duplicate a portion of the existing cfg module interface, which allows for configuration options to be declared. (In the cfg module, these declarations are mandatory, but in this proposed blueprint, they would not be.) This would allow for a policy rule to be declared near the point where it is checked, and, as already stated, a reasonable default and some helpful text can be associated with that policy rule. (To support the section separation suggested above, we would form a tree of these declarations.) Then, using a methodology similar to the existing nova/tools/conf/generate_sample.sh, we could generate a sample policy file which would help serve to guide an administrator in configuring the policies appropriately for their environment. These optional declarations would also provide a source of defaults for given rules, which would be displayed in the sample policy.ini file and which would be used if no policy configuration for that rule is given. (Undeclared rules or rules with a "None" default would fall back to the existing default rule behavior of the policy module.)