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
parent
ea8e38d09f
commit
d573a56297
85
README.md
85
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
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user