From: Lenz Grimmer Date: Mon, 16 Apr 2018 11:21:30 +0000 (+0200) Subject: doc: Improved dashboard documentation X-Git-Tag: v13.1.0~212^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=e9706e60def721d1c7dcc78570e00bb1ea75149a;p=ceph.git doc: Improved dashboard documentation Moved content (RGW access configuration) from the dashboard `README.rst` into the reference manual. Made various textual improvements to both the README and the documentation. Signed-off-by: Lenz Grimmer --- diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst index a4d7ba7cdab6a..af1131f18498f 100644 --- a/doc/mgr/dashboard.rst +++ b/doc/mgr/dashboard.rst @@ -1,8 +1,39 @@ -dashboard plugin +Dashboard Plugin ================ -The dashboard plugin is a web application that visualizes information and -statistics about the Ceph cluster using a web server hosted by ``ceph-mgr``. +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 dashboard plugin 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 insight into the following aspects of your cluster: @@ -36,9 +67,10 @@ Enabling The *dashboard* module is enabled with:: - ceph mgr module enable dashboard + $ ceph mgr module enable dashboard -This can be automated (e.g. during deployment) by adding the following to ceph.conf:: +This can be automated (e.g. during deployment) by adding the following to +``ceph.conf``:: [mon] mgr initial modules = dashboard @@ -64,8 +96,8 @@ Since each ``ceph-mgr`` hosts its own instance of dashboard, it may also be necessary to configure them separately. The hostname and port can be changed via the configuration key facility:: - ceph config-key set mgr/dashboard/$name/server_addr $IP - ceph config-key set mgr/dashboard/$name/server_port $PORT + $ ceph config-key set mgr/dashboard/$name/server_addr $IP + $ ceph config-key set mgr/dashboard/$name/server_port $PORT where ``$name`` is the ID of the ceph-mgr who is hosting this dashboard web app. @@ -73,8 +105,8 @@ dashboard web app. These settings can also be configured cluster-wide and not manager specific. For example,:: - ceph config-key set mgr/dashboard/server_addr $IP - ceph config-key set mgr/dashboard/server_port $PORT + $ ceph config-key set mgr/dashboard/server_addr $IP + $ ceph config-key set mgr/dashboard/server_port $PORT If the port is not configured, the web app will bind to port ``7000``. If the address it not configured, the web app will bind to ``::``, @@ -90,11 +122,54 @@ Username and password In order to be able to log in, you need to define a username and password, which will be stored in the MON's configuration database:: - ceph dashboard set-login-credentials + $ ceph dashboard set-login-credentials The password will be stored in the configuration database in encrypted form using ``bcrypt``. This is a global setting that applies to all dashboard instances. +Enabling the Object Gateway management frontend +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To use the Object Gateway management functionality of the dashboard, you will +need to provide the login credentials of a user with the ``system`` flag +enabled. + +If you do not have a user which shall be used for providing those credentials, +you will also need to create one:: + + $ radosgw-admin user create --uid= --display-name= \ + --system + +Take note of the keys ``access_key`` and ``secret_key`` in the output of this +command. + +The credentials of an existing user can also be obtained by using +`radosgw-admin`:: + + $ radosgw-admin user info --uid= + +Finally, provide the credentials to the dashboard module:: + + $ ceph dashboard set-rgw-api-access-key + $ ceph dashboard set-rgw-api-secret-key + +This is all you have to do to get the Object Gateway management functionality +working. The host and port of the Object Gateway are determined automatically. + +If multiple zones are used, it will automatically determine the host within the +master zone group and master zone. This should be sufficient for most setups, +but in some circumstances you might want to set the host and port manually:: + + $ ceph dashboard set-rgw-api-host + $ ceph dashboard set-rgw-api-port + +In addition to the settings mentioned so far, the following settings do also +exist and you may find yourself in the situation that you have to use them:: + + $ ceph dashboard set-rgw-api-scheme # http or https + $ ceph dashboard set-rgw-api-admin-resource + $ ceph dashboard set-rgw-api-user-id + Accessing the dashboard ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/src/pybind/mgr/dashboard/README.rst b/src/pybind/mgr/dashboard/README.rst index 27c586005f007..30cbe2fc5bbd1 100644 --- a/src/pybind/mgr/dashboard/README.rst +++ b/src/pybind/mgr/dashboard/README.rst @@ -1,40 +1,35 @@ Dashboard and Administration Module for Ceph Manager -========================================================================= +==================================================== Overview -------- -The original Ceph Manager Dashboard that was shipped with Ceph "Luminous" +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. +performance data of a Ceph cluster. It used a very simple architecture to +achieve the original goal. -However, there is a `growing demand `_ -for adding more web-based management capabilities, to make it easier for -administrators that prefer a WebUI over the command line. +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 module is an ongoing project to add a native web based monitoring and -administration application to Ceph Manager. It aims at becoming a successor of -the existing dashboard, which provides read-only functionality and uses a -simpler architecture to achieve the original goal. +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 code and architecture of this module is derived from and inspired by the -`openATTIC Ceph management and monitoring tool `_ (both -the backend and WebUI). The development is actively driven by the team behind -openATTIC. +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 code as possible, -while adapting it to the different environment. The current openATTIC backend -implementation is based on Django and the Django REST framework, the Manager -module's backend code will use the CherryPy framework and a custom REST API -implementation instead. +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 will be developed using Angular/TypeScript, merging -both functionality from the existing dashboard as well as adding new -functionality originally developed for the standalone version of openATTIC. - -The porting and migration of the existing openATTIC and dashboard functionality -will be done in stages. The tasks are currently tracked in the `openATTIC team's -JIRA instance `_. +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. Enabling and Starting the Dashboard ----------------------------------- @@ -51,59 +46,14 @@ Finally, you need to build the dashboard frontend code. See the file ``HACKING.rst`` in this directory for instructions on setting up the necessary development environment. -From within a running Ceph cluster, you can start the Dashboard module by -running the following command:: - - $ ceph mgr module enable dashboard - -You can see currently enabled Manager modules with:: - - $ ceph mgr module ls - -In order to be able to log in, you need to define a username and password, which -will be stored in the MON's configuration database:: - - $ ceph dashboard set-login-credentials - -The password will be stored as a hash using ``bcrypt``. - -The Dashboard's WebUI should then be reachable on TCP port 8080. - -Enabling the Object Gateway management frontend ------------------------------------------------ - -If you want to use the Object Gateway management functionality of the -dashboard, you will need to provide credentials. If you do not have a user -which shall be used for providing those credentials, you will also need to -create one:: - - $ radosgw-admin user create --uuid= --display-name= \ - --system - -The credentials of a user can also be obtained by using `radosgw-admin`:: - - $ radosgw-admin user info --uid= - -Finally, set the credentials to the dashboard module:: - - $ ceph dashboard set-rgw-api-secret-key - $ ceph dashboard set-rgw-api-access-key - -This is all you have to do to get the Object Gateway management functionality -working. The host and port of the Object Gateway are determined automatically. -If multiple zones are used, it will automatically determine the host within the -master zone group and master zone. This should be sufficient for most setups, -but in some circumstances you might want to set the host and port manually:: - - $ ceph dashboard set-rgw-api-host - $ ceph dashboard set-rgw-api-port - -In addition to the settings mentioned so far, the following settings do also -exist and you may find yourself in the situation that you have to use them:: +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. - $ ceph dashboard set-rgw-api-scheme # http or https - $ ceph dashboard set-rgw-api-admin-resource - $ ceph dashboard set-rgw-api-user-id +See the `Ceph Dashboard plugin 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. Working on the Dashboard Code -----------------------------