From 7f5b1d8bfed931bd035ebf40218aa1ba249089e9 Mon Sep 17 00:00:00 2001 From: Patrick Seidensal Date: Fri, 25 Sep 2020 15:39:32 +0200 Subject: [PATCH] doc/cephadm: document setting custom monitoring templates Fixes: https://tracker.ceph.com/issues/47651 Signed-off-by: Patrick Seidensal --- doc/cephadm/monitoring.rst | 84 +++++++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 2 deletions(-) diff --git a/doc/cephadm/monitoring.rst b/doc/cephadm/monitoring.rst index 6d4f21da1ae..5718ebb02e5 100644 --- 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 `_, Prometheus exporters (:ref:`mgr-prometheus`, `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 +`_ 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/ + +To set contents of files as template use the ``-i`` argument: + +.. code-block:: bash + + ceph config-key set mgr/cephadm/ -i $PWD/ + +.. 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 -------------------- -- 2.39.5