Streamline README for policy overrides

The appendix in the deploy-guide has recently been
refreshed. This is the fifth of the nine charms that
support overrides to receive a streamlining in order
to cut down on duplication.

Some driveby formatting improvements.

Added a Bugs section.

Change-Id: I842c0f162c709546f41148983060af1c5f767a36

README.md

@@ -1,11 +1,9 @@
-Overview
+# Overview
-========
 
 This charm provides Keystone, the OpenStack identity service. Its target
 platform is (ideally) Ubuntu LTS + OpenStack.
 
-Usage
+# Usage
-=====
 
 The following interfaces are provided:
 
@@ -49,16 +47,14 @@ The following interfaces are provided:
   - `domain` Keystone v3 domain the user will be created in. Defaults
              to the Default domain.
 
-Database
+## Database
---------
 
 Keystone requires a database. The charm supports relation to a shared database
 server through the `mysql-shared` interface. When a new data store is
 configured, the charm ensures the minimum administrator credentials exist (as
 configured in charm configuration)
 
-HA/Clustering
+## HA/Clustering
--------------
 
 There are two mutually exclusive high availability options: using virtual
 IP(s) or DNS. In both cases, a relationship to hacluster is required which
@@ -95,8 +91,7 @@ The charm will throw an exception in the following circumstances:
 - If `dns-ha` is set and none of the `os-{admin,internal,public}-hostname`
   configuration options are set
 
-TLS/HTTPS
+## TLS/HTTPS
----------
 
 Support for TLS and HTTPS endpoints can be enabled through configuration
 options.
@@ -128,8 +123,7 @@ Example bundle usage:
   Base64 encode it before storing it as a configuration option value. The path
   can be absolute or relative to the location of the bundle file.
 
-Network Space Support
+## Spaces
----------------------
 
 This charm supports the use of Juju Network Spaces, allowing the charm to be
 bound to network space configurations managed directly by Juju. This is only
@@ -144,11 +138,15 @@ using the shared-db relation.
 To use this feature, use the --bind option when deploying the charm:
 
     juju deploy keystone --bind \
-    "public=public-space internal=internal-space admin=admin-space shared-db=internal-space"
+       "public=public-space \
+        internal=internal-space \
+        admin=admin-space \
+        shared-db=internal-space"
 
 Alternatively, these can also be provided as part of a Juju native bundle
 configuration:
 
+```yaml
     keystone:
       charm: cs:xenial/keystone
       num_units: 1
@@ -157,6 +155,7 @@ configuration:
         admin: admin-space
         internal: internal-space
         shared-db: internal-space
+```
 
 NOTE: Spaces must be configured in the underlying provider prior to attempting
 to use them.
@@ -165,51 +164,30 @@ NOTE: Existing deployments using `os\-\*-network` configuration options will
 continue to function; these options are preferred over any network space
 binding provided if set.
 
-Policy Overrides
+## Policy Overrides
-----------------
 
-This feature allows for policy overrides using the `policy.d` directory.  This
+Policy overrides is an **advanced** feature that allows an operator to override
-is an **advanced** feature and the policies that the OpenStack service supports
+the default policy of an OpenStack service. The policies that the service
-should be clearly and unambiguously understood before trying to override, or
+supports, the defaults it implements in its code, and the defaults that a charm
-add to, the default policies that the service uses.  The charm also has some
+may include should all be clearly understood before proceeding.
-policy defaults.  They should also be understood before being overridden.
 
 > **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
+Policy statements are placed in a YAML file. This file (or files) is then (ZIP)
-override, existing policy rules in the service.  The `policy.d` directory is
+compressed into a single file and used as an application resource. The override
-a place to put the YAML override files.  This charm owns the
+is then enabled via a Boolean charm option.
-`/etc/keystone/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
+Here are the essential commands (filenames are arbitrary):
-`policyd-override`.  The resource is a ZIP file.  This file, say
-`overrides.zip`, is attached to the charm by:
 
+    zip overrides.zip override-file.yaml
     juju attach-resource keystone policyd-override=overrides.zip
-
-The policy override is enabled in the charm using:
-
     juju config keystone use-policyd-override=true
 
-When `use-policyd-override` is `True` the status line of the charm will be
+See appendix [Policy Overrides][cdg-appendix-n] in the [OpenStack Charms
-prefixed with `PO:` indicating that policies have been overridden.  If the
+Deployment Guide][cdg] for a thorough treatment of this feature.
-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.
 
-Policy overrides on one service may affect the functionality of another
+## Token Support
-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.
-
-Token Support
--------------
 
 As the keystone charm supports multiple releases of the OpenStack software, it
 also supports two keystone token systems: UUID and Fernet. The capabilities are:
@@ -303,3 +281,16 @@ UUID tokens. In order to change the token system to Fernet, change the
 `token-provider` configuration item to `fernet`. This will switch the
 token system over. There may be a small outage in the _control plane_,
 but the running instances will be unaffected.
+
+# Bugs
+
+Please report bugs on [Launchpad][lp-bugs-charm-keystone].
+
+For general charm questions refer to the OpenStack [Charm Guide][cg].
+
+<!-- LINKS -->
+
+[cg]: https://docs.openstack.org/charm-guide
+[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
+[lp-bugs-charm-keystone]: https://bugs.launchpad.net/charm-keystone/+filebug