diff --git a/docs/tutorial/assets/dashboard.jpeg b/docs/tutorial/assets/dashboard.jpeg new file mode 100644 index 00000000..860b0830 Binary files /dev/null and b/docs/tutorial/assets/dashboard.jpeg differ diff --git a/docs/tutorial/assets/dashboard_monitoring.jpeg b/docs/tutorial/assets/dashboard_monitoring.jpeg new file mode 100644 index 00000000..62b7d731 Binary files /dev/null and b/docs/tutorial/assets/dashboard_monitoring.jpeg differ diff --git a/docs/tutorial/enable_dashboard.rst b/docs/tutorial/enable_dashboard.rst new file mode 100644 index 00000000..0e8fbbb8 --- /dev/null +++ b/docs/tutorial/enable_dashboard.rst @@ -0,0 +1,91 @@ +Enable Ceph-Dashboard +===================== + +Introduction +------------ + +Ceph-Dashboard is a built-in web based application for monitoring and management of your Ceph cluster. This makes it easy to administer Ceph clusters for users who prefer WebUI over CLI. It is implemented as a ceph-mgr module and thus is served by the active ceph-mgr daemon. + +Enabling Ceph-Dashboard +----------------------- + +Ceph-Dashboard can be enabled like any other ceph-mgr module using the ceph cli as: + +.. code-block:: none + + ceph mgr module enable dashboard + +It can also generate a self signed certificate to quickly configure TLS. + +.. code-block:: none + + ceph dashboard create-self-signed-cert + +For more details on SSL/TLS config visit `Ceph-Dashboard configuration `_. + +Enabled ceph-mgr services can be queried as: + +.. code-block:: none + + ceph mgr services + { + "dashboard": "https://10.5.3.199:8443/", + "prometheus": "http://10.5.3.199:9283/" + } + +Let's visit the service URL and see our dashboard. + +.. figure:: assets/dashboard.jpeg + + Ceph Dashboard WebUI + +Configure SSL Key/Certicate pair +-------------------------------- + +Users may wish to configure their own set of SSL certificates for ceph-dashboard. This can be done simply using the ceph cli command: + +.. code-block:: none + + ceph dashboard set-ssl-certificate -i server.pem + SSL certificate updated + ceph dashboard set-ssl-certificate-key -i server.key + SSL certificate key updated + ceph mgr services + { + "dashboard": "https://10.5.1.107:8443/" + "prometheus": "http://10.5.1.107:9283/" + } + +**Warning:** MicroCeph snap is a confined ceph application, therefore it does not have access to files at arbitrary locations on the host machine. Therefore, it is required to have the SSL certificate/key files at $HOMEDIR, since MicroCeph can read files located at the home directory. + +Integration with Prometheus and Alertmanager +-------------------------------------------- + +Ceph-Dashboard can be configured as a receiver of the alerts coming from the Alertmanager instance. For this, we need to configure both Prometheus and Alertmanager host APIs in ceph dashboard as: + +.. code-block:: none + + ceph dashboard set-alertmanager-api-host + ceph dashboard set-prometheus-api-host + +for example: + +.. code-block:: none + + ceph dashboard set-alertmanager-api-host 'http://localhost:9093' + ceph dashboard set-prometheus-api-host 'http://localhost:9090' + +Note: +If SSL/TLS is not configured for Prometheus or Alertmanager, ssl verification can be disabled using: + +.. code-block:: none + + ceph dashboard set-prometheus-api-ssl-verify False + ceph dashboard set-alertmanager-api-ssl-verify False + +Let's check if the dashboard is receiving alerts! + +.. figure:: assets/dashboard_monitoring.jpeg + + We have an active ‘CephHealthWarning’ alert with a description which states that the cluster state has been in HEALTH_WARN for more than 15 minutes. + diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 1c65db43..932c2f6e 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -28,6 +28,7 @@ journey through the product. install initial_setup add_osds + enable_dashboard update Follow the core tutorial steps in sequence; they take you on a learning journey through the product.