Openstack-Common/Self-Documenting Policies

= Self-Documenting Policies =

Summary
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.

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  is an accepted syntax for specifying values in stock ConfigParser.)  Variable values will, of course, be policy language strings (e.g.,  ). (Value interpolation will also have to be turned off, of course.) As an example, consider this   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 [RULES] admin_api = is_admin:True admin_or_owner = is_admin:True or project_id:%(project_id)s

[compute_extension] accounts = rule:admin_api admin_actions = rule:admin_api aggregates = rule:admin_api certificates = @ cloudpipe = rule:admin_api console_output = @

[compute_extension:admin_actions] 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  module interface, which allows for configuration options to be declared. (In the  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 , 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  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  module.)