Appendix N: Policy Overrides

Overview

This appendix explains the purpose of policy overrides and shows how to enable them.

Important

Overrides are available on a per-charm basis and will be noted in a charm’s README. Always consult the charm documentation prior to enabling this feature.

Background

The Policy Overrides feature provides a mechanism for operators to modify the policies within OpenStack services in order to manage the permissions of the tenants and users of the system. It is NOT intended that this facility is used to manage the permissions of the services themselves, and steps are taken to prevent this where possible. The charms will continue to manage the policies of the service users directly (e.g. keystone, glance, nova) using the default policy files within the charms themselves.

The preferred approach has always been to use charm options to enable a more controlled approach to modifying the policy of a service by providing templates that the options modify - i.e. a controlled approach that always results in consistent policy files.

However, over time, it has become apparent that there will always be an aspect of the policy of a service that an operator wants to tweak or change that the charm authors hadn’t considered, and the cycle time to introduce the option exceeds the expectations of the delay that an operator is willing to tolerate.

Therefore, it has been recognised that there are aspects of the configuration files that the charms control need to be more fluidly modifiable by operators. These tend to be orthogonal to the act of deployment and instead are to do with operating the cloud.

So, the objective is to provide operators with a mechanism to override the policy defaults without (hopefully) breaking the cloud. The policy defaults are either coded in the service via “policy-in-code” and/or via a default policy YAML file provided by the charm/service.

Facility offered

The general facility offered is the ability to:

  • Create YAML files that contain any rules that are allowed in policy files for each service.

  • The YAML files are placed into a zip file.

  • The ZIP file will be attached/uploaded to the charm as a Juju resource.

  • A config item named use-policyd-override is set to True.

This will cause the charm to unzip the attached file, do some validation checks, and then drop the file(s) in the /etc/<service-name>/policy.d/ directory. The OpenStack service will then use these overrides to add to, change, or remove the default charm- or package-determined policies and thus provide the permissions that the operator requires.

Some charms may wish to provide a template system with the policy overrides. In this case the override file may include template variables that the charm will substitute with data that the charm has from config, the enviroment, or through relation data. This will be documented within the charms’ README file.

Policies across the OpenStack services

The policy override system described here is per charm. Thus if several services require policy overrides then a policy override resource ZIP file needs to be created for each charm and applied to the service.

Requirements

Policy overrides are charm dependent, so the individual charm README files should be consulted. However, the following general issues may arise:

  • The ZIP file is not properly formatted. Check that a pkunzip program can open and test the enclosed files.

  • There are no files in the zip file that have an extension of .yaml, or .yml.

  • There are duplicate named files after the ZIP file has been processed. Directories in the zip file are “flattened” such that all of the files appear as a simple list. Each of these flattened filename is lower-cased. At this point any duplicates will cause a failure. This processing is done so that the policy.d directory for the OpenStack service is a simple list of unambiguous files.

  • An identified YAML file in the zip file is not formatted correctly; as it can’t be loaded, it won’t be written to the policy.d override folder.

  • The template substitution function errors.

  • A blacklisted key has been used in the policy override. Individual charms may choose to disallow the override of particular rules in the policy file. In this case the policy file will be rejected.

Any problems with the overrides will be indicated in the output for juju status. See next section Applying overrides.

Note

The hook (install, upgrade, config-changed) will not fail if the policy override is broken. The policy overrides will not be installed, and the status line will indicate a failure. It is not a charm breakage if the policy overrides are not installed as the overrides should be orthogonal to the operation of the charm. i.e. they are to do with tenants and user permissions, and not the operation of the underlying services.

Applying overrides

Policy overrides for an OpenStack service are applied by attaching the ZIP file to the corresponding charm and then enabling them by passing an option to the charm. These are both done via Juju commands.

The file containing policy override files is attached to the charm in this way:

juju attach-resource <charm-name> policyd-override=<overrides.zip>

The policy override is enabled in the charm using:

juju config <charm-name> use-policyd-override=true

Juju status

The status of the overrides for a Juju application is shown in the output for the juju status command. When overrides are successful the text PO: (for Policy Overrides) will be prefixed to the application’s status message. When they are unsuccessful PO: (broken) will be used.

Unsuccessful overrides imply that none of the default policies have been modified. In this case, the operator should either fix and re-attach them to the charm or disable the overrides entirely (i.e. set use-policyd-overrides to ‘false’).

Information on broken overrides will appear in the logs.