horizon: allow to configure by custom_local_settings.j2

kolla-ansible should provide a mechanism to allow operators to overwrite
the default (or not exposed through configuration) options for the
local_settings.

local_settings.j2 may be good place to configure horizon but requires
operator to sync it every release.

custom_local_settings.j2 can be used to overwrite things from
local_settings.j2 without a need of syncing it first.

This patch also adds a release note and a documentation section
under the advanced configuration page.

Partial-Bug: #1769970
Depends-On: https://review.openstack.org/#/c/567006/
Change-Id: I84b54ba737276114e512d4577ac4b9010682bb98

ansible/roles/horizon/handlers/main.yml

@@ -17,5 +17,6 @@
     - horizon_config_json | changed
       or horizon_conf | changed
       or horizon_local_settings | changed
+      or horizon_custom_local_settings | changed
       or policy_jsons | changed
       or check_horizon_container | changed

ansible/roles/horizon/tasks/config.yml

@@ -98,6 +98,25 @@
   notify:
     - Restart horizon container
 
+- name: Copying over custom_local_settings
+  become: true
+  vars:
+    horizon: "{{ horizon_services['horizon'] }}"
+  template:
+    src: "{{ item }}"
+    dest: "{{ node_config_directory }}/horizon/custom_local_settings"
+    mode: "0660"
+  with_first_found:
+    - "{{ node_custom_config }}/horizon/{{ inventory_hostname }}/custom_local_settings"
+    - "{{ node_custom_config }}/horizon/custom_local_settings"
+    - "custom_local_settings.j2"
+  register: horizon_custom_local_settings
+  when:
+    - horizon.enabled | bool
+    - inventory_hostname in groups[horizon.group]
+  notify:
+    - Restart horizon container
+
 - name: Copying over existing policy file
   become: true
   vars:

ansible/roles/horizon/templates/horizon.json.j2

@@ -49,6 +49,12 @@
             "dest": "/etc/openstack-dashboard/local_settings",
             "owner": "horizon",
             "perm": "0600"
+        },
+        {
+            "source": "{{ container_config_directory }}/custom_local_settings",
+            "dest": "/etc/openstack-dashboard/custom_local_settings",
+            "owner": "horizon",
+            "perm": "0600"
         }
     ]
 }

ansible/roles/horizon/templates/local_settings.j2

@@ -841,3 +841,6 @@ KEY_MANAGER = {
         'project_domain_name': '{{ default_project_domain_name }}'
 }
 {% endif %}
+
+# Allow operators to overwrite variables (LP: #1769970).
+from custom_local_settings import *

doc/source/reference/horizon-guide.rst

+.. _horizon-guide:
+
+================
+Horizon in Kolla
+================
+
+Overview
+~~~~~~~~
+
+Kolla can deploy a full working Horizon dashboard setup in either
+a **all-in-one** or **multinode** setup.
+
+Extending the default local_settings options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to extend the default configuration options for
+Horizon by using a custom python settings file that will override
+the default options set on the local_settings file.
+
+As an example, for setting a different (material) theme as the default one,
+a file named custom_local_settings should be created under the directory
+``{{ node_custom_config }}/horizon/`` with the following contents:
+
+.. code-block:: python
+
+   AVAILABLE_THEMES = [
+                ('material', 'Material', 'themes/material'),
+   ]
+
+.. end

doc/source/reference/index.rst

@@ -26,3 +26,4 @@ Projects Deployment References
    vmware-guide
    tacker-guide
    xenserver-guide
+   horizon-guide

releasenotes/notes/add-horizon-custom-settings-file-d5dfab8a1a3b4ee7.yaml

+---
+features:
+  - |
+    The settings file ``{{ node_custom_config}}/horizon/custom_local_settings`` can be
+    used in Horizon to overwrite the default local_settings without a need to sync it at image build time.