openstack/charm-designate
Code Issues Proposed changes

Streamline README for policy overrides

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

Change-Id: I0754ff1cd24fc48689bbf811f671194c93115e4c
This commit is contained in:
Peter Matulis 2020-01-09 11:57:12 -05:00
parent a971729627
commit 487c9ab7cc
1 changed files with 21 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
src/README.md
View File

@ -2,7 +2,6 @@
This charm provides Designate (DNSaaS) for an OpenStack Cloud.
# Usage
Designate relies on services from the mysql, rabbitmq-server and keystone
@ -34,51 +33,38 @@ For Queens and later, the nameservers config value must be set:
juju config designate nameservers="ns1.example.com. ns2.example.com."
# 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.
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 designate policyd-override=overrides.zip
The policy override is enabled in the charm using:
juju config designate 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.
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.
See appendix [Policy Overrides][cdg-appendix-n] in the [OpenStack Charms
Deployment Guide][cdg] for a thorough treatment of this feature.
# Bugs
Please report bugs on [Launchpad](https://bugs.launchpad.net/charm-designate/+filebug).
Please report bugs on [Launchpad][lp-bugs-charm-designate].
For general questions please refer to the OpenStack [Charm Guide](http://docs.openstack.org/developer/charm-guide/).
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-designate]: https://bugs.launchpad.net/charm-designate/+filebug