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``
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
~~~~~~~~~~~~~~~~~~~
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
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
--------------------