Add appendix on Policy Overrides

Add a general appendix about how policy overrides work.

Change-Id: Ic2b1f85cc7ad41d6fe69d379736d5dec614ef176

deploy-guide/source/app-policy-overrides.rst

@@ -0,0 +1,139 @@
+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
+  <https://jaas.ai/docs/juju-resources>`_.
+- 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.

deploy-guide/source/app.rst

@@ -18,3 +18,4 @@ Appendices
    app-ceph-rbd-mirror.rst
    app-masakari.rst
    app-erasure-coding.rst
+   app-policy-overrides.rst