RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2025-01-11 13:41:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: Updated Ceph Dashboard documentation

Browse Source 
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 <lgrimmer@suse.com>
This commit is contained in:
Lenz Grimmer 2019-02-28 15:10:42 +01:00
parent 6d02236ffa
commit 48282cb9f9
7 changed files with 117 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/glossary.rst
View File

@ -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

122
doc/mgr/dashboard.rst
View File

@ -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
<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
@ -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 <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
@ -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 <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
@ -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 <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
@ -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 <https://github.com/ceph/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 <gateway_name> <scheme>://<username>:<password>@<host>[:port]
$ ceph dashboard iscsi-gateway-rm <gateway_name>
.. _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 <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:
@ -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 <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
@ -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 <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
@ -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-<daemon_id>`` and ``export-<id>`` 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

2
doc/mgr/dashboard_plugins/feature_toggles.inc.rst
View File

@ -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.

2
doc/mgr/index.rst
View File

@ -1,4 +1,4 @@
.. _ceph-manager-daemon:
===================
Ceph Manager Daemon

2
doc/mgr/prometheus.rst
View File

@ -1,3 +1,5 @@
.. _mgr-prometheus:
=================
Prometheus Module
=================

16
src/pybind/mgr/dashboard/HACKING.rst
View File

@ -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 <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).
@ -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.

56
src/pybind/mgr/dashboard/README.rst
View File

@ -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
<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
@ -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
<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.