doc/cephadm: document setting custom monitoring templates

Fixes: https://tracker.ceph.com/issues/47651
Signed-off-by: Patrick Seidensal <pseidensal@suse.com>

diff --git a/doc/cephadm/monitoring.rst b/doc/cephadm/monitoring.rst
index 6d4f21da1aee747acb1c604e8111ddd70e70db39..5718ebb02e54074bbe92a1e4f987632aba614926 100644 (file)
--- a/doc/cephadm/monitoring.rst
+++ b/doc/cephadm/monitoring.rst
@@ -15,7 +15,7 @@ metrics on cluster utilization and performance.  Ceph users have three options:
    Ceph is running in Kubernetes with Rook).
 #. Skip the monitoring stack completely.  Some Ceph dashboard graphs will
    not be available.
-   
+
 The monitoring stack consists of `Prometheus <https://prometheus.io/>`_,
 Prometheus exporters (:ref:`mgr-prometheus`, `Node exporter
 <https://prometheus.io/docs/guides/node-exporter/>`_), `Prometheus Alert
@@ -125,7 +125,7 @@ For example
      you have set the custom image for automatically.  You will need to
      manually update the configuration (image name and tag) to be able to
      install updates.
-     
+
      If you choose to go with the recommendations instead, you can reset the
      custom image you have set before.  After that, the default value will be
      used again.  Use ``ceph config rm`` to reset the configuration option
@@ -140,6 +140,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
 --------------------