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:

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:

Chef OpenStack

Goal not applicable.

cinder

Planning Artifacts:

Completion Artifacts:

cloudkitty

Planning Artifacts:

Completion Artifacts:

congress

Planning Artifacts:

Completion Artifacts:

Documentation

Goal not applicable.

dragonflow

Goal not applicable.

ec2-api

Planning Artifacts:

Completion Artifacts:

freezer

Planning Artifacts:

Completion Artifacts:

fuel

Planning Artifacts:

Completion Artifacts:

glance

Planning Artifacts:

Completion Artifacts:

heat

Planning Artifacts:

Completion Artifacts:

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:

Completion Artifacts:

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:

Completion Artifacts:

karbor

Planning Artifacts:

Completion Artifacts:

keystone

The keystone project completed this work in the Pike release.

Planning Artifacts:

Completion Artifacts:

kolla

Goal not applicable.

kuryr

Goal not applicable.

magnum

Planning Artifacts:

Completion Artifacts:

manila

Planning Artifacts:

Completion Artifacts:

mistral

Planning Artifacts:

Completion Artifacts:

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.openstack.org/#/c/473562/

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

neutron

Planning Artifacts:

Completion Artifacts:

nova

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

Planning Artifacts:

Completion Artifacts:

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.openstack.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.openstack.org/#/c/503221/ and can be marked as done.

searchlight

Planning Artifacts:

Completion Artifacts:

Security

Goal not applicable.

senlin

Planning Artifacts:

Completion Artifacts:

shade

Goal not applicable.

solum

Planning Artifacts:

Completion Artifacts:

Stable branch maintenance

Goal not applicable.

storlets

Goal not applicable.

swift

Planning Artifacts:

Completion Artifacts:

tacker

Planning Artifacts:

Completion Artifacts:

Telemetry

Planning Artifacts:

Completion Artifacts:

tricircle

Planning Artifacts:

This document was used as the planning artifact for tricircle.

Completion Artifacts:

tripleo

Goal not applicable.

trove

Planning Artifacts:

Completion Artifacts:

vitrage

Planning Artifacts:

Completion Artifacts:

watcher

Planning Artifacts:

Completion Artifacts:

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: