docs: Improve policy documentation

Change-Id: Iede747ceaafa54a00186761943fe2f4ac13f9559

1 files changed, 21 insertions, 14 deletions

diff --git a/doc/source/admin/advanced-configuration.rst b/doc/source/admin/advanced-configuration.rst
index 62298046c..9fe2c2c9f 100644
--- a/doc/source/admin/advanced-configuration.rst
+++ b/doc/source/admin/advanced-configuration.rst
@@ -176,27 +176,34 @@ operator needs to create ``/etc/kolla/config/global.conf`` with content:
    [database]
    max_pool_size = 100
 
-In case the operators want to customize ``policy.json`` file, they should
-create a full policy file for specific project in the same directory like above
-and Kolla will overwrite default policy file with it. Be aware, with some
-projects are keeping full policy file in source code, operators just need to
-copy it but with some others are defining default rules in codebase, they have
-to generate it.
+OpenStack policy customisation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For example to overwrite ``policy.json`` file of Neutron project, the operator
-needs to grab ``policy.json`` from Neutron project source code, update rules
-and then put it to ``/etc/kolla/config/neutron/policy.json``.
+OpenStack services allow customisation of policy. Since the Queens release,
+default policy configuration is defined within the source code for each
+service, meaning that operators only need to override rules they wish to
+change. Projects typically provide documentation on their default policy
+configuration, for example, :keystone-doc:`Keystone <configuration/policy>`.
 
-.. note::
+Policy can be customised via JSON or YAML files. As of the Wallaby release, the
+JSON format is deprecated in favour of YAML. One major benefit of YAML is that
+it allows for the use of comments.
 
-   Currently kolla-ansible only support JSON and YAML format for policy file.
+For example, to customise the Neutron policy in YAML format, the operator
+should add the customised rules in ``/etc/kolla/config/neutron/policy.yaml``.
 
-The operator can make these changes after services were already deployed by
-using following command:
+The operator can make these changes after services have been deployed by using
+the following command:
 
 .. code-block:: console
 
-   kolla-ansible reconfigure
+   kolla-ansible deploy
+
+In order to present a user with the correct interface, Horizon includes policy
+for other services. Customisations made to those services may need to be
+replicated in Horizon. For example, to customise the Neutron policy in YAML
+format for Horizon, the operator should add the customised rules in
+``/etc/kolla/config/horizon/neutron_policy.yaml``.
 
 IP Address Constrained Environments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~