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
This commit is contained in:
Peter Matulis 2020-01-09 12:56:27 -05:00
parent ea8e38d09f
commit d573a56297

View File

@ -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
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/keystone/policy.d` directory, and as such, any manual changes to it will
be overwritten on charm upgrades.
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.
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:
Here are the essential commands (filenames are arbitrary):
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
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.
Token Support
-------------
## 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