Register and Document Policy in Code

OpenStack services typically have a file that describes and enforces policy or Role Based Access Control for the APIs of that service. The file is usually maintained in the project source and documents the default policy values. The goal here would be to move default policy definitions from file-based maintenance to registering them in code. This is very similar to how we treat default configuration values.

By registering and documenting default policy in code, we see the following benefits for operators and developers:

1. The policy file can be removed for deployments that don’t modify any default policies. This continues to move configuration out of /etc/$PROJECT/ directories and into code, which naturally enables easier upgrades.

2. Operators can remove default checks from policy files. The result is that their policy file only contains the overridden policies they need for their deployment. This makes auditing and policy maintenance easier.

3. Tooling can be used to generate sample policy files.

4. Tooling can be used to generate complete policy files that include overrides from a specific policy file.

5. Documentation describing each policy is generated and available to assist operators.

6. Project developers have a way to communicate changing defaults to operators through a library. Think of this like marking configuration values for deprecation or removal. The important bit is that we have a programmatic way to signal those changes for operators.

7. Project developers use the process of moving defaults into code and documenting them as an exercise for understanding the default policies within the project and how they might be improved.

By doing this, it becomes easier for developers and operators to move towards a more flexible set of roles by introducing better, or more granular, defaults. The change is backwards compatible and allows operators to continue overriding policies their deployment relies on.

Champion

Goals need a main driver to project-manage them to completion. Project teams need assistance, reminders and sometimes direct help in order for them to complete the goals.

Lance Bragstad (lbragstad) has volunteered to drive this goal.

Gerrit Topic

To facilitate tracking, commits related to this goal should use the gerrit topic:

policy-and-docs-in-code

Completion Criteria

For all projects:

1. Use oslo.policy to register default policies in code that map to the defaults described in policy files.

2. Each policy must contain a description that describes the API the policy is intended to protect.

3. Ensure default policies that are registered in code can be overridden by operators.

4. Ensure oslo.policy endpoints can be used to leverage tooling for generating default policy files, or producing custom policy files that consist of defaults in addition to overrides specified by operators in existing policy files. This mainly consists of exposing oslo.policy endpoints in each project’s setup.cfg file. An example can be found in some of the existing services.

References

This effort was discussed during the Newton design summit and has been completed by a few projects already. The etherpad capturing the original discussion describes the approach.

The following specifications detail the work done already by specific projects:

• Nova policy-in-code specification

• Nova policy-docs specification

• Keystone policy-in-code specification

• Keystone policy-docs specification

Current State / Anticipated Impact

Note that this goal does not require the changing of default policies and only specifies moving the defaults into code and documenting them. If at a later time the community comes together and agrees upon a direction using specific defaults, we can leverage this work to make that transition easier.

As noted in the section above, the nova and keystone projects have already completed these items as of the Pike release. The patterns used to implement policy and policy documentation in code by these projects can serve as a reference for other projects looking to complete the aforementioned goals.

Project Teams

barbican

Planning Artifacts:

Completion Artifacts:

• barbican implementation

Chef OpenStack

Goal not applicable.

cinder

Planning Artifacts:

• cinder policy-in-code blueprint

Completion Artifacts:

• cinder policy-in-code implementation

• cinder documentation update

cloudkitty

Planning Artifacts:

Cloudkitty used this document as the planning artifact for this goal.

Completion Artifacts:

• cloudkitty implementation

congress

Planning Artifacts:

• congress planning

Completion Artifacts:

• congress implementation

designate

Planning Artifacts:

• designate policy-in-code blueprint

Completion Artifacts:

• designate documented policy-in-code implementation

• designate policy documentation

Documentation

Goal not applicable.

dragonflow

Goal not applicable.

ec2-api

Planning Artifacts:

Completion Artifacts:

freezer

Planning Artifacts:

Completion Artifacts:

• Freezer API implementation

fuel

Planning Artifacts:

Completion Artifacts:

glance

Planning Artifacts:

• Spec Lite: Community Goal: Register and Document Policy in Code

Completion Artifacts:

• Glance did not complete this goal during the Queens cycle. We will be discussing refactoring the way Glance handles policies at the Rocky PTG. In light of that (and in light of the fact that the development team is currently under-powered), we felt that it did not make sense to work on this goal during Queens.

  The implementation for moving policy into code was completed in Ussuri. Work remains to document each policy.

heat

Planning Artifacts:

• heat specification

Completion Artifacts:

• heat implementation

horizon

Goal not appliable.

I18n

Goal not applicable.

Infrastructure

Planning Artifacts:

Completion Artifacts:

ironic

The ironic project moved default policies into code during the Newton release. The Queens release will focus on documenting policies and using the new DocumentedRuleDefault object.

Planning Artifacts:

• ironic policy-in-code bug

• ironic documenting policy bug

Completion Artifacts:

• ironic documented policy-in-code implementation

• ironic policy documentation

ironic-inspector

Until Queens, ironic-inspector project had no configurable API access policies. They were implemented in Queens, with documented policies in code from the start.

Planning Artifacts:

• inspector policy-in-code bug

Completion Artifacts:

• inspector policies implementation

• inspector policies documentation

karbor

Planning Artifacts:

Completion Artifacts:

keystone

The keystone project completed this work in the Pike release.

Planning Artifacts:

• keystone policy-in-code specification

• keystone policy-docs specification

Completion Artifacts:

• keystone policy-in-code implementation

• keystone policy-docs implementation

kolla

Goal not applicable.

kuryr

Goal not applicable.

magnum

Planning Artifacts:

• magnum blueprint

Completion Artifacts:

• magnum implementation

manila

Planning Artifacts:

• manila blueprint

Completion Artifacts:

• manila implementation

mistral

Planning Artifacts:

• mistral used this document as the planning artifact

Completion Artifacts:

• mistral policy-in-code implementation

• mistral policy documentation

monasca

Planning Artifacts:

Completion Artifacts:

murano

Planning Artifacts:

Murano implemented this toward the end of Pike-2 milestone.

The blueprint used was: https://blueprints.launchpad.net/murano/+spec/policy-in-code

Completion Artifacts:

The final RBAC patch in the chain was: https://review.opendev.org/#/c/473562/

The policy documentation is available here: https://docs.openstack.org/murano/latest/admin/murano_policies.html

neutron

Neutron implemented this towards the end of the Stein-2 milestone.

Planning Artifacts:

• neutron policy-in-code specification

Completion Artifacts:

• neutron policy-in-code implementation

nova

Note that nova moved policy into code during the Newton release and formally documented it in Pike.

Planning Artifacts:

• nova policy-in-code specification

• nova policy-docs specification

Completion Artifacts:

• nova policy-in-code implementation

• nova policy-docs implementation

octavia

Planning Artifacts:

Octavia implemented this as part of our new endpoint in Pike.

The tracking bug was: https://bugs.launchpad.net/octavia/+bug/1690481

Completion Artifacts:

The final RBAC patch in the chain merged while Pike was still in development: https://review.opendev.org/#/c/475980/

The policy documentation is available here: https://docs.openstack.org/octavia/latest/configuration/policy.html

OpenStack Charms

Goal not applicable.

OpenStackAnsible

Planning Artifacts:

We’ll have to adapt on the other project’s completion artifacts, and everything will be analysed case by case.

Completion Artifacts:

We already have a mechanism to adapt to policy in code (see our Keystone Role).

OpenStackClient

Goal not applicable.

oslo

Goal not applicable.

Packaging-deb

Goal not applicable.

Packaging-rpm

Goal not applicable.

Puppet OpenStack

Goal not applicable.

Quality Assurance

Goal not applicable.

rally

Goal not applicable.

RefStack

Goal not applicable.

Release Management

Goal not applicable.

requirements

Goal not applicable.

sahara

Planning Artifacts:

We used the community goal document found in https://governance.openstack.org/tc/goals/queens/policy-in-code.html as planning artifact.

Completion Artifacts:

The goal was implemented in https://review.opendev.org/#/c/503221/ and can be marked as done.

searchlight

Planning Artifacts:

• Work was done without the need for a bug / blueprint

Completion Artifacts:

• searchlight policy-in-code implementation

• searchlight policy documentation

Security

Goal not applicable.

senlin

Planning Artifacts:

Completion Artifacts:

• senlin implementation

shade

Goal not applicable.

solum

Planning Artifacts:

• solum blueprint

Completion Artifacts:

• solum implementation

Stable branch maintenance

Goal not applicable.

storlets

Goal not applicable.

swift

Planning Artifacts:

Completion Artifacts:

tacker

Planning Artifacts:

Completion Artifacts:

Telemetry

Planning Artifacts:

This document was used as the planning document for the Telemetry project.

Completion Artifacts:

• panko implementation

• aodh implementation

tricircle

Planning Artifacts:

This document was used as the planning artifact for tricircle.

Completion Artifacts:

• policy-in-code implementation

tripleo

Goal not applicable.

trove

Planning Artifacts:

We used the community goal document found in https://governance.openstack.org/tc/goals/queens/policy-in-code.html as planning artifact.

Completion Artifacts:

• trove policy-in-code implementation

vitrage

Planning Artifacts:

Completion Artifacts:

• https://review.opendev.org/#/c/509217/

watcher

Planning Artifacts:

• watcher policy-in-code blueprint

Completion Artifacts:

• watcher policy-in-code implementation

winstackers

Goal not applicable.

zaqar

Planning Artifacts:

Completion Artifacts:

zun

Planning Artifacts:

TBD, checking with the Zun team to see if they want a specification for this or if this can serve as the planning artifact.

Completion Artifacts:

• zun implementation