From 48282cb9f9ff34274d588b95481d4f5d6e359791 Mon Sep 17 00:00:00 2001 From: Lenz Grimmer Date: Thu, 28 Feb 2019 15:10:42 +0100 Subject: [PATCH] doc: Updated Ceph Dashboard documentation Renamed "Ceph Manager Dashboard" to "Ceph Dashboard" in various locations, replaced "plugin" with "module". Overhauled the feature list, added more references to configuration instructions and related components. Fixed capitalization of subchapters. Added note about mixed content blocking to the Grafana section. Removed duplicate content from the dashboard's `README.rst`, moved some parts (supported browser list) into the documentation instead. Signed-off-by: Lenz Grimmer --- doc/glossary.rst | 7 +- doc/mgr/dashboard.rst | 122 +++++++++++++----- .../dashboard_plugins/feature_toggles.inc.rst | 2 +- doc/mgr/index.rst | 2 +- doc/mgr/prometheus.rst | 2 + src/pybind/mgr/dashboard/HACKING.rst | 16 +-- src/pybind/mgr/dashboard/README.rst | 56 +------- 7 files changed, 117 insertions(+), 90 deletions(-) diff --git a/doc/glossary.rst b/doc/glossary.rst index ce86daf1cba..3fc44744f3c 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -126,10 +126,13 @@ reflect either technical terms or legacy ways of referring to Ceph systems. Ceph Manager Dashboard Ceph Dashboard + Dashboard Module Dashboard Plugin Dashboard - A built-in web based monitoring and administration application to - Ceph Manager. Refer :ref:`mgr-dashboard` for more details. + A built-in web-based Ceph management and monitoring application to + administer various aspects and objects of the cluster. The dashboard is + implemented as a Ceph Manager module. See :ref:`mgr-dashboard` for more + details. Ceph Metadata Server MDS diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst index 2b504e1d97c..607c1ca875c 100644 --- a/doc/mgr/dashboard.rst +++ b/doc/mgr/dashboard.rst @@ -1,37 +1,43 @@ .. _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 `_. The development is actively driven by the team behind openATTIC at `SUSE `_, with a lot of support from -the Ceph community and other companies like Red Hat. +companies like `Red Hat `_ 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 @@ -48,8 +54,17 @@ various aspects of your Ceph cluster: 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 `_ 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 @@ -68,6 +83,9 @@ various aspects of your Ceph cluster: 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 @@ -80,13 +98,43 @@ various aspects of your Ceph cluster: * **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 `_ | 68+ | ++----------------------------------------------+----------+ +| `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 @@ -155,7 +203,7 @@ wanted or required. $ 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. @@ -188,7 +236,7 @@ app. 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 @@ -201,8 +249,9 @@ commands:: $ ceph dashboard ac-user-create 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 @@ -259,10 +308,12 @@ into timeouts, then you can set the timeout value to your needs:: 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 `_ project. Please make sure that it's installed and enabled on the iSCSI gateways. @@ -272,6 +323,8 @@ The available iSCSI gateways must be defined using the following commands:: $ ceph dashboard iscsi-gateway-add ://:@[:port] $ ceph dashboard iscsi-gateway-rm +.. _dashboard-grafana: + Enabling the Embedding of Grafana Dashboards ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -333,13 +386,23 @@ mgr/prometheus/>`_ of the prometheus module. 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 # default: '' The format of url is : `::` + +.. 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: @@ -347,7 +410,7 @@ You can directly access Grafana Instance as well to monitor your cluster. 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 `_ 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 @@ -393,7 +456,7 @@ To enable SSO:: $ ceph dashboard sso enable saml2 -Enabling Prometheus alerting +Enabling Prometheus Alerting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using Prometheus for monitoring, you have to define `alerting rules @@ -629,7 +692,7 @@ To associate roles to users, the following CLI commands are available: $ ceph dashboard ac-user-del-roles [...] -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 @@ -651,7 +714,7 @@ view and create Ceph pools, and have read-only access to any other scopes. $ 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, @@ -667,8 +730,8 @@ so you can access the dashboard at ``http://$IP:$PORT/$PREFIX/``. .. _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 @@ -692,6 +755,7 @@ A log entry may look like this:: 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 ---------------------- @@ -722,7 +786,7 @@ Both the ``conf-`` and ``export-`` objects must be stored in the 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 @@ -739,7 +803,7 @@ After running the above command, Ceph Dashboard is able to find the NFS-Ganesha 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 diff --git a/doc/mgr/dashboard_plugins/feature_toggles.inc.rst b/doc/mgr/dashboard_plugins/feature_toggles.inc.rst index bb12aaad09f..b02448664a9 100644 --- a/doc/mgr/dashboard_plugins/feature_toggles.inc.rst +++ b/doc/mgr/dashboard_plugins/feature_toggles.inc.rst @@ -3,7 +3,7 @@ Feature Toggles ^^^^^^^^^^^^^^^ -This plug-in allows to enable or disable some features from the Ceph-Dashboard +This plug-in allows to enable or disable some features from the Ceph Dashboard on-demand. When a feature becomes disabled: - Its front-end elements (web pages, menu entries, charts, etc.) will become hidden. diff --git a/doc/mgr/index.rst b/doc/mgr/index.rst index ff2d5b9c971..78fefc11f05 100644 --- a/doc/mgr/index.rst +++ b/doc/mgr/index.rst @@ -1,4 +1,4 @@ - +.. _ceph-manager-daemon: =================== Ceph Manager Daemon diff --git a/doc/mgr/prometheus.rst b/doc/mgr/prometheus.rst index 54b1f53f344..e01196bb0ce 100644 --- a/doc/mgr/prometheus.rst +++ b/doc/mgr/prometheus.rst @@ -1,3 +1,5 @@ +.. _mgr-prometheus: + ================= Prometheus Module ================= diff --git a/src/pybind/mgr/dashboard/HACKING.rst b/src/pybind/mgr/dashboard/HACKING.rst index bd8b9b9e57f..8c834784096 100644 --- a/src/pybind/mgr/dashboard/HACKING.rst +++ b/src/pybind/mgr/dashboard/HACKING.rst @@ -1,5 +1,5 @@ -Dashboard Developer Documentation -==================================== +Ceph Dashboard Developer Documentation +====================================== .. contents:: Table of Contents @@ -1030,7 +1030,7 @@ The value of the class attribute is a pair composed by the default value for tha 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 @@ -1585,12 +1585,12 @@ Plug-ins 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 `_ to provide +Ceph Dashboard relies on `Pluggy `_ 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). @@ -1601,13 +1601,13 @@ In order to create a new plugin, the following steps are required: #. 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. diff --git a/src/pybind/mgr/dashboard/README.rst b/src/pybind/mgr/dashboard/README.rst index e26c39057d2..0756845ecb1 100644 --- a/src/pybind/mgr/dashboard/README.rst +++ b/src/pybind/mgr/dashboard/README.rst @@ -1,42 +1,16 @@ -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 -`_. 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 `_ for details on how to @@ -50,30 +24,14 @@ If you use the ``vstart.sh`` script to start up your development cluster, it 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 `_ 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 `_ | 68+ | -+----------------------------------------------+----------+ -| `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.