Add Policy Docs

Today operators need to read the code to work out what a policy rule actually means. That is terrible, and this spec proposes we fix that by adding a description for every policy rule.

Problem description

Operators need to read the code to understand what a policy rule controls.

Use Cases

  • Operator wants to audit the default policy rules and see if they are appropriate for their deployment.

  • Operator wants to give users access to a particular API that they currently get a 403 error when accessing.

  • Operator wants to restrict access to an API a user currently has access to.

Proposed change

We should fill in the description field for all of the policy rules in the system. To help ensure the operator doesn’t need to read the code to fully understand the impact of each rule, we should ensure:

For example, we might see something like this in the sample policy:

# Show details of a specific server
# GET /servers/{server_id}
# "os_compute_api:servers:show": "rule:admin_or_owner"

# Show real hostname of nova-compute managing the server
# Users normally only see an obfuscated hostname that is unique
# to each project. If you pass this rule, we show the real hostname
# so admins can find which host the server is on.
# GET /servers/details
# GET /servers/{server_id}
# "os_compute_api:servers:show:host_status": "rule:admin_api"

# Create a server
# POST /servers/{server_id}
# "os_compute_api:servers:create": "rule:admin_or_owner"

# Create an image from a server
# POST /servers/{server_id}/action (createImage)
# "os_compute_api:servers:create_image": "rule:admin_or_owner"

# List all host aggregates
# GET /os-aggregates
# "os_compute_api:os-aggregates:index": "rule:admin_api"

# Delete a host aggregate
# DELETE /os-aggregates/{aggregate_id}
# "os_compute_api:os-aggregates:delete": "rule:admin_api"

As an example, we would update the policy definition from:

policy.RuleDefault(SERVERS % 'show', RULE_AOO),

To something more like this:

policy.DocumentedRuleDefault(SERVERS % "show", RULE_AOO,
    "Show details of a specific server",
    operations=[{"method": "GET", "path": "/servers/{server_id}"}])

Depending on how soon DocumentedRuleDefault is available, we may fake this using a wrapper inside nova, so we can make progress before this is released. oslo.policy > 1.20 now supports multi-line descriptions.


We could try documentation separate to the code, but that has proven hard to maintain and keep in sync with the code.

Data model impact


REST API impact


Security impact

A better understanding of what each rule means can only help operators and developers get the policy configuration correct.

Notifications impact


Other end user impact


Performance Impact


Other deployer impact


Developer impact

We must add a description when adding a policy rule. These are all required arguments when creating DocumentedRuleDefault.



Primary assignee:

John Garbutt (johnthetubaguy)

Other contributors:


Work Items

  • Add docs for each policy rule

  • Ensure sample policy file renders correctly

  • Add hacking check to prefer DocumentedRuleDefault over RuleDefault


Waiting on changes to oslo.polcy before we can call this finished. Mostly we are waiting for this change:


The documentation job generates the updated policy sample file. That clearly shows which rules are left and how the updated rules look.

Documentation Impact

We get a much improved sample policy file.

We should ensure this gets into the configuration guide for Nova.





Release Name