Skip to content

Latest commit

 

History

History
151 lines (103 loc) · 5.12 KB

README.rst

File metadata and controls

151 lines (103 loc) · 5.12 KB
Raw

Dashboard and Administration Module for Ceph Manager (aka "Dashboard v2")

Overview

The original Ceph Manager Dashboard started out as a simple read-only view into various run-time information and performance data of a Ceph cluster.

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.

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.

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

Enabling and Starting the Dashboard

The Python backend code of this module requires a number of Python modules to be installed. They are listed in file requirements.txt. Using pip you may install all required dependencies by issuing pip -r requirements.txt.

If you're using the ceph-dev-docker development environment, simply run ./install_deps.sh from the current directory to install them.

Start the Dashboard module by running:

$ ceph mgr module enable dashboard_v2

You can see currently enabled 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 <username> <password>

The password will be stored as a hash using bcrypt.

The WebUI should then be reachable on TCP port 8080.

Unit Testing and Linting

We included a tox configuration file that will run the unit tests under Python 2 and 3, as well as linting tools to guarantee the uniformity of code.

You need to install tox before running it. To install tox in your system, either install it via your operating system's package management tools, e.g. by running dnf install python3-tox on Fedora Linux.

Alternatively, you can use Python's native package installation method:

$ pip install tox

To run tox, run the following command in the root directory (where tox.ini is located):

$ tox

If you just want to run a single tox environment, for instance only run the linting tools:

$ tox -e lint

Developer Notes

How to add a new controller?

If you want to add a new endpoint to the backend, you just need to add a class decorated with ApiController in a python file located under the controllers directory. The dashboard plugin will automatically load your new controller upon start.

For example create a file ping2.py under controllers directory with the following code:

import cherrypy
from ..tools import ApiController

@ApiController('ping2')
class Ping2(object):
  @cherrypy.expose
  def default(self, *args):
    return "Hello"

Reload the dashboard plugin, and then you can access the above controller from the web browser using the URL http://mgr_hostname:8080/api/ping2

We also provide a simple mechanism to create REST based controllers using the RESTController class.

For example, we can adapt the above controller to return JSON when accessing the endpoint with a GET request:

import cherrypy
from ..tools import ApiController, RESTController

@ApiController('ping2')
class Ping2(RESTController):
  def list(self):
    return {"msg": "Hello"}

How to restrict access to a controller?

If you require that only authenticated users can access you controller, just add the AuthRequired decorator to your controller class.

Example:

import cherrypy
from ..tools import ApiController, AuthRequired, RESTController

@ApiController('ping2')
@AuthRequired
class Ping2(RESTController):
  def list(self):
    return {"msg": "Hello"}

Now only authenticated users will be able to "ping" your controller.