import 15.2.9

[ceph.git] / ceph / doc / cephadm / monitoring.rst

diff --git a/ceph/doc/cephadm/monitoring.rst b/ceph/doc/cephadm/monitoring.rst
index b1a4157730cbfc28848eb504678cdf0bc9b9d693..a694efaed69eb837764fdb48a14429afbcde8a2f 100644 (file)
--- a/ceph/doc/cephadm/monitoring.rst
+++ b/ceph/doc/cephadm/monitoring.rst
@@ -72,8 +72,20 @@ monitoring by following the steps below.
 
      ceph orch apply grafana 1
 
 
      ceph orch apply grafana 1
 

-Cephadm handles the prometheus, grafana, and alertmanager
-configurations automatically.
+Cephadm takes care of the configuration of Prometheus, Grafana, and Alertmanager
+automatically.
+
+However, there is one exception to this rule. In a some setups, the Dashboard
+user's browser might not be able to access the Grafana URL configured in Ceph
+Dashboard. One such scenario is when the cluster and the accessing user are each
+in a different DNS zone.
+
+For this case, there is an extra configuration option for Ceph Dashboard, which
+can be used to configure the URL for accessing Grafana by the user's browser.
+This value will never be altered by cephadm. To set this configuration option,
+issue the following command::
+
+  $ ceph dashboard set-grafana-frontend-api-url <grafana-server-api>

 
 It may take a minute or two for services to be deployed.  Once
 completed, you should see something like this from ``ceph orch ls``
 
 It may take a minute or two for services to be deployed.  Once
 completed, you should see something like this from ``ceph orch ls``


@@ -88,6 +100,37 @@ completed, you should see something like this from ``ceph orch ls``
   node-exporter      2/2  6s ago     docker.io/prom/node-exporter:latest             e5a616e4b9cf  present
   prometheus         1/1  6s ago     docker.io/prom/prometheus:latest                e935122ab143  present
 
   node-exporter      2/2  6s ago     docker.io/prom/node-exporter:latest             e5a616e4b9cf  present
   prometheus         1/1  6s ago     docker.io/prom/prometheus:latest                e935122ab143  present
 

+Configuring SSL/TLS for Grafana
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``cephadm`` will deploy Grafana using the certificate defined in the ceph
+key/value store. If a certificate is not specified, ``cephadm`` will generate a
+self-signed certificate during deployment of the Grafana service.
+
+A custom certificate can be configured using the following commands.
+
+.. code-block:: bash
+
+  ceph config-key set mgr/cephadm/grafana_key -i $PWD/key.pem
+  ceph config-key set mgr/cephadm/grafana_crt -i $PWD/certificate.pem
+
+The ``cephadm`` manager module needs to be restarted to be able to read updates
+to these keys.
+
+.. code-block:: bash
+
+  ceph orch restart mgr
+
+If you already deployed Grafana, you need to redeploy the service for the
+configuration to be updated.
+
+.. code-block:: bash
+
+  ceph orch redeploy grafana
+
+The ``redeploy`` command also takes care of setting the right URL for Ceph
+Dashboard.
+

 Using custom images
 ~~~~~~~~~~~~~~~~~~~
 
 Using custom images
 ~~~~~~~~~~~~~~~~~~~
 


@@ -120,7 +163,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.
      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
      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


@@ -135,6 +178,86 @@ For example
 
           ceph config rm mgr mgr/cephadm/container_image_prometheus
 
 
           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
 --------------------
 
 Disabling monitoring
 --------------------