.. _mgr-dashboard:
-Ceph Manager Dashboard
-======================
+Ceph Dashboard
+==============
Overview
--------
-The original Ceph Manager Dashboard that was shipped with Ceph Luminous started
+The Ceph Dashboard is a built-in web-based Ceph management and monitoring
+application to administer various aspects and objects of the cluster. It is
+implemented as a :ref:`ceph-manager-daemon` module.
+
+The original Ceph Dashboard that was shipped with Ceph Luminous started
out as a simple read-only view into various run-time information and performance
data of a Ceph cluster. It used a very simple architecture to achieve the
original goal. However, there was a growing demand for adding more web-based
management capabilities, to make it easier to administer Ceph for users that
prefer a WebUI over using the command line.
-The new :term:`Ceph Manager Dashboard` plugin is a replacement of the previous
-one and adds a built-in web based monitoring and administration application to
-the Ceph Manager. The architecture and functionality of this new plugin is
-derived from and inspired by the `openATTIC Ceph management and monitoring tool
+The new :term:`Ceph Dashboard` module is a replacement of the previous one and
+adds a built-in web based monitoring and administration application to the Ceph
+Manager. The architecture and functionality of this new plugin is derived from
+and inspired by the `openATTIC Ceph management and monitoring tool
<https://openattic.org/>`_. The development is actively driven by the team
behind openATTIC at `SUSE <https://www.suse.com/>`_, with a lot of support from
-the Ceph community and other companies like Red Hat.
-
+companies like `Red Hat <https://redhat.com/>`_ and other members of the Ceph
+community.
-The dashboard plugin's backend code uses the CherryPy framework and a custom
+The dashboard module's backend code uses the CherryPy framework and a custom
REST API implementation. The WebUI implementation is based on
Angular/TypeScript, merging both functionality from the original dashboard as
well as adding new functionality originally developed for the standalone version
-of openATTIC. The Ceph Manager Dashboard plugin is implemented as a web
+of openATTIC. The Ceph Dashboard module is implemented as a web
application that visualizes information and statistics about the Ceph cluster
using a web server hosted by ``ceph-mgr``.
-The dashboard currently provides the following features to monitor and manage
-various aspects of your Ceph cluster:
+Feature Overview
+^^^^^^^^^^^^^^^^
+
+The dashboard provides the following features:
* **Multi-User and Role Management**: The dashboard supports multiple user
accounts with different permissions (roles). The user accounts and roles
and DELETE API requests in the Ceph audit log. See :ref:`dashboard-auditing`
for instructions on how to enable this feature.
* **Internationalization (I18N)**: use the dashboard in different languages.
+
+Currently, Ceph Dashboard is capable of monitoring and managing the following
+aspects of your Ceph cluster:
+
* **Overall cluster health**: Displays overall cluster status, performance
and capacity metrics.
+* **Embedded Grafana Dashboards**: Ceph Dashboard is capable of embedding
+ `Grafana <https://grafana.com>`_ dashboards in many locations, to display
+ additional information and performance metrics gathered by the
+ :ref:`mgr-prometheus`. See :ref:`dashboard-grafana` for details on how to
+ configure this functionality.
* **Cluster logs**: Display the latest updates to the cluster's event and audit
log files.
* **Hosts**: Provides a list of all hosts associated to the cluster, which
the level of backfilling activity.
* **iSCSI**: Lists all hosts that run the TCMU runner service, displaying all
images and their performance characteristics (read/write ops, traffic).
+ Create, modify and delete iSCSI targets (via ``ceph-iscsi``). See
+ :ref:`dashboard-iscsi-management` for instructions on how to configure this
+ feature.
* **RBD**: Lists all RBD images and their properties (size, objects, features).
Create, copy, modify and delete RBD images. Create, delete and rollback
snapshots of selected images, protect/unprotect these snapshots against
* **Object Gateway**: Lists all active object gateways and their performance
counters. Display and manage (add/edit/delete) object gateway users and their
details (e.g. quotas) as well as the users' buckets and their details (e.g.
- owner, quotas).
-* **NFS**: Manage NFS exports of CephFS filesystems and RGW S3 buckets via NFS Ganesha.```
+ owner, quotas). See :ref:`dashboard-enabling-object-gateway` for configuration
+ instructions.
+* **NFS**: Manage NFS exports of CephFS filesystems and RGW S3 buckets via NFS
+ Ganesha. See :ref:`dashboard-nfs-ganesha-management` for details on how to
+ enable this functionality.
+* **Ceph Manager Modules**: Enable and disable all Ceph Manager modules, change
+ the module-specific configuration settings.
+
+
+Supported Browsers
+^^^^^^^^^^^^^^^^^^
+
+Ceph Dashboard is primarily tested and developed using the following web
+browsers:
+
++----------------------------------------------+----------+
+| Browser | Versions |
++==============================================+==========+
+| `Chrome <https://www.google.com/chrome/>`_ | 68+ |
++----------------------------------------------+----------+
+| `Firefox <http://www.mozilla.org/firefox/>`_ | 61+ |
++----------------------------------------------+----------+
+
+While Ceph Dashboard might work in older browsers, we cannot guarantee it and
+recommend you to update your browser to the latest version.
Enabling
--------
-Within a running Ceph cluster, the Ceph Manager Dashboard is enabled with::
+If you have installed Ceph from distribution packages, the package management
+system should have taken care of installing all the required dependencies.
+
+If you're installing Ceph from source and want to start the dashboard from your
+development environment, please see the files ``README.rst`` and ``HACKING.rst``
+in directory ``src/pybind/mgr/dashboard`` of the source code.
+
+Within a running Ceph cluster, the Ceph Dashboard is enabled with::
$ ceph mgr module enable dashboard
$ ceph mgr module disable dashboard
$ ceph mgr module enable dashboard
-Host name and port
+Host Name and Port
^^^^^^^^^^^^^^^^^^
Like most web applications, dashboard binds to a TCP/IP address and TCP port.
currently configured. Look for the ``dashboard`` key to obtain the URL for
accessing the dashboard.
-Username and password
+Username and Password
^^^^^^^^^^^^^^^^^^^^^
In order to be able to log in, you need to create a user account and associate
$ ceph dashboard ac-user-create <username> <password> administrator
+.. _dashboard-enabling-object-gateway:
-Enabling the Object Gateway management frontend
+Enabling the Object Gateway Management Frontend
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To use the Object Gateway management functionality of the dashboard, you will
The default value is 45 seconds.
+.. _dashboard-iscsi-management:
+
Enabling iSCSI Management
^^^^^^^^^^^^^^^^^^^^^^^^^
-The Ceph Manager Dashboard can manage iSCSI targets using the REST API provided
+The Ceph Dashboard can manage iSCSI targets using the REST API provided
by the `rbd-target-api` service of the `ceph-iscsi <https://github.com/ceph/ceph-iscsi>`_
project. Please make sure that it's installed and enabled on the iSCSI gateways.
$ ceph dashboard iscsi-gateway-add <gateway_name> <scheme>://<username>:<password>@<host>[:port]
$ ceph dashboard iscsi-gateway-rm <gateway_name>
+.. _dashboard-grafana:
+
Enabling the Embedding of Grafana Dashboards
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
org_role = Viewer
After you have set up Grafana and Prometheus, you will need to configure the
-connection information that the Ceph Manager Dashboard will use to access Grafana.
+connection information that the Ceph Dashboard will use to access Grafana.
You need to tell the dashboard on which url Grafana instance is running/deployed::
$ ceph dashboard set-grafana-api-url <grafana-server-url> # default: ''
The format of url is : `<protocol>:<IP-address>:<port>`
+
+.. note::
+ Ceph Dashboard embeds the Grafana dashboards via ``iframe`` HTML elements.
+ If Grafana is configured without SSL/TLS support, most browsers will block the
+ embedding of insecure content into a secured web page, if the SSL support in
+ the dashboard has been enabled (which is the default configuration). If you
+ can't see the embedded Grafana dashboards after enabling them as outlined
+ above, check your browser's documentation on how to unblock mixed content.
+ Alternatively, consider enabling SSL/TLS support in Grafana.
+
You can directly access Grafana Instance as well to monitor your cluster.
.. _dashboard-sso-support:
Enabling Single Sign-On (SSO)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Ceph Manager Dashboard supports external authentication of users via the
+The Ceph Dashboard supports external authentication of users via the
`SAML 2.0 <https://en.wikipedia.org/wiki/SAML_2.0>`_ protocol. You need to create
the user accounts and associate them with the desired roles first, as authorization
is still performed by the Dashboard. However, the authentication process can be
$ ceph dashboard sso enable saml2
-Enabling Prometheus alerting
+Enabling Prometheus Alerting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using Prometheus for monitoring, you have to define `alerting rules
$ ceph dashboard ac-user-del-roles <username> <rolename> [<rolename>...]
-Example of user and custom role creation
+Example of User and Custom Role Creation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this section we show a full example of the commands that need to be used
$ ceph dashboard ac-user-set-roles bob rbd/pool-manager read-only
-Reverse proxies
+Reverse Proxies
---------------
If you are accessing the dashboard via a reverse proxy configuration,
.. _dashboard-auditing:
-Auditing
---------
+Auditing API Requests
+---------------------
The REST API is capable of logging PUT, POST and DELETE requests to the Ceph
audit log. This feature is disabled by default, but can be enabled with the
2018-10-22 15:27:01.302514 mgr.x [INF] [DASHBOARD] from='https://[::ffff:127.0.0.1]:37022' path='/api/rgw/user/klaus' method='PUT' user='admin' params='{"max_buckets": "1000", "display_name": "Klaus Mustermann", "uid": "klaus", "suspended": "0", "email": "klaus.mustermann@ceph.com"}'
+.. _dashboard-nfs-ganesha-management:
NFS-Ganesha Management
----------------------
same RADOS pool/namespace.
-Configuring NFS-Ganesha in the dashboard
+Configuring NFS-Ganesha in the Dashboard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To enable the management of NFS-Ganesha exports in Ceph Dashboard, we only
configuration objects and we can start manage the exports through the Web UI.
-Support for multiple NFS-Ganesha clusters
+Support for Multiple NFS-Ganesha Clusters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Ceph Dashboard also supports the management of NFS-Ganesha exports belonging
-Dashboard Developer Documentation
-====================================
+Ceph Dashboard Developer Documentation
+======================================
.. contents:: Table of Contents
setting, and the python type of the value.
By declaring the ``ADMIN_EMAIL_ADDRESS`` class attribute, when you restart the
-dashboard plugin, you will automatically gain two additional CLI commands to
+dashboard module, you will automatically gain two additional CLI commands to
get and set that setting::
$ ceph dashboard get-admin-email-address
New functionality can be provided by means of a plug-in architecture. Among the
benefits this approach brings in, loosely coupled development is one of the most
-notable. As the Ceph-Dashboard grows in feature richness, its code-base becomes
+notable. As the Ceph Dashboard grows in feature richness, its code-base becomes
more and more complex. The hook-based nature of a plug-in architecture allows to
extend functionality in a controlled manner, and isolate the scope of the
changes.
-Ceph-Dashboard relies on `Pluggy <https://pluggy.readthedocs.io>`_ to provide
+Ceph Dashboard relies on `Pluggy <https://pluggy.readthedocs.io>`_ to provide
for plug-ing support. On top of pluggy, an interface-based approach has been
implemented, with some safety checks (method override and abstract method
checks).
#. Import the ``PLUGIN_MANAGER`` instance and the ``Interfaces``.
#. Create a class extending the desired interfaces. The plug-in library will check if all the methods of the interfaces have been properly overridden.
#. Register the plugin in the ``PLUGIN_MANAGER`` instance.
-#. Import the plug-in from within the Ceph-Dashboard ``module.py`` (currently no dynamic loading is implemented).
+#. Import the plug-in from within the Ceph Dashboard ``module.py`` (currently no dynamic loading is implemented).
The available interfaces are the following:
- ``CanMgr``: provides the plug-in with access to the ``mgr`` instance under ``self.mgr``.
-- ``CanLog``: provides the plug-in with access to the Ceph-Dashboard logger under ``self.log``.
-- ``Setupable``: requires overriding ``setup()`` hook. This method is run in the Ceph-Dashboard ``serve()`` method, right after CherryPy has been configured, but before it is started. It's a placeholder for the plug-in initialization logic.
+- ``CanLog``: provides the plug-in with access to the Ceph Dashboard logger under ``self.log``.
+- ``Setupable``: requires overriding ``setup()`` hook. This method is run in the Ceph Dashboard ``serve()`` method, right after CherryPy has been configured, but before it is started. It's a placeholder for the plug-in initialization logic.
- ``HasOptions``: requires overriding ``get_options()`` hook by returning a list of ``Options()``. The options returned here are added to the ``MODULE_OPTIONS``.
- ``HasCommands``: requires overriding ``register_commands()`` hook by defining the commands the plug-in can handle and decorating them with ``@CLICommand`. The commands can be optionally returned, so that they can be invoked externally (which makes unit testing easier).
- ``HasControllers``: requires overriding ``get_controllers()`` hook by defining and returning the controllers as usual.
-Dashboard and Administration Module for Ceph Manager
-====================================================
+Ceph Dashboard
+==============
Overview
--------
-The original Ceph manager dashboard that was shipped with Ceph "Luminous"
-started out as a simple read-only view into various run-time information and
-performance data of a Ceph cluster. It used a very simple architecture to
-achieve the original goal.
-
-However, there was a growing demand for adding more web-based management
-capabilities, to make it easier to administer Ceph for users that prefer a WebUI
-over using the command line.
-
-This new dashboard module is a replacement of the previous one and an
-ongoing project to add a native web based monitoring and administration
-application to Ceph Manager.
-
-The architecture and functionality of this module are derived from and inspired
-by the `openATTIC Ceph management and monitoring tool
-<https://openattic.org/>`_. The development is actively driven by the team
-behind openATTIC at SUSE.
-
-The intention is to reuse as much of the existing openATTIC functionality as
-possible, while adapting it to the different environment. The Dashboard module's
-backend code uses the CherryPy framework and a custom REST API implementation
-instead of Django and the Django REST Framework.
-
-The WebUI implementation is based on Angular/TypeScript, merging both
-functionality from the original dashboard as well as adding new functionality
-originally developed for the standalone version of openATTIC.
+The Ceph Dashboard is a built-in web-based Ceph management and monitoring
+application to administer various aspects and objects of the cluster. It is
+implemented as a Ceph Manager module.
Enabling and Starting the Dashboard
-----------------------------------
-If you have installed Ceph from distribution packages, the package management
-system should have taken care of installing all the required dependencies.
-
If you want to start the dashboard from within a development environment, you
need to have built Ceph (see the toplevel ``README.md`` file and the `developer
documentation <http://docs.ceph.com/docs/master/dev/>`_ for details on how to
will configure and enable the dashboard automatically. The URL and login
credentials are displayed when the script finishes.
-See the `Ceph Dashboard plugin documentation
+Please see the `Ceph Dashboard documentation
<http://docs.ceph.com/docs/master/mgr/dashboard/>`_ for details on how to enable
and configure the dashboard manually and how to configure other settings, e.g.
access to the Ceph object gateway.
-Supported browsers
-------------------
-
-The Ceph Manager Dashboard is tested and developed on the following browsers:
-
-+----------------------------------------------+----------+
-| Browser | Versions |
-+==============================================+==========+
-| `Chrome <https://www.google.com/chrome/>`_ | 68+ |
-+----------------------------------------------+----------+
-| `Firefox <http://www.mozilla.org/firefox/>`_ | 61+ |
-+----------------------------------------------+----------+
-
-While Ceph Manager Dashboard might work in older browsers, we cannot guarantee
-it and recommend you update your browser to the latest version.
-
Working on the Dashboard Code
-----------------------------
If you're interested in helping with the development of the dashboard, please
see the file ``HACKING.rst`` for details on how to set up a development
-environment and some other development-related topics.
+environment and other development-related topics.
projects / ceph.git / commitdiff