doc/cephadm: document setting custom monitoring templates

Fixes: https://tracker.ceph.com/issues/47651
Signed-off-by: Patrick Seidensal <pseidensal@suse.com>
(cherry picked from commit 7f5b1d8bfed931bd035ebf40218aa1ba249089e9)

diff --git a/doc/cephadm/monitoring.rst b/doc/cephadm/monitoring.rst
index 6a4a06d1cd2542a1f18878e46b6a6ea89db9ec8f..19e603c28ad5a32bff8e9a96d55fdc1ac77b98e0 100644 (file)
--- a/doc/cephadm/monitoring.rst
+++ b/doc/cephadm/monitoring.rst
@@ -166,6 +166,86 @@ For example
 
           ceph config rm mgr mgr/cephadm/container_image_prometheus
 
+Using custom configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By overriding cephadm templates, it is possible to completely customize the
+configuration files for monitoring services.
+
+Internally, cephadm already uses `Jinja2
+<https://jinja.palletsprojects.com/en/2.11.x/>`_ templates to generate the
+configuration files for all monitoring components. To be able to customize the
+configuration of Prometheus, Grafana or the Alertmanager it is possible to store
+a Jinja2 template for each service that will be used for configuration
+generation instead. This template will be evaluated every time a service of that
+kind is deployed or reconfigured. That way, the custom configuration is
+preserved and automatically applied on future deployments of these services.
+
+.. note::
+
+  The configuration of the custom template is also preserved when the default
+  configuration of cephadm changes. If the updated configuration is to be used,
+  the custom template needs to be migrated *manually*.
+
+Option names
+""""""""""""
+
+The following templates for files that will be generated by cephadm can be
+overridden. These are the names to be used when storing with ``ceph config-key
+set``:
+
+- ``alertmanager_alertmanager.yml``
+- ``grafana_ceph-dashboard.yml``
+- ``grafana_grafana.ini``
+- ``prometheus_prometheus.yml``
+
+You can look up the file templates that are currently used by cephadm in
+``src/pybind/mgr/cephadm/templates``:
+
+- ``services/alertmanager/alertmanager.yml.j2``
+- ``services/grafana/ceph-dashboard.yml.j2``
+- ``services/grafana/grafana.ini.j2``
+- ``services/prometheus/prometheus.yml.j2``
+
+Usage
+"""""
+
+The following command applies a single line value:
+
+.. code-block:: bash
+
+  ceph config-key set mgr/cephadm/<option_name> <value>
+
+To set contents of files as template use the ``-i`` argument:
+
+.. code-block:: bash
+
+  ceph config-key set mgr/cephadm/<option_name> -i $PWD/<filename>
+
+.. note::
+
+  When using files as input to ``config-key`` an absolute path to the file must
+  be used.
+
+It is required to restart the cephadm mgr module after a configuration option
+has been set. Then the configuration file for the service needs to be recreated.
+This is done using `redeploy`. For more details see the following example.
+
+Example
+"""""""
+
+.. code-block:: bash
+
+  # set the contents of ./prometheus.yml.j2 as template
+  ceph config-key set mgr/cephadm/services_prometheus_prometheus.yml \
+    -i $PWD/prometheus.yml.j2
+
+  # restart cephadm mgr module
+  ceph orch restart mgr
+
+  # redeploy the prometheus service
+  ceph orch redeploy prometheus
+
 Disabling monitoring
 --------------------