From 11e13e7fe0f2331abbc5182edd6fdc9f0e7f7265 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 8 Jan 2020 22:55:35 -0500 Subject: [PATCH] Streamline README for policy overrides The appendix in the deploy-guide has recently been refreshed. This is the first of the nine charms that support overrides to receive a streamlining in order to cut down on duplication. Change-Id: Ib4012a478226474f1e96495bd949add1c1398138 --- README.md | 45 +++++++++++++++------------------------------ 1 file changed, 15 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 47d88c54..96700bfb 100644 --- a/README.md +++ b/README.md @@ -191,43 +191,28 @@ binding provided if set. Policy Overrides ================ -This feature allows for policy overrides using the `policy.d` directory. This -is an **advanced** feature and the policies that the OpenStack service supports -should be clearly and unambiguously understood before trying to override, or -add to, the default policies that the service uses. The charm also has some -policy defaults. They should also be understood before being overridden. +Policy overrides is an **advanced** feature that allows an operator to override +the default policy of an OpenStack service. The policies that the service +supports, the defaults it implements in its code, and the defaults that a charm +may include should all be clearly understood before proceeding. > **Caution**: It is possible to break the system (for tenants and other services) if policies are incorrectly applied to the service. -Policy overrides are YAML files that contain rules that will add to, or -override, existing policy rules in the service. The `policy.d` directory is -a place to put the YAML override files. This charm owns the -`/etc/cinder/policy.d` directory, and as such, any manual changes to it will -be overwritten on charm upgrades. - -Overrides are provided to the charm using a Juju resource called -`policyd-override`. The resource is a ZIP file. This file, say -`overrides.zip`, is attached to the charm by: +Policy statements are placed in a YAML file. This file (or files) is then (ZIP) +compressed into a single file and used as an application resource. The override +is then enabled via a Boolean charm option. +Here are the essential commands (filenames are arbitrary): + zip overrides.zip override-file.yaml juju attach-resource cinder policyd-override=overrides.zip - -The policy override is enabled in the charm using: - juju config cinder use-policyd-override=true -When `use-policyd-override` is `True` the status line of the charm will be -prefixed with `PO:` indicating that policies have been overridden. If the -installation of the policy override YAML files failed for any reason then the -status line will be prefixed with `PO (broken):`. The log file for the charm -will indicate the reason. No policy override files are installed if the `PO -(broken):` is shown. The status line indicates that the overrides are broken, -not that the policy for the service has failed. The policy will be the defaults -for the charm and service. +See appendix [Policy Overrides][cdg-appendix-n] in the [OpenStack Charms +Deployment Guide][cdg] for a thorough treatment of this feature. -Policy overrides on one service may affect the functionality of another -service. Therefore, it may be necessary to provide policy overrides for -multiple service charms to achieve a consistent set of policies across the -OpenStack system. The charms for the other services that may need overrides -should be checked to ensure that they support overrides before proceeding. + + +[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide +[cdg-appendix-n]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-policy-overrides.html