3 Ceph Dashboard Developer Documentation
4 ======================================
6 .. contents:: Table of Contents
11 To promote collaboration on new Ceph Dashboard features, the first step is
12 the definition of a design document. These documents then form the basis of
13 implementation scope and permit wider participation in the evolution of the
18 :caption: Design Documents:
20 UI Design Goals <../dashboard/ui_goals>
26 The following documentation chapters expect a running Ceph cluster and at
27 least a running ``dashboard`` manager module (with few exceptions). This
28 chapter gives an introduction on how to set up such a system for development,
29 without the need to set up a full-blown production environment. All options
30 introduced in this chapter are based on a so called ``vstart`` environment.
34 Every ``vstart`` environment needs Ceph `to be compiled`_ from its Github
35 repository, though Docker environments simplify that step by providing a
36 shell script that contains those instructions.
38 One exception to this rule are the `build-free`_ capabilities of
39 `ceph-dev`_. See below for more information.
41 .. _to be compiled: https://docs.ceph.com/docs/master/install/build-ceph/
46 "vstart" is actually a shell script in the ``src/`` directory of the Ceph
47 repository (``src/vstart.sh``). It is used to start a single node Ceph
48 cluster on the machine where it is executed. Several required and some
49 optional Ceph internal services are started automatically when it is used to
50 start a Ceph cluster. vstart is the basis for the three most commonly used
51 development environments in Ceph Dashboard.
53 You can read more about vstart in `Deploying a development cluster`_.
54 Additional information for developers can also be found in the `Developer
57 .. _Deploying a development cluster: https://docs.ceph.com/docs/master/dev/dev_cluster_deployement/
58 .. _Developer Guide: https://docs.ceph.com/docs/master/dev/quick_guide/
60 Host-based vs Docker-based Development Environments
61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63 This document introduces you to three different development environments, all
64 based on vstart. Those are:
66 - vstart running on your host system
68 - vstart running in a Docker environment
73 Besides their independent development branches and sometimes slightly
74 different approaches, they also differ with respect to their underlying
77 ========= ====================== ========
78 Release ceph-dev-docker ceph-dev
79 ========= ====================== ========
80 Mimic openSUSE Leap 15 CentOS 7
81 Nautilus openSUSE Leap 15 CentOS 7
82 Octopus openSUSE Leap 15.2 CentOS 8
83 --------- ---------------------- --------
84 Master openSUSE Tumbleweed CentOS 8
85 ========= ====================== ========
89 Independently of which of these environments you will choose, you need to
90 compile Ceph in that environment. If you compiled Ceph on your host system,
91 you would have to recompile it on Docker to be able to switch to a Docker
92 based solution. The same is true vice versa. If you previously used a
93 Docker development environment and compiled Ceph there and you now want to
94 switch to your host system, you will also need to recompile Ceph (or
95 compile Ceph using another separate repository).
97 `ceph-dev`_ is an exception to this rule as one of the options it provides
98 is `build-free`_. This is accomplished through a Ceph installation using
99 RPM system packages. You will still be able to work with a local Github
100 repository like you are used to.
103 Development environment on your host system
104 ...........................................
106 - No need to learn or have experience with Docker, jump in right away.
108 - Limited amount of scripts to support automation (like Ceph compilation).
110 - No pre-configured easy-to-start services (Prometheus, Grafana, etc).
112 - Limited amount of host operating systems supported, depending on which
113 Ceph version is supposed to be used.
115 - Dependencies need to be installed on your host.
117 - You might find yourself in the situation where you need to upgrade your
118 host operating system (for instance due to a change of the GCC version used
122 Development environments based on Docker
123 ........................................
125 - Some overhead in learning Docker if you are not used to it yet.
127 - Both Docker projects provide you with scripts that help you getting started
128 and automate recurring tasks.
130 - Both Docker environments come with partly pre-configured external services
131 which can be used to attach to or complement Ceph Dashboard features, like
139 - Works independently of the operating system you use on your host.
142 .. _build-free: https://github.com/rhcs-dashboard/ceph-dev#quick-install-rpm-based
144 vstart on your host system
145 ~~~~~~~~~~~~~~~~~~~~~~~~~~
147 The vstart script is usually called from your `build/` directory like so:
151 ../src/vstart.sh -n -d
153 In this case ``-n`` ensures that a new vstart cluster is created and that a
154 possibly previously created cluster isn't re-used. ``-d`` enables debug
155 messages in log files. There are several more options to chose from. You can
156 get a list using the ``--help`` argument.
158 At the end of the output of vstart, there should be information about the
159 dashboard and its URLs::
161 vstart cluster complete. Use stop.sh to stop. See out/* (e.g. 'tail -f out/????') for debug output.
163 dashboard urls: https://192.168.178.84:41259, https://192.168.178.84:43259, https://192.168.178.84:45259
164 w/ user/pass: admin / admin
165 restful urls: https://192.168.178.84:42259, https://192.168.178.84:44259, https://192.168.178.84:46259
166 w/ user/pass: admin / 598da51f-8cd1-4161-a970-b2944d5ad200
168 During development (especially in backend development), you also want to
169 check on occasions if the dashboard manager module is still running. To do so
170 you can call `./bin/ceph mgr services` manually. It will list all the URLs of
171 successfully enabled services. Only URLs of services which are available over
172 HTTP(S) will be listed there. Ceph Dashboard is one of these services. It
173 should look similar to the following output:
177 $ ./bin/ceph mgr services
179 "dashboard": "https://home:41931/",
180 "restful": "https://home:42931/"
183 By default, this environment uses a randomly chosen port for Ceph Dashboard
184 and you need to use this command to find out which one it has become.
189 Docker development environments usually ship with a lot of useful scripts.
190 ``ceph-dev-docker`` for instance contains a file called `start-ceph.sh`,
191 which cleans up log files, always starts a Rados Gateway service, sets some
192 Ceph Dashboard configuration options and automatically runs a frontend proxy,
193 all before or after starting up your vstart cluster.
195 Instructions on how to use those environments are contained in their
196 respective repository README files.
201 .. _ceph-dev-docker: https://github.com/ricardoasmarques/ceph-dev-docker
202 .. _ceph-dev: https://github.com/rhcs-dashboard/ceph-dev
207 Before you can start the dashboard from within a development environment, you
208 will need to generate the frontend code and either use a compiled and running
209 Ceph cluster (e.g. started by ``vstart.sh``) or the standalone development web
212 The build process is based on `Node.js <https://nodejs.org/>`_ and requires the
213 `Node Package Manager <https://www.npmjs.com/>`_ ``npm`` to be installed.
218 * Node 14.15.0 or higher
219 * NPM 6.14.9 or higher
222 During Ceph's build we create a virtualenv with ``node`` and ``npm``
223 installed, which can be used as an alternative to installing node/npm in your
226 If you want to use the node installed in the virtualenv you just need to
227 activate the virtualenv before you run any npm commands. To activate it run
228 ``. build/src/pybind/mgr/dashboard/node-env/bin/activate``.
230 Once you finish, you can simply run ``deactivate`` and exit the virtualenv.
233 If you do not have the `Angular CLI <https://github.com/angular/angular-cli>`_
234 installed globally, then you need to execute ``ng`` commands with an
235 additional ``npm run`` before it.
240 Run ``npm ci`` in directory ``src/pybind/mgr/dashboard/frontend`` to
241 install the required packages locally.
243 Adding or updating packages
244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
246 Run the following commands to add/update a package::
248 npm install <PACKAGE_NAME>
251 Setting up a Development Server
252 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
254 Create the ``proxy.conf.json`` file based on ``proxy.conf.json.sample``.
256 Run ``npm start`` for a dev server.
257 Navigate to ``http://localhost:4200/``. The app will automatically
258 reload if you change any of the source files.
263 Run ``ng generate component component-name`` to generate a new
264 component. You can also use
265 ``ng generate directive|pipe|service|class|guard|interface|enum|module``.
270 Run ``npm run build`` to build the project. The build artifacts will be
271 stored in the ``dist/`` directory. Use the ``--prod`` flag for a
272 production build (``npm run build -- --prod``). Navigate to ``https://localhost:8443``.
274 Build the Code Documentation
275 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
277 Run ``npm run doc-build`` to generate code docs in the ``documentation/``
278 directory. To make them accessible locally for a web browser, run
279 ``npm run doc-serve`` and they will become available at ``http://localhost:8444``.
280 With ``npm run compodoc -- <opts>`` you may
281 `fully configure it <https://compodoc.app/guides/usage.html>`_.
283 Code linting and formatting
284 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
286 We use the following tools to lint and format the code in all our TS, SCSS and
289 - `codelyzer <http://codelyzer.com/>`_
290 - `html-linter <https://github.com/chinchiheather/html-linter>`_
291 - `htmllint-cli <https://github.com/htmllint/htmllint-cli>`_
292 - `Prettier <https://prettier.io/>`_
293 - `ESLint <https://eslint.org/>`_
294 - `stylelint <https://stylelint.io/>`_
296 We added 2 npm scripts to help run these tools:
298 - ``npm run lint``, will check frontend files against all linters
299 - ``npm run fix``, will try to fix all the detected linting errors
301 Ceph Dashboard and Bootstrap
302 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
304 Currently we are using Bootstrap on the Ceph Dashboard as a CSS framework. This means that most of our SCSS and HTML
305 code can make use of all the utilities and other advantages Bootstrap is offering. In the past we often have used our
306 own custom styles and this lead to more and more variables with a single use and double defined variables which
307 sometimes are forgotten to be removed or it led to styling be inconsistent because people forgot to change a color or to
308 adjust a custom SCSS class.
310 To get the current version of Bootstrap used inside Ceph please refer to the ``package.json`` and search for:
312 - ``bootstrap``: For the Bootstrap version used.
313 - ``@ng-bootstrap``: For the version of the Angular bindings which we are using.
315 So for the future please do the following when visiting a component:
317 - Does this HTML/SCSS code use custom code? - If yes: Is it needed? --> Clean it up before changing the things you want
319 - If you are creating a new component: Please make use of Bootstrap as much as reasonably possible! Don't try to
321 - If possible please look up if Bootstrap has guidelines on how to extend it properly to do achieve what you want to
324 The more bootstrap alike our code is the easier it is to theme, to maintain and the less bugs we will have. Also since
325 Bootstrap is a framework which tries to have usability and user experience in mind we increase both points
326 exponentially. The biggest benefit of all is that there is less code for us to maintain which makes it easier to read
327 for beginners and even more easy for people how are already familiar with the code.
332 To write unit tests most efficient we have a small collection of tools,
333 we use within test suites.
335 Those tools can be found under
336 ``src/pybind/mgr/dashboard/frontend/src/testing/``, especially take
337 a look at ``unit-test-helper.ts``.
339 There you will be able to find:
341 ``configureTestBed`` that replaces the initial ``TestBed``
342 methods. It takes the same arguments as ``TestBed.configureTestingModule``.
343 Using it will run your tests a lot faster in development, as it doesn't
344 recreate everything from scratch on every test. To use the default behaviour
345 pass ``true`` as the second argument.
347 ``PermissionHelper`` to help determine if
348 the correct actions are shown based on the current permissions and selection
351 ``FormHelper`` which makes testing a form a lot easier
352 with a few simple methods. It allows you to set a control or multiple
353 controls, expect if a control is valid or has an error or just do both with
354 one method. Additional you can expect a template element or multiple elements
355 to be visible in the rendered template.
360 Run ``npm run test`` to execute the unit tests via `Jest
361 <https://facebook.github.io/jest/>`_.
363 If you get errors on all tests, it could be because `Jest
364 <https://facebook.github.io/jest/>`__ or something else was updated.
365 There are a few ways how you can try to resolve this:
367 - Remove all modules with ``rm -rf dist node_modules`` and run ``npm install``
368 again in order to reinstall them
369 - Clear the cache of jest by running ``npx jest --clearCache``
371 Running End-to-End (E2E) Tests
372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
374 We use `Cypress <https://www.cypress.io/>`__ to run our frontend E2E tests.
379 You need to previously build the frontend.
381 In some environments, depending on your user permissions and the CYPRESS_CACHE_FOLDER,
382 you might need to run ``npm ci`` with the ``--unsafe-perm`` flag.
384 You might need to install additional packages to be able to run Cypress.
385 Please run ``npx cypress verify`` to verify it.
387 run-frontend-e2e-tests.sh
388 .........................
390 Our ``run-frontend-e2e-tests.sh`` script is the go to solution when you wish to
391 do a full scale e2e run.
392 It will verify if everything needed is installed, start a new vstart cluster
393 and run the full test suite.
395 Start all frontend E2E tests with::
397 $ cd src/pybind/mgr/dashboard
398 $ ./run-frontend-e2e-tests.sh
401 You can follow the e2e report on the terminal and you can find the screenshots
402 of failed test cases by opening the following directory::
404 src/pybind/mgr/dashboard/frontend/cypress/screenshots/
407 You can force the script to use a specific device with the ``-d`` flag::
409 $ ./run-frontend-e2e-tests.sh -d <chrome|chromium|electron|docker>
412 By default this script will stop and start a new vstart cluster.
413 If you want to run the tests outside the ceph environment, you will need to
414 manually define the dashboard url using ``-r`` and, optionally, credentials
417 $ ./run-frontend-e2e-tests.sh -r <DASHBOARD_URL> -u <E2E_LOGIN_USER> -p <E2E_LOGIN_PWD>
420 When using docker, as your device, you might need to run the script with sudo
423 run-cephadm-e2e-tests.sh
424 .........................
426 ``run-cephadm-e2e-tests.sh`` runs a subset of E2E tests to verify that the Dashboard and cephadm as
427 Orchestrator backend behave correctly.
429 Prerequisites: you need to install `KCLI
430 <https://kcli.readthedocs.io/en/latest/>`_ and Node.js in your local machine.
432 Configure KCLI plan requirements::
434 $ sudo chown -R $(id -un) /var/lib/libvirt/images
435 $ mkdir -p /var/lib/libvirt/images/ceph-dashboard
436 $ kcli create pool -p /var/lib/libvirt/images/ceph-dashboard ceph-dashboard
437 $ kcli create network -c 192.168.100.0/24 ceph-dashboard
440 This script is aimed to be run as jenkins job so the cleanup is triggered only in a jenkins
441 environment. In local, the user will shutdown the cluster when desired (i.e. after debugging).
443 Start E2E tests by running::
445 $ cd <your/ceph/repo/dir>
446 $ sudo chown -R $(id -un) src/pybind/mgr/dashboard/frontend/{dist,node_modules,src/environments}
447 $ ./src/pybind/mgr/dashboard/ci/cephadm/run-cephadm-e2e-tests.sh
450 In fedora 35, there can occur a permission error when trying to mount the shared_folders. This can be
453 $ sudo setfacl -R -m u:qemu:rwx <abs-path-to-your-user-home>
455 or also by setting the appropriate permission to your $HOME directory
457 You can also start a cluster in development mode (so the frontend build starts in watch mode and you
458 only have to reload the page for the changes to be reflected) by running::
460 $ ./src/pybind/mgr/dashboard/ci/cephadm/start-cluster.sh --dev-mode
463 Add ``--expanded`` if you need a cluster ready to deploy services (one with enough monitor
464 daemons spread across different hosts and enough OSDs).
466 Test your changes by running:
468 $ ./src/pybind/mgr/dashboard/ci/cephadm/run-cephadm-e2e-tests.sh
470 Shutdown the cluster by running:
472 $ kcli delete plan -y ceph
473 $ # In development mode, also kill the npm build watch process (e.g., pkill -f "ng build")
475 Other running options
476 .....................
478 During active development, it is not recommended to run the previous script,
479 as it is not prepared for constant file changes.
480 Instead you should use one of the following commands:
482 - ``npm run e2e`` - This will run ``ng serve`` and open the Cypress Test Runner.
483 - ``npm run e2e:ci`` - This will run ``ng serve`` and run the Cypress Test Runner once.
484 - ``npx cypress run`` - This calls cypress directly and will run the Cypress Test Runner.
485 You need to have a running frontend server.
486 - ``npx cypress open`` - This calls cypress directly and will open the Cypress Test Runner.
487 You need to have a running frontend server.
489 Calling Cypress directly has the advantage that you can use any of the available
490 `flags <https://docs.cypress.io/guides/guides/command-line.html#cypress-run>`__
491 to customize your test run and you don't need to start a frontend server each time.
493 Using one of the ``open`` commands, will open a cypress application where you
494 can see all the test files you have and run each individually.
495 This is going to be run in watch mode, so if you make any changes to test files,
496 it will retrigger the test run.
497 This cannot be used inside docker, as it requires X11 environment to be able to open.
499 By default Cypress will look for the web page at ``https://localhost:4200/``.
500 If you are serving it in a different URL you will need to configure it by
501 exporting the environment variable CYPRESS_BASE_URL with the new value.
502 E.g.: ``CYPRESS_BASE_URL=https://localhost:41076/ npx cypress open``
505 .....................
507 When installing cypress via npm, a binary of the cypress app will also be
508 downloaded and stored in a cache folder.
509 This removes the need to download it every time you run ``npm ci`` or even when
510 using cypress in a separate project.
512 By default Cypress uses ~/.cache to store the binary.
513 To prevent changes to the user home directory, we have changed this folder to
514 ``/ceph/build/src/pybind/mgr/dashboard/cypress``, so when you build ceph or run
515 ``run-frontend-e2e-tests.sh`` this is the directory Cypress will use.
517 When using any other command to install or run cypress,
518 it will go back to the default directory. It is recommended that you export the
519 CYPRESS_CACHE_FOLDER environment variable with a fixed directory, so you always
520 use the same directory no matter which command you use.
523 Writing End-to-End Tests
524 ~~~~~~~~~~~~~~~~~~~~~~~~
526 The PagerHelper class
527 .....................
529 The ``PageHelper`` class is supposed to be used for general purpose code that
530 can be used on various pages or suites.
534 - ``navigateTo()`` - Navigates to a specific page and waits for it to load
535 - ``getFirstTableCell()`` - returns the first table cell. You can also pass a
536 string with the desired content and it will return the first cell that
538 - ``getTabsCount()`` - returns the amount of tabs
540 Every method that could be useful on several pages belongs there. Also, methods
541 which enhance the derived classes of the PageHelper belong there. A good
542 example for such a case is the ``restrictTo()`` decorator. It ensures that a
543 method implemented in a subclass of PageHelper is called on the correct page.
544 It will also show a developer-friendly warning if this is not the case.
546 Subclasses of PageHelper
547 ........................
552 In order to make code reusable which is specific for a particular suite, make
553 sure to put it in a derived class of the ``PageHelper``. For instance, when
554 talking about the pool suite, such methods would be ``create()``, ``exist()``
555 and ``delete()``. These methods are specific to a pool but are useful for other
558 Methods that return HTML elements which can only be found on a specific page,
559 should be either implemented in the helper methods of the subclass of PageHelper
560 or as own methods of the subclass of PageHelper.
565 In any suite, an instance of the specific ``Helper`` class should be
566 instantiated and called directly.
570 const pools = new PoolPageHelper();
572 it('should create a pool', () => {
573 pools.exist(poolName, false);
574 pools.navigateTo('create');
575 pools.create(poolName, 8);
576 pools.exist(poolName, true);
582 Please refer to the official `Cypress Core Concepts
583 <https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Cypress-Can-Be-Simple-Sometimes>`__
584 for a better insight on how to write and structure tests.
586 ``describe()`` vs ``it()``
587 """"""""""""""""""""""""""
589 Both ``describe()`` and ``it()`` are function blocks, meaning that any
590 executable code necessary for the test can be contained in either block.
591 However, Typescript scoping rules still apply, therefore any variables declared
592 in a ``describe`` are available to the ``it()`` blocks inside of it.
594 ``describe()`` typically are containers for tests, allowing you to break tests
595 into multiple parts. Likewise, any setup that must be made before your tests are
596 run can be initialized within the ``describe()`` block. Here is an example:
600 describe('create, edit & delete image test', () => {
601 const poolName = 'e2e_images_pool';
605 pools.navigateTo('create');
606 pools.create(poolName, 8, 'rbd');
607 pools.exist(poolName, true);
619 As shown, we can initiate the variable ``poolName`` as well as run commands
620 before our test suite begins (creating a pool). ``describe()`` block messages
621 should include what the test suite is.
623 ``it()`` blocks typically are parts of an overarching test. They contain the
624 functionality of the test suite, each performing individual roles.
629 describe('create, edit & delete image test', () => {
632 it('should create image', () => {
633 images.createImage(imageName, poolName, '1');
634 images.getFirstTableCell(imageName).should('exist');
637 it('should edit image', () => {
638 images.editImage(imageName, poolName, newImageName, '2');
639 images.getFirstTableCell(newImageName).should('exist');
645 As shown from the previous example, our ``describe()`` test suite is to create,
646 edit and delete an image. Therefore, each ``it()`` completes one of these steps,
647 one for creating, one for editing, and so on. Likewise, every ``it()`` blocks
648 message should be in lowercase and written so long as "it" can be the prefix of
649 the message. For example, ``it('edits the test image' () => ...)`` vs.
650 ``it('image edit test' () => ...)``. As shown, the first example makes
651 grammatical sense with ``it()`` as the prefix whereas the second message does
652 not. ``it()`` should describe what the individual test is doing and what it
656 Visual Regression Testing
657 ~~~~~~~~~~~~~~~~~~~~~~~~~
659 For visual regression testing, we use `Applitools Eyes <https://applitools.com/products-eyes/>`_
660 an AI powered automated visual regression testing tool.
661 Applitools integrates with our existing Cypress E2E tests.
662 The tests currently are located at: ``ceph/src/pybind/mgr/dashboard/frontend/cypress/integration/visualTests`` and
663 follow the naming convention: ``<component-name>.vrt-spec.ts``.
665 Running Visual Regression Tests Locally
666 .......................................
668 To run the tests locally, you'll need an Applitools API key, if you don't have one, you can sign up
669 for a free account. After obtaining the API key, export it as an environment variable: ``APPLITOOLS_API_KEY``.
671 Now you can run the tests like normal cypress E2E tests, using either ``npx cypress open`` or in headless mode by running ``npx cypress run``.
673 Capturing Screenshots
674 .....................
676 Baseline screenshots are the screenshots against which checkpoint screenshots
677 (or the screenshots from your feature branch) will be tested.
679 To capture baseline screenshots, you can run the tests against the master branch,
680 and then switch to your feature branch and run the tests again to capture checkpoint screenshots.
682 Now to see your screenshots, login to applitools.com and on the landing page you'll be greeted with
683 applitools eyes test runner, where you can see all your screenshots. And if there's any visual regression or difference (diff) between your baseline and checkpoint screenshots, they'll be highlighted with a mask over the diff.
685 Writing More Visual Regression Tests
686 ....................................
688 Please refer to `Applitools's official cypress sdk documentation <https://github.com/applitools/eyes.sdk.javascript1/tree/master/packages/eyes-cypress>`_ to write more tests.
690 Visual Regression Tests In Jenkins
691 ..................................
693 Currently, all visual regression tests are being run under `ceph dashboard tests <https://jenkins.ceph.com/job/ceph-dashboard-pull-requests>`_ GitHub check in the Jenkins job.
695 Accepting or Rejecting Differences
696 ..................................
698 Currently, only the ceph dashboard team has read and write access to the applitools test runner. If any differences are reported by the tests, and you want to accept them and update the baseline screenshots, or if the differences are due to a genuine regression you can fail them. To perform the above actions, please follow `this <https://applitools.com/docs/topics/test-manager/pages/page-test-results/tm-accepting-and-rejecting-steps.html>`_ guide.
700 Debugging Regressions
701 .....................
703 If you're running the tests locally and regressions are reported, you can take advantage of `Applitools's Root Cause Analysis feature <https://applitools.com/docs/topics/test-manager/viewers/root-cause-analysis.html>`_ to find the cause of the regression.
706 Differences between Frontend Unit Tests and End-to-End (E2E) Tests / FAQ
707 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
709 General introduction about testing and E2E/unit tests
712 What are E2E/unit tests designed for?
713 .....................................
717 It requires a fully functional system and tests the interaction of all components
718 of the application (Ceph, back-end, front-end).
719 E2E tests are designed to mimic the behavior of the user when interacting with the application
720 - for example when it comes to workflows like creating/editing/deleting an item.
721 Also the tests should verify that certain items are displayed as a user would see them
722 when clicking through the UI (for example a menu entry or a pool that has been
723 created during a test and the pool and its properties should be displayed in the table).
727 Unit tests, as the name suggests, are tests for smaller units of the code.
728 Those tests are designed for testing all kinds of Angular components (e.g. services, pipes etc.).
729 They do not require a connection to the backend, hence those tests are independent of it.
730 The expected data of the backend is mocked in the frontend and by using this data
731 the functionality of the frontend can be tested without having to have real data from the backend.
732 As previously mentioned, data is either mocked or, in a simple case, contains a static input,
733 a function call and an expected static output.
734 More complex examples include the state of a component (attributes of the component class),
735 that define how the output changes according to the given input.
737 Which E2E/unit tests are considered to be valid?
738 ................................................
740 This is not easy to answer, but new tests that are written in the same way as already existing
741 dashboard tests should generally be considered valid.
742 Unit tests should focus on the component to be tested.
743 This is either an Angular component, directive, service, pipe, etc.
745 E2E tests should focus on testing the functionality of the whole application.
746 Approximately a third of the overall E2E tests should verify the correctness
747 of user visible elements.
749 How should an E2E/unit test look like?
750 ......................................
752 Unit tests should focus on the described purpose
753 and shouldn't try to test other things in the same `it` block.
755 E2E tests should contain a description that either verifies
756 the correctness of a user visible element or a complete process
757 like for example the creation/validation/deletion of a pool.
759 What should an E2E/unit test cover?
760 ...................................
762 E2E tests should mostly, but not exclusively, cover interaction with the backend.
763 This way the interaction with the backend is utilized to write integration tests.
765 A unit test should mostly cover critical or complex functionality
766 of a component (Angular Components, Services, Pipes, Directives, etc).
768 What should an E2E/unit test NOT cover?
769 .......................................
771 Avoid duplicate testing: do not write E2E tests for what's already
772 been covered as frontend-unit tests and vice versa.
773 It may not be possible to completely avoid an overlap.
775 Unit tests should not be used to extensively click through components and E2E tests
776 shouldn't be used to extensively test a single component of Angular.
778 Best practices/guideline
779 ........................
781 As a general guideline we try to follow the 70/20/10 approach - 70% unit tests,
782 20% integration tests and 10% end-to-end tests.
783 For further information please refer to `this document
784 <https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html>`__
785 and the included "Testing Pyramid".
790 To get more help on the Angular CLI use ``ng help`` or go check out the
792 README <https://github.com/angular/angular-cli/blob/master/README.md>`__.
794 Example of a Generator
795 ~~~~~~~~~~~~~~~~~~~~~~
799 # Create module 'Core'
800 src/app> ng generate module core -m=app --routing
802 # Create module 'Auth' under module 'Core'
803 src/app/core> ng generate module auth -m=core --routing
805 src/app> ng generate module core/auth -m=core --routing
807 # Create component 'Login' under module 'Auth'
808 src/app/core/auth> ng generate component login -m=core/auth
810 src/app> ng generate component core/auth/login -m=core/auth
812 Frontend Typescript Code Style Guide Recommendations
813 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
815 Group the imports based on its source and separate them with a blank
818 The source groups can be either from Angular, external or internal.
824 import { Component } from '@angular/core';
825 import { Router } from '@angular/router';
827 import { ToastrManager } from 'ngx-toastr';
829 import { Credentials } from '../../../shared/models/credentials.model';
830 import { HostService } from './services/host.service';
835 There are several components that can be reused on different pages.
836 This components are declared on the components module:
837 `src/pybind/mgr/dashboard/frontend/src/app/shared/components`.
842 This component should be used to provide additional information to the user.
849 Some <strong>helper</strong> html text
852 Terminology and wording
853 ~~~~~~~~~~~~~~~~~~~~~~~
855 Instead of using the Ceph component names, the approach
856 suggested is to use the logical/generic names (Block over RBD, Filesystem over
857 CephFS, Object over RGW). Nevertheless, as Ceph-Dashboard cannot completely hide
858 the Ceph internals, some Ceph-specific names might remain visible.
860 Regarding the wording for action labels and other textual elements (form titles,
861 buttons, etc.), the chosen approach is to follow `these guidelines
862 <https://www.patternfly.org/styles/terminology-and-wording/#terminology-and-wording-for-action-labels>`_.
863 As a rule of thumb, 'Create' and 'Delete' are the proper wording for most forms,
864 instead of 'Add' and 'Remove', unless some already created item is either added
865 or removed to/from a set of items (e.g.: 'Add permission' to a user vs. 'Create
868 In order to enforce the use of this wording, a service ``ActionLabelsI18n`` has
869 been created, which provides translated labels for use in UI elements.
874 Every vendor can customize the 'Ceph dashboard' to his needs. No matter if
875 logo, HTML-Template or TypeScript, every file inside the frontend folder can be
878 To replace files, open ``./frontend/angular.json`` and scroll to the section
879 ``fileReplacements`` inside the production configuration. Here you can add the
880 files you wish to brand. We recommend to place the branded version of a file in
881 the same directory as the original one and to add a ``.brand`` to the file
882 name, right in front of the file extension. A ``fileReplacement`` could for
883 example look like this:
888 "replace": "src/app/core/auth/login/login.component.html",
889 "with": "src/app/core/auth/login/login.component.brand.html"
892 To serve or build the branded user interface run:
894 $ npm run start -- --prod
898 $ npm run build -- --prod
900 Unfortunately it's currently not possible to use multiple configurations when
901 serving or building the UI at the same time. That means a configuration just
902 for the branding ``fileReplacements`` is not an option, because you want to use
903 the production configuration anyway
904 (https://github.com/angular/angular-cli/issues/10612).
905 Furthermore it's also not possible to use glob expressions for
906 ``fileReplacements``. As long as the feature hasn't been implemented, you have
907 to add the file replacements manually to the angular.json file
908 (https://github.com/angular/angular-cli/issues/12354).
910 Nevertheless you should stick to the suggested naming scheme because it makes
911 it easier for you to use glob expressions once it's supported in the future.
913 To change the variable defaults or add your own ones you can overwrite them in
914 ``./frontend/src/styles/vendor/_variables.scss``.
915 Just reassign the variable you want to change, for example ``$color-primary: teal;``
916 To overwrite or extend the default CSS, you can add your own styles in
917 ``./frontend/src/styles/vendor/_style-overrides.scss``.
922 The style guide is created to document Ceph Dashboard standards and maintain
923 consistency across the project. Its an effort to make it easier for
924 contributors to process designing and deciding mockups and designs for
927 The development environment for Ceph Dashboard has live reloading enabled so
928 any changes made in UI are reflected in open browser windows. Ceph Dashboard
929 uses Bootstrap as the main third-party CSS library.
931 Avoid duplication of code. Be consistent with the existing UI by reusing
932 existing SCSS declarations as much as possible.
934 Always check for existing code similar to what you want to write.
935 You should always try to keep the same look-and-feel as the existing code.
940 All the colors used in Ceph Dashboard UI are listed in
941 `frontend/src/styles/defaults/_bootstrap-defaults.scss`. If using new color
942 always define color variables in the `_bootstrap-defaults.scss` and
943 use the variable instead of hard coded color values so that changes to the
944 color are reflected in similar UI elements.
946 The main color for the Ceph Dashboard is `$primary`. The primary color is
947 used in navigation components and as the `$border-color` for input components of
950 The secondary color is `$secondary` and is the background color for Ceph
956 Buttons are used for performing actions such as: “Submit”, “Edit, “Create" and
959 **Forms:** When using to submit forms anywhere in the Dashboard, the main action
960 button should use the `cd-submit-button` component and the secondary button should
961 use `cd-back-button` component. The text on the action button should be same as the
962 form title and follow a title case. The text on the secondary button should be
963 `Cancel`. `Perform action` button should always be on right while `Cancel`
964 button should always be on left.
966 **Modals**: The main action button should use the `cd-submit-button` component and
967 the secondary button should use `cd-back-button` component. The text on the action
968 button should follow a title case and correspond to the action to be performed.
969 The text on the secondary button should be `Close`.
971 **Disclosure Button:** Disclosure buttons should be used to allow users to
972 display and hide additional content in the interface.
974 **Action Button**: Use the action button to perform actions such as edit or update
975 a component. All action button should have an icon corresponding to the actions they
976 perform and button text should follow title case. The button color should be the
977 same as the form's main button color.
979 **Drop Down Buttons:** Use dropdown buttons to display predefined lists of
980 actions. All drop down buttons have icons corresponding to the action they
986 Use text hyperlinks as navigation to guide users to a new page in the application
987 or to anchor users to a section within a page. The color of the hyperlinks
988 should be `$primary`.
993 Mark invalid form fields with red outline and show a meaningful error message.
994 Use red as font color for message and be as specific as possible.
995 `This field is required.` should be the exact error message for required fields.
996 Mark valid forms with a green outline and a green tick at the end of the form.
997 Sections should not have a bigger header than the parent.
1002 Blur any interface elements in the background to bring the modal content into
1003 focus. The heading of the modal should reflect the action it can perform and
1004 should be clearly mentioned at the top of the modal. Use `cd-back-button`
1005 component in the footer for closing the modal.
1010 We use `Fork Awesome <https://forkaweso.me/Fork-Awesome/>`_ classes for icons.
1011 We have a list of used icons in `src/app/shared/enum/icons.enum.ts`, these
1012 should be referenced in the HTML, so its easier to change them later. When
1013 icons are next to text, they should be center-aligned horizontally. If icons
1014 are stacked, they should also be center-aligned vertically. Use small icons
1015 with buttons. For notifications use large icons.
1020 For local navigation use tabs. For overall navigation use expandable vertical
1021 navigation to collapse and expand items as needed.
1023 Alerts and notifications
1024 ........................
1026 Default notification should have `text-info` color. Success notification should
1027 have `text-success` color. Failure notification should have `text-danger` color.
1032 For handling front-end errors, there is a generic Error Component which can be
1033 found in ``./src/pybind/mgr/dashboard/frontend/src/app/core/error``. For
1034 reporting a new error, you can simply extend the ``DashboardError`` class
1035 in ``error.ts`` file and add specific header and message for the new error. Some
1036 generic error classes are already in place such as ``DashboardNotFoundError``
1037 and ``DashboardForbiddenError`` which can be called and reused in different
1040 For example - ``throw new DashboardNotFoundError()``.
1042 Internationalization (i18n)
1043 ---------------------------
1045 How to extract messages from source code?
1046 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1048 To extract the I18N messages from the templates and the TypeScript files just
1049 run the following command in ``src/pybind/mgr/dashboard/frontend``::
1051 $ npm run i18n:extract
1053 This will extract all marked messages from the HTML templates first and then
1054 add all marked strings from the TypeScript files to the translation template.
1055 Since the extraction from TypeScript files is still not supported by Angular
1056 itself, we are using the
1057 `ngx-translator <https://github.com/ngx-translate/i18n-polyfill>`_ extractor to
1058 parse the TypeScript files.
1060 When the command ran successfully, it should have created or updated the file
1061 ``src/locale/messages.xlf``.
1063 The file isn't tracked by git, you can just use it to start with the
1064 translation offline or add/update the resource files on transifex.
1069 All our supported languages should be registered in both exports in
1070 ``supported-languages.enum.ts`` and have a corresponding test in
1071 ``language-selector.component.spec.ts``.
1073 The ``SupportedLanguages`` enum will provide the list for the default language selection.
1078 To facilitate the translation process of the dashboard we are using a web tool
1079 called `transifex <https://www.transifex.com/>`_.
1081 If you wish to help translating to any language just go to our `transifex
1082 project page <https://www.transifex.com/ceph/ceph-dashboard/>`_, join the
1083 project and you can start translating immediately.
1085 All translations will then be reviewed and later pushed upstream.
1087 Updating translated messages
1088 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1090 Any time there are new messages translated and reviewed in a specific language
1091 we should update the translation file upstream.
1093 To do that, check the settings in the i18n config file
1094 ``src/pybind/mgr/dashboard/frontend/i18n.config.json``:: and make sure that the
1095 organization is *ceph*, the project is *ceph-dashboard* and the resource is
1096 the one you want to pull from and push to e.g. *Master:master*. To find a list
1097 of available resources visit `<https://www.transifex.com/ceph/ceph-dashboard/content/>`_.
1099 After you checked the config go to the directory ``src/pybind/mgr/dashboard/frontend`` and run::
1103 This command will extract all marked messages from the HTML templates and
1104 TypeScript files. Once the source file has been created it will push it to
1105 transifex and pull the latest translations. It will also fill all the
1106 untranslated strings with the source string.
1107 The tool will ask you for an api token, unless you added it by running:
1109 $ npm run i18n:token
1111 To create a transifex api token visit `<https://www.transifex.com/user/settings/api/>`_.
1113 After the command ran successfully, build the UI and check if everything is
1114 working as expected. You also might want to run the frontend tests.
1116 Add a new release resource to transifex
1117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1119 In order to organize the translations, we create a
1120 `transifex resource <https://www.transifex.com/ceph/ceph-dashboard/content/>`_
1121 for every Ceph release. This means, once a new version has been released, the
1122 ``src/pybind/mgr/dashboard/frontend/i18n.config.json`` needs to be updated on
1127 "resource": "Master:master"
1131 "resource": "<Release-name>:<release-name>"
1133 E.g. the resource definition for the pacific release::
1135 "resource": "Pacific:pacific"
1138 The first part of the resource definition (before the colon) needs to be
1139 written with a capital letter.
1144 Strings need to start and end in the same line as the element:
1146 .. code-block:: html
1153 <!-- recommended -->
1154 <span i18n>Foo</span>
1163 <!-- recommended -->
1164 <span i18n>Foo bar baz.
1167 Isolated interpolations should not be translated:
1169 .. code-block:: html
1172 <span i18n>{{ foo }}</span>
1174 <!-- recommended -->
1175 <span>{{ foo }}</span>
1177 Interpolations used in a sentence should be kept in the translation:
1179 .. code-block:: html
1181 <!-- recommended -->
1182 <span i18n>There are {{ x }} OSDs.</span>
1184 Remove elements that are outside the context of the translation:
1186 .. code-block:: html
1191 <span class="required"></span>
1194 <!-- recommended -->
1196 <ng-container i18n>Profile<ng-container>
1197 <span class="required"></span>
1200 Keep elements that affect the sentence:
1202 .. code-block:: html
1204 <!-- recommended -->
1205 <span i18n>Profile <b>foo</b> will be removed.</span>
1213 Many parts of the Ceph Dashboard are modeled on `Web Content Accessibility Guidelines (WCAG) 2.1 <https://www.w3.org/TR/WCAG21/>`_ level A accessibility conformance guidelines.
1214 By implementing accessibility best practices, you are improving the usability of the Ceph Dashboard for blind and visually impaired users.
1219 A few things you should check before introducing a new code change include:
1221 1) Add `ARIA labels and descriptions <https://www.w3.org/TR/wai-aria/>`_ to actionable HTML elements.
1222 2) Don't forget to tag ARIA labels/descriptions or any user-readable text for translation (i18n-title, i18n-aria-label...).
1223 3) Add `ARIA roles <https://www.w3.org/TR/wai-aria/#usage_intro>`_ to tag HTML elements that behave different from their intended behaviour (<a> tags behaving as <buttons>) or that provide extended behaviours (roles).
1224 4) Avoid poor `color contrast choices <https://www.w3.org/TR/WCAG21/#contrast-minimum>`_ (foreground-background) when styling a component. Here are some :ref:`tools <color-contrast-checkers>` you can use.
1225 5) When testing menus or dropdowns, be sure to scan them with an :ref:`accessibility checker <accessibility-checkers>` in both opened and closed states. Sometimes issues are hidden when menus are closed.
1227 .. _accessibility-checkers:
1229 Accessibility checkers
1230 ~~~~~~~~~~~~~~~~~~~~~~
1232 During development, you can test the accessibility compliance of your features using one of the tools below:
1234 - `Accessibility insights plugin <https://accessibilityinsights.io/downloads/>`_
1235 - `Site Improve plugin <https://www.siteimprove.com/integrations/browser-extensions/>`_
1236 - `Axe devtools <https://www.deque.com/axe/devtools/>`_
1238 Testing with two or more of these tools can greatly improve the detection of accessibility violations.
1240 .. _color-contrast-checkers:
1242 Color contrast checkers
1243 ~~~~~~~~~~~~~~~~~~~~~~~
1245 When adding new colors, making sure they are accessible is also important. Here are some tools which can help with color contrast testing:
1247 - `Accessible web color-contrast checker <https://accessibleweb.com/color-contrast-checker/>`_
1248 - `Colorsafe generator <https://colorsafe.co/>`_
1250 Accessibility linters
1251 ~~~~~~~~~~~~~~~~~~~~~
1253 If you use VSCode, you may install the `axe accessibility linter <https://marketplace.visualstudio.com/items?itemName=deque-systems.vscode-axe-linter>`_,
1254 which can help you catch and fix potential issues during development.
1256 Accessibility testing
1257 ~~~~~~~~~~~~~~~~~~~~~
1259 Our e2e testing suite, which is based on Cypress, supports the addition of accessibility tests using `axe-core <https://github.com/dequelabs/axe-core>`_
1260 and `cypress-axe <https://github.com/component-driven/cypress-axe>`_. A custom Cypress command, `cy.checkAccessibility`, can also be used directly.
1261 This is a great way to prevent accessibility regressions on high impact components.
1263 Tests can be found under the `a11y folder <./src/pybind/mgr/dashboard/frontend/cypress/integration/a11y>`_ in the dashboard. Here is an example:
1265 .. code:: TypeScript
1267 describe('Navigation accessibility', { retries: 0 }, () => {
1268 const shared = new NavigationPageHelper();
1272 Cypress.Cookies.preserveOnce('token');
1273 shared.navigateTo();
1276 it('top-nav should have no accessibility violations', () => {
1278 cy.checkAccessibility('.cd-navbar-top');
1281 it('sidebar should have no accessibility violations', () => {
1283 cy.checkAccessibility('nav[id=sidebar]');
1288 Additional guidelines
1289 ~~~~~~~~~~~~~~~~~~~~~
1291 If you're unsure about which UI pattern to follow in order to implement an accessibility fix, `patternfly <https://www.patternfly.org/v4/accessibility/accessibility-fundamentals>`_ guidelines can be used.
1296 The Python backend code of this module requires a number of Python modules to be
1297 installed. They are listed in file ``requirements.txt``. Using `pip
1298 <https://pypi.python.org/pypi/pip>`_ you may install all required dependencies
1299 by issuing ``pip install -r requirements.txt`` in directory
1300 ``src/pybind/mgr/dashboard``.
1302 If you're using the `ceph-dev-docker development environment
1303 <https://github.com/ricardoasmarques/ceph-dev-docker/>`_, simply run
1304 ``./install_deps.sh`` from the toplevel directory to install them.
1309 In dashboard we have two different kinds of backend tests:
1311 1. Unit tests based on ``tox``
1312 2. API tests based on Teuthology.
1314 Unit tests based on tox
1315 ~~~~~~~~~~~~~~~~~~~~~~~~
1317 We included a ``tox`` configuration file that will run the unit tests under
1318 Python 3, as well as linting tools to guarantee the uniformity of code.
1320 You need to install ``tox`` and ``coverage`` before running it. To install the
1321 packages in your system, either install it via your operating system's package
1322 management tools, e.g. by running ``dnf install python-tox python-coverage`` on
1325 Alternatively, you can use Python's native package installation method::
1328 $ pip install coverage
1330 To run the tests, run ``src/script/run_tox.sh`` in the dashboard directory (where
1331 ``tox.ini`` is located)::
1333 ## Run Python 3 tests+lint commands:
1334 $ ../../../script/run_tox.sh --tox-env py3,lint,check
1336 ## Run Python 3 arbitrary command (e.g. 1 single test):
1337 $ ../../../script/run_tox.sh --tox-env py3 "" tests/test_rgw_client.py::RgwClientTest::test_ssl_verify
1339 You can also run tox instead of ``run_tox.sh``::
1341 ## Run Python 3 tests command:
1344 ## Run Python 3 arbitrary command (e.g. 1 single test):
1345 $ tox -e py3 tests/test_rgw_client.py::RgwClientTest::test_ssl_verify
1347 Python files can be automatically fixed and formatted according to PEP8
1348 standards by using ``run_tox.sh --tox-env fix`` or ``tox -e fix``.
1350 We also collect coverage information from the backend code when you run tests. You can check the
1351 coverage information provided by the tox output, or by running the following
1352 command after tox has finished successfully::
1356 This command will create a directory ``htmlcov`` with an HTML representation of
1357 the code coverage of the backend.
1359 API tests based on Teuthology
1360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1362 How to run existing API tests:
1363 To run the API tests against a real Ceph cluster, we leverage the Teuthology
1364 framework. This has the advantage of catching bugs originated from changes in
1365 the internal Ceph code.
1367 Our ``run-backend-api-tests.sh`` script will start a ``vstart`` Ceph cluster
1368 before running the Teuthology tests, and then it stops the cluster after the
1369 tests are run. Of course this implies that you have built/compiled Ceph
1372 Start all dashboard tests by running::
1374 $ ./run-backend-api-tests.sh
1376 Or, start one or multiple specific tests by specifying the test name::
1378 $ ./run-backend-api-tests.sh tasks.mgr.dashboard.test_pool.PoolTest
1380 Or, ``source`` the script and run the tests manually::
1382 $ source run-backend-api-tests.sh
1383 $ run_teuthology_tests [tests]...
1384 $ cleanup_teuthology
1386 How to write your own tests:
1387 There are two possible ways to write your own API tests:
1389 The first is by extending one of the existing test classes in the
1390 ``qa/tasks/mgr/dashboard`` directory.
1392 The second way is by adding your own API test module if you're creating a new
1393 controller for example. To do so you'll just need to add the file containing
1394 your new test class to the ``qa/tasks/mgr/dashboard`` directory and implement
1395 all your tests here.
1397 .. note:: Don't forget to add the path of the newly created module to
1398 ``modules`` section in ``qa/suites/rados/mgr/tasks/dashboard.yaml``.
1400 Short example: Let's assume you created a new controller called
1401 ``my_new_controller.py`` and the related test module
1402 ``test_my_new_controller.py``. You'll need to add
1403 ``tasks.mgr.dashboard.test_my_new_controller`` to the ``modules`` section in
1404 the ``dashboard.yaml`` file.
1406 Also, if you're removing test modules please keep in mind to remove the
1407 related section. Otherwise the Teuthology test run will fail.
1409 Please run your API tests on your dev environment (as explained above)
1410 before submitting a pull request. Also make sure that a full QA run in
1411 Teuthology/sepia lab (based on your changes) has completed successfully
1412 before it gets merged. You don't need to schedule the QA run yourself, just
1413 add the 'needs-qa' label to your pull request as soon as you think it's ready
1414 for merging (e.g. make check was successful, the pull request is approved and
1415 all comments have been addressed). One of the developers who has access to
1416 Teuthology/the sepia lab will take care of it and report the result back to
1420 How to add a new controller?
1421 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1423 A controller is a Python class that extends from the ``BaseController`` class
1424 and is decorated with either the ``@Controller``, ``@ApiController`` or
1425 ``@UiApiController`` decorators. The Python class must be stored inside a Python
1426 file located under the ``controllers`` directory. The Dashboard module will
1427 automatically load your new controller upon start.
1429 ``@ApiController`` and ``@UiApiController`` are both specializations of the
1430 ``@Controller`` decorator.
1432 The ``@ApiController`` should be used for controllers that provide an API-like
1433 REST interface and the ``@UiApiController`` should be used for endpoints consumed
1434 by the UI but that are not part of the 'public' API. For any other kinds of
1435 controllers the ``@Controller`` decorator should be used.
1437 A controller has a URL prefix path associated that is specified in the
1438 controller decorator, and all endpoints exposed by the controller will share
1439 the same URL prefix path.
1441 A controller's endpoint is exposed by implementing a method on the controller
1442 class decorated with the ``@Endpoint`` decorator.
1444 For example create a file ``ping.py`` under ``controllers`` directory with the
1447 .. code-block:: python
1449 from ..tools import Controller, ApiController, UiApiController, BaseController, Endpoint
1451 @Controller('/ping')
1452 class Ping(BaseController):
1455 return {'msg': "Hello"}
1457 @ApiController('/ping')
1458 class ApiPing(BaseController):
1461 return {'msg': "Hello"}
1463 @UiApiController('/ping')
1464 class UiApiPing(BaseController):
1467 return {'msg': "Hello"}
1469 The ``hello`` endpoint of the ``Ping`` controller can be reached by the
1470 following URL: https://mgr_hostname:8443/ping/hello using HTTP GET requests.
1471 As you can see the controller URL path ``/ping`` is concatenated to the
1472 method name ``hello`` to generate the endpoint's URL.
1474 In the case of the ``ApiPing`` controller, the ``hello`` endpoint can be
1475 reached by the following URL: https://mgr_hostname:8443/api/ping/hello using a
1477 The API controller URL path ``/ping`` is prefixed by the ``/api`` path and then
1478 concatenated to the method name ``hello`` to generate the endpoint's URL.
1479 Internally, the ``@ApiController`` is actually calling the ``@Controller``
1480 decorator by passing an additional decorator parameter called ``base_url``::
1482 @ApiController('/ping') <=> @Controller('/ping', base_url="/api")
1484 ``UiApiPing`` works in a similar way than the ``ApiPing``, but the URL will be
1485 prefixed by ``/ui-api``: https://mgr_hostname:8443/ui-api/ping/hello. ``UiApiPing`` is
1486 also a ``@Controller`` extension::
1488 @UiApiController('/ping') <=> @Controller('/ping', base_url="/ui-api")
1490 The ``@Endpoint`` decorator also supports many parameters to customize the
1493 * ``method="GET"``: the HTTP method allowed to access this endpoint.
1494 * ``path="/<method_name>"``: the URL path of the endpoint, excluding the
1495 controller URL path prefix.
1496 * ``path_params=[]``: list of method parameter names that correspond to URL
1497 path parameters. Can only be used when ``method in ['POST', 'PUT']``.
1498 * ``query_params=[]``: list of method parameter names that correspond to URL
1500 * ``json_response=True``: indicates if the endpoint response should be
1501 serialized in JSON format.
1502 * ``proxy=False``: indicates if the endpoint should be used as a proxy.
1504 An endpoint method may have parameters declared. Depending on the HTTP method
1505 defined for the endpoint the method parameters might be considered either
1506 path parameters, query parameters, or body parameters.
1508 For ``GET`` and ``DELETE`` methods, the method's non-optional parameters are
1509 considered path parameters by default. Optional parameters are considered
1510 query parameters. By specifying the ``query_parameters`` in the endpoint
1511 decorator it is possible to make a non-optional parameter to be a query
1514 For ``POST`` and ``PUT`` methods, all method parameters are considered
1515 body parameters by default. To override this default, one can use the
1516 ``path_params`` and ``query_params`` to specify which method parameters are
1517 path and query parameters respectively.
1518 Body parameters are decoded from the request body, either from a form format, or
1519 from a dictionary in JSON format.
1521 Let's use an example to better understand the possible ways to customize an
1524 .. code-block:: python
1526 from ..tools import Controller, BaseController, Endpoint
1528 @Controller('/ping')
1529 class Ping(BaseController):
1531 # URL: /ping/{key}?opt1=...&opt2=...
1532 @Endpoint(path="/", query_params=['opt1'])
1533 def index(self, key, opt1, opt2=None):
1536 # URL: /ping/{key}?opt1=...&opt2=...
1537 @Endpoint(query_params=['opt1'])
1538 def __call__(self, key, opt1, opt2=None):
1541 # URL: /ping/post/{key1}/{key2}
1542 @Endpoint('POST', path_params=['key1', 'key2'])
1543 def post(self, key1, key2, data1, data2=None):
1547 In the above example we see how the ``path`` option can be used to override the
1548 generated endpoint URL in order to not use the method's name in the URL. In the
1549 ``index`` method we set the ``path`` to ``"/"`` to generate an endpoint that is
1550 accessible by the root URL of the controller.
1552 An alternative approach to generate an endpoint that is accessible through just
1553 the controller's path URL is by using the ``__call__`` method, as we show in
1556 From the third method you can see that the path parameters are collected from
1557 the URL by parsing the list of values separated by slashes ``/`` that come
1558 after the URL path ``/ping`` for ``index`` method case, and ``/ping/post`` for
1559 the ``post`` method case.
1561 Defining path parameters in endpoints's URLs using python methods's parameters
1562 is very easy but it is still a bit strict with respect to the position of these
1563 parameters in the URL structure.
1564 Sometimes we may want to explicitly define a URL scheme that
1565 contains path parameters mixed with static parts of the URL.
1566 Our controller infrastructure also supports the declaration of URL paths with
1567 explicit path parameters at both the controller level and method level.
1569 Consider the following example:
1571 .. code-block:: python
1573 from ..tools import Controller, BaseController, Endpoint
1575 @Controller('/ping/{node}/stats')
1576 class Ping(BaseController):
1578 # URL: /ping/{node}/stats/{date}/latency?unit=...
1579 @Endpoint(path="/{date}/latency")
1580 def latency(self, node, date, unit="ms"):
1583 In this example we explicitly declare a path parameter ``{node}`` in the
1584 controller URL path, and a path parameter ``{date}`` in the ``latency``
1585 method. The endpoint for the ``latency`` method is then accessible through
1586 the URL: https://mgr_hostname:8443/ping/{node}/stats/{date}/latency .
1588 For a full set of examples on how to use the ``@Endpoint``
1589 decorator please check the unit test file: ``tests/test_controllers.py``.
1590 There you will find many examples of how to customize endpoint methods.
1593 Implementing Proxy Controller
1594 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1596 Sometimes you might need to relay some requests from the Dashboard frontend
1597 directly to an external service.
1598 For that purpose we provide a decorator called ``@Proxy``.
1599 (As a concrete example, check the ``controllers/rgw.py`` file where we
1600 implemented an RGW Admin Ops proxy.)
1603 The ``@Proxy`` decorator is a wrapper of the ``@Endpoint`` decorator that
1604 already customizes the endpoint for working as a proxy.
1605 A proxy endpoint works by capturing the URL path that follows the controller
1606 URL prefix path, and does not do any decoding of the request body.
1610 .. code-block:: python
1612 from ..tools import Controller, BaseController, Proxy
1614 @Controller('/foo/proxy')
1615 class FooServiceProxy(BaseController):
1618 def proxy(self, path, **params):
1620 if requested URL is "/foo/proxy/access/service?opt=1"
1621 then path is "access/service" and params is {'opt': '1'}
1625 How does the RESTController work?
1626 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1628 We also provide a simple mechanism to create REST based controllers using the
1629 ``RESTController`` class. Any class which inherits from ``RESTController`` will,
1630 by default, return JSON.
1632 The ``RESTController`` is basically an additional abstraction layer which eases
1633 and unifies the work with collections. A collection is just an array of objects
1634 with a specific type. ``RESTController`` enables some default mappings of
1635 request types and given parameters to specific method names. This may sound
1636 complicated at first, but it's fairly easy. Lets have look at the following
1639 .. code-block:: python
1642 from ..tools import ApiController, RESTController
1644 @ApiController('ping')
1645 class Ping(RESTController):
1647 return {"msg": "Hello"}
1650 return self.objects[id]
1652 In this case, the ``list`` method is automatically used for all requests to
1653 ``api/ping`` where no additional argument is given and where the request type
1654 is ``GET``. If the request is given an additional argument, the ID in our
1655 case, it won't map to ``list`` anymore but to ``get`` and return the element
1656 with the given ID (assuming that ``self.objects`` has been filled before). The
1657 same applies to other request types:
1659 +--------------+------------+----------------+-------------+
1660 | Request type | Arguments | Method | Status Code |
1661 +==============+============+================+=============+
1662 | GET | No | list | 200 |
1663 +--------------+------------+----------------+-------------+
1664 | PUT | No | bulk_set | 200 |
1665 +--------------+------------+----------------+-------------+
1666 | POST | No | create | 201 |
1667 +--------------+------------+----------------+-------------+
1668 | DELETE | No | bulk_delete | 204 |
1669 +--------------+------------+----------------+-------------+
1670 | GET | Yes | get | 200 |
1671 +--------------+------------+----------------+-------------+
1672 | PUT | Yes | set | 200 |
1673 +--------------+------------+----------------+-------------+
1674 | DELETE | Yes | delete | 204 |
1675 +--------------+------------+----------------+-------------+
1677 To use a custom endpoint for the above listed methods, you can
1678 use ``@RESTController.MethodMap``
1680 .. code-block:: python
1683 from ..tools import ApiController, RESTController
1685 @RESTController.MethodMap(version='0.1')
1687 return {"msg": "Hello"}
1689 This decorator supports three parameters to customize the
1692 * ``resource"``: resource id.
1693 * ``status=200``: set the HTTP status response code
1694 * ``version``: version
1696 How to use a custom API endpoint in a RESTController?
1697 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1699 If you don't have any access restriction you can use ``@Endpoint``. If you
1700 have set a permission scope to restrict access to your endpoints,
1701 ``@Endpoint`` will fail, as it doesn't know which permission property should be
1702 used. To use a custom endpoint inside a restricted ``RESTController`` use
1703 ``@RESTController.Collection`` instead. You can also choose
1704 ``@RESTController.Resource`` if you have set a ``RESOURCE_ID`` in your
1705 ``RESTController`` class.
1707 .. code-block:: python
1710 from ..tools import ApiController, RESTController
1712 @ApiController('ping', Scope.Ping)
1713 class Ping(RESTController):
1714 RESOURCE_ID = 'ping'
1716 @RESTController.Resource('GET')
1717 def some_get_endpoint(self):
1718 return {"msg": "Hello"}
1720 @RESTController.Collection('POST')
1721 def some_post_endpoint(self, **data):
1722 return {"msg": data}
1724 Both decorators also support five parameters to customize the
1727 * ``method="GET"``: the HTTP method allowed to access this endpoint.
1728 * ``path="/<method_name>"``: the URL path of the endpoint, excluding the
1729 controller URL path prefix.
1730 * ``status=200``: set the HTTP status response code
1731 * ``query_params=[]``: list of method parameter names that correspond to URL
1733 * ``version``: version
1735 How to restrict access to a controller?
1736 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1738 All controllers require authentication by default.
1739 If you require that the controller can be accessed without authentication,
1740 then you can add the parameter ``secure=False`` to the controller decorator.
1744 .. code-block:: python
1747 from . import ApiController, RESTController
1750 @ApiController('ping', secure=False)
1751 class Ping(RESTController):
1753 return {"msg": "Hello"}
1755 How to create a dedicated UI endpoint which uses the 'public' API?
1756 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1758 Sometimes we want to combine multiple calls into one single call
1759 to save bandwidth or for other performance reasons.
1760 In order to achieve that, we first have to create an ``@UiApiController`` which
1761 is used for endpoints consumed by the UI but that are not part of the
1762 'public' API. Let the ui class inherit from the REST controller class.
1763 Now you can use all methods from the api controller.
1767 .. code-block:: python
1770 from . import UiApiController, ApiController, RESTController
1773 @ApiController('ping', secure=False) # /api/ping
1774 class Ping(RESTController):
1778 def _list(self): # To not get in conflict with the JSON wrapper
1782 @UiApiController('ping', secure=False) # /ui-api/ping
1785 return self._list() + [4, 5, 6]
1787 How to access the manager module instance from a controller?
1788 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1790 We provide the manager module instance as a global variable that can be
1791 imported in any module.
1795 .. code-block:: python
1800 from ..tools import ApiController, RESTController
1802 logger = logging.getLogger(__name__)
1804 @ApiController('servers')
1805 class Servers(RESTController):
1807 logger.debug('Listing available servers')
1808 return {'servers': mgr.list_servers()}
1811 How to write a unit test for a controller?
1812 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1814 We provide a test helper class called ``ControllerTestCase`` to easily create
1815 unit tests for your controller.
1817 If we want to write a unit test for the above ``Ping`` controller, create a
1818 ``test_ping.py`` file under the ``tests`` directory with the following code:
1820 .. code-block:: python
1822 from .helper import ControllerTestCase
1823 from .controllers.ping import Ping
1826 class PingTest(ControllerTestCase):
1828 def setup_test(cls):
1829 cp_config = {'tools.authenticate.on': True}
1830 cls.setup_controllers([Ping], cp_config=cp_config)
1832 def test_ping(self):
1833 self._get("/api/ping")
1834 self.assertStatus(200)
1835 self.assertJsonBody({'msg': 'Hello'})
1837 The ``ControllerTestCase`` class starts by initializing a CherryPy webserver.
1838 Then it will call the ``setup_test()`` class method where we can explicitly
1839 load the controllers that we want to test. In the above example we are only
1840 loading the ``Ping`` controller. We can also provide ``cp_config`` in order to
1841 update the controller's cherrypy config (e.g. enable authentication as shown in the example).
1843 How to update or create new dashboards in grafana?
1844 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1846 We are using ``jsonnet`` and ``grafonnet-lib`` to write code for the grafana dashboards.
1847 All the dashboards are written inside ``grafana_dashboards.jsonnet`` file in the
1848 monitoring/grafana/dashboards/jsonnet directory.
1850 We generate the dashboard json files directly from this jsonnet file by running this
1851 command in the grafana/dashboards directory:
1852 ``jsonnet -m . jsonnet/grafana_dashboards.jsonnet``.
1853 (For the above command to succeed we need ``jsonnet`` package installed and ``grafonnet-lib``
1854 directory cloned in our machine. Please refer -
1855 ``https://grafana.github.io/grafonnet-lib/getting-started/`` in case you have some trouble.)
1857 To update an existing grafana dashboard or to create a new one, we need to update
1858 the ``grafana_dashboards.jsonnet`` file and generate the new/updated json files using the
1859 above mentioned command. For people who are not familiar with grafonnet or jsonnet implementation
1860 can follow this doc - ``https://grafana.github.io/grafonnet-lib/``.
1862 Example grafana dashboard in jsonnet format:
1864 To specify the grafana dashboard properties such as title, uid etc we can create a local function -
1868 local dashboardSchema(title, uid, time_from, refresh, schemaVersion, tags,timezone, timepicker)
1870 To add a graph panel we can spcify the graph schema in a local function such as -
1874 local graphPanelSchema(title, nullPointMode, stack, formatY1, formatY2, labelY1, labelY2, min, fill, datasource)
1876 and then use these functions inside the dashboard definition like -
1881 radosgw-sync-overview.json: //json file name to be generated
1884 'RGW Sync Overview', 'rgw-sync-overview', 'now-1h', '15s', .., .., ..
1889 'Replication (throughput) from Source Zone', 'Bps', null, .., .., ..)
1893 The valid grafonnet-lib attributes can be found here - ``https://grafana.github.io/grafonnet-lib/api-docs/``.
1896 How to listen for manager notifications in a controller?
1897 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1899 The manager notifies the modules of several types of cluster events, such
1900 as cluster logging event, etc...
1902 Each module has a "global" handler function called ``notify`` that the manager
1903 calls to notify the module. But this handler function must not block or spend
1904 too much time processing the event notification.
1905 For this reason we provide a notification queue that controllers can register
1906 themselves with to receive cluster notifications.
1908 The example below represents a controller that implements a very simple live
1911 .. code-block:: python
1917 from ..tools import ApiController, BaseController, NotificationQueue
1920 @ApiController('livelog')
1921 class LiveLog(BaseController):
1922 log_buffer = collections.deque(maxlen=1000)
1925 super(LiveLog, self).__init__()
1926 NotificationQueue.register(self.log, 'clog')
1928 def log(self, log_struct):
1929 self.log_buffer.appendleft(log_struct)
1933 ret = '<html><meta http-equiv="refresh" content="2" /><body>'
1934 for l in self.log_buffer:
1935 ret += "{}<br>".format(l)
1936 ret += "</body></html>"
1939 As you can see above, the ``NotificationQueue`` class provides a register
1940 method that receives the function as its first argument, and receives the
1941 "notification type" as the second argument.
1942 You can omit the second argument of the ``register`` method, and in that case
1943 you are registering to listen all notifications of any type.
1945 Here is an list of notification types (these might change in the future) that
1948 * ``clog``: cluster log notifications
1949 * ``command``: notification when a command issued by ``MgrModule.send_command``
1951 * ``perf_schema_update``: perf counters schema update
1952 * ``mon_map``: monitor map update
1953 * ``fs_map``: cephfs map update
1954 * ``osd_map``: OSD map update
1955 * ``service_map``: services (RGW, RBD-Mirror, etc.) map update
1956 * ``mon_status``: monitor status regular update
1957 * ``health``: health status regular update
1958 * ``pg_summary``: regular update of PG status information
1961 How to write a unit test when a controller accesses a Ceph module?
1962 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1964 Consider the following example that implements a controller that retrieves the
1965 list of RBD images of the ``rbd`` pool:
1967 .. code-block:: python
1971 from ..tools import ApiController, RESTController
1974 @ApiController('rbdimages')
1975 class RbdImages(RESTController):
1977 self.ioctx = mgr.rados.open_ioctx('rbd')
1978 self.rbd = rbd.RBD()
1981 return [{'name': n} for n in self.rbd.list(self.ioctx)]
1983 In the example above, we want to mock the return value of the ``rbd.list``
1984 function, so that we can test the JSON response of the controller.
1986 The unit test code will look like the following:
1988 .. code-block:: python
1991 from .helper import ControllerTestCase
1994 class RbdImagesTest(ControllerTestCase):
1995 @mock.patch('rbd.RBD.list')
1996 def test_list(self, rbd_list_mock):
1997 rbd_list_mock.return_value = ['img1', 'img2']
1998 self._get('/api/rbdimages')
1999 self.assertJsonBody([{'name': 'img1'}, {'name': 'img2'}])
2003 How to add a new configuration setting?
2004 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2006 If you need to store some configuration setting for a new feature, we already
2007 provide an easy mechanism for you to specify/use the new config setting.
2009 For instance, if you want to add a new configuration setting to hold the
2010 email address of the dashboard admin, just add a setting name as a class
2011 attribute to the ``Options`` class in the ``settings.py`` file::
2014 class Options(object):
2017 ADMIN_EMAIL_ADDRESS = ('admin@admin.com', str)
2019 The value of the class attribute is a pair composed by the default value for that
2020 setting, and the python type of the value.
2022 By declaring the ``ADMIN_EMAIL_ADDRESS`` class attribute, when you restart the
2023 dashboard module, you will automatically gain two additional CLI commands to
2024 get and set that setting::
2026 $ ceph dashboard get-admin-email-address
2027 $ ceph dashboard set-admin-email-address <value>
2029 To access, or modify the config setting value from your Python code, either
2030 inside a controller or anywhere else, you just need to import the ``Settings``
2031 class and access it like this:
2033 .. code-block:: python
2035 from settings import Settings
2038 tmp_var = Settings.ADMIN_EMAIL_ADDRESS
2041 Settings.ADMIN_EMAIL_ADDRESS = 'myemail@admin.com'
2043 The settings management implementation will make sure that if you change a
2044 setting value from the Python code you will see that change when accessing
2045 that setting from the CLI and vice-versa.
2048 How to run a controller read-write operation asynchronously?
2049 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2051 Some controllers might need to execute operations that alter the state of the
2052 Ceph cluster. These operations might take some time to execute and to maintain
2053 a good user experience in the Web UI, we need to run those operations
2054 asynchronously and return immediately to frontend some information that the
2055 operations are running in the background.
2057 To help in the development of the above scenario we added the support for
2058 asynchronous tasks. To trigger the execution of an asynchronous task we must
2059 use the following class method of the ``TaskManager`` class::
2061 from ..tools import TaskManager
2063 TaskManager.run(name, metadata, func, args, kwargs)
2065 * ``name`` is a string that can be used to group tasks. For instance
2066 for RBD image creation tasks we could specify ``"rbd/create"`` as the
2067 name, or similarly ``"rbd/remove"`` for RBD image removal tasks.
2069 * ``metadata`` is a dictionary where we can store key-value pairs that
2070 characterize the task. For instance, when creating a task for creating
2071 RBD images we can specify the metadata argument as
2072 ``{'pool_name': "rbd", image_name': "test-img"}``.
2074 * ``func`` is the python function that implements the operation code, which
2075 will be executed asynchronously.
2077 * ``args`` and ``kwargs`` are the positional and named arguments that will be
2078 passed to ``func`` when the task manager starts its execution.
2080 The ``TaskManager.run`` method triggers the asynchronous execution of function
2081 ``func`` and returns a ``Task`` object.
2082 The ``Task`` provides the public method ``Task.wait(timeout)``, which can be
2083 used to wait for the task to complete up to a timeout defined in seconds and
2084 provided as an argument. If no argument is provided the ``wait`` method
2085 blocks until the task is finished.
2087 The ``Task.wait`` is very useful for tasks that usually are fast to execute but
2088 that sometimes may take a long time to run.
2089 The return value of the ``Task.wait`` method is a pair ``(state, value)``
2090 where ``state`` is a string with following possible values:
2092 * ``VALUE_DONE = "done"``
2093 * ``VALUE_EXECUTING = "executing"``
2095 The ``value`` will store the result of the execution of function ``func`` if
2096 ``state == VALUE_DONE``. If ``state == VALUE_EXECUTING`` then
2099 The pair ``(name, metadata)`` should unequivocally identify the task being
2100 run, which means that if you try to trigger a new task that matches the same
2101 ``(name, metadata)`` pair of the currently running task, then the new task
2102 is not created and you get the task object of the current running task.
2104 For instance, consider the following example:
2106 .. code-block:: python
2108 task1 = TaskManager.run("dummy/task", {'attr': 2}, func)
2109 task2 = TaskManager.run("dummy/task", {'attr': 2}, func)
2111 If the second call to ``TaskManager.run`` executes while the first task is
2112 still executing then it will return the same task object:
2113 ``assert task1 == task2``.
2116 How to get the list of executing and finished asynchronous tasks?
2117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2119 The list of executing and finished tasks is included in the ``Summary``
2120 controller, which is already polled every 5 seconds by the dashboard frontend.
2121 But we also provide a dedicated controller to get the same list of executing
2124 The ``Task`` controller exposes the ``/api/task`` endpoint that returns the
2125 list of executing and finished tasks. This endpoint accepts the ``name``
2126 parameter that accepts a glob expression as its value.
2127 For instance, an HTTP GET request of the URL ``/api/task?name=rbd/*``
2128 will return all executing and finished tasks which name starts with ``rbd/``.
2130 To prevent the finished tasks list from growing unbounded, we will always
2131 maintain the 10 most recent finished tasks, and the remaining older finished
2132 tasks will be removed when reaching a TTL of 1 minute. The TTL is calculated
2133 using the timestamp when the task finished its execution. After a minute, when
2134 the finished task information is retrieved, either by the summary controller or
2135 by the task controller, it is automatically deleted from the list and it will
2136 not be included in further task queries.
2138 Each executing task is represented by the following dictionary::
2141 'name': "name", # str
2142 'metadata': { }, # dict
2143 'begin_time': "2018-03-14T15:31:38.423605Z", # str (ISO 8601 format)
2144 'progress': 0 # int (percentage)
2147 Each finished task is represented by the following dictionary::
2150 'name': "name", # str
2151 'metadata': { }, # dict
2152 'begin_time': "2018-03-14T15:31:38.423605Z", # str (ISO 8601 format)
2153 'end_time': "2018-03-14T15:31:39.423605Z", # str (ISO 8601 format)
2154 'duration': 0.0, # float
2155 'progress': 0 # int (percentage)
2156 'success': True, # bool
2157 'ret_value': None, # object, populated only if 'success' == True
2158 'exception': None, # str, populated only if 'success' == False
2162 How to use asynchronous APIs with asynchronous tasks?
2163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2165 The ``TaskManager.run`` method as described in a previous section, is well
2166 suited for calling blocking functions, as it runs the function inside a newly
2167 created thread. But sometimes we want to call some function of an API that is
2168 already asynchronous by nature.
2170 For these cases we want to avoid creating a new thread for just running a
2171 non-blocking function, and want to leverage the asynchronous nature of the
2172 function. The ``TaskManager.run`` is already prepared to be used with
2173 non-blocking functions by passing an object of the type ``TaskExecutor`` as an
2174 additional parameter called ``executor``. The full method signature of
2175 ``TaskManager.run``::
2177 TaskManager.run(name, metadata, func, args=None, kwargs=None, executor=None)
2180 The ``TaskExecutor`` class is responsible for code that executes a given task
2181 function, and defines three methods that can be overridden by
2184 def init(self, task)
2186 def finish(self, ret_value, exception)
2188 The ``init`` method is called before the running the task function, and
2189 receives the task object (of class ``Task``).
2191 The ``start`` method runs the task function. The default implementation is to
2192 run the task function in the current thread context.
2194 The ``finish`` method should be called when the task function finishes with
2195 either the ``ret_value`` populated with the result of the execution, or with
2196 an exception object in the case that execution raised an exception.
2198 To leverage the asynchronous nature of a non-blocking function, the developer
2199 should implement a custom executor by creating a subclass of the
2200 ``TaskExecutor`` class, and provide an instance of the custom executor class
2201 as the ``executor`` parameter of the ``TaskManager.run``.
2203 To better understand the expressive power of executors, we write a full example
2204 of use a custom executor to execute the ``MgrModule.send_command`` asynchronous
2207 .. code-block:: python
2210 from mgr_module import CommandResult
2212 from ..tools import ApiController, RESTController, NotificationQueue, \
2213 TaskManager, TaskExecutor
2216 class SendCommandExecutor(TaskExecutor):
2218 super(SendCommandExecutor, self).__init__()
2222 def init(self, task):
2223 super(SendCommandExecutor, self).init(task)
2225 # we need to listen for 'command' events to know when the command
2227 NotificationQueue.register(self._handler, 'command')
2229 # store the CommandResult object to retrieve the results
2230 self.result = self.task.fn_args[0]
2231 if len(self.task.fn_args) > 4:
2232 # the user specified a tag for the command, so let's use it
2233 self.tag = self.task.fn_args[4]
2235 # let's generate a unique tag for the command
2236 self.tag = 'send_command_{}'.format(id(self))
2237 self.task.fn_args.append(self.tag)
2239 def _handler(self, data):
2240 if data == self.tag:
2241 # the command has finished, notifying the task with the result
2242 self.finish(self.result.wait(), None)
2243 # deregister listener to avoid memory leaks
2244 NotificationQueue.deregister(self._handler, 'command')
2247 @ApiController('test')
2248 class Test(RESTController):
2250 def _run_task(self, osd_id):
2251 task = TaskManager.run("test/task", {}, mgr.send_command,
2252 [CommandResult(''), 'osd', osd_id,
2253 json.dumps({'prefix': 'perf histogram dump'})],
2254 executor=SendCommandExecutor())
2255 return task.wait(1.0)
2257 def get(self, osd_id):
2258 status, value = self._run_task(osd_id)
2259 return {'status': status, 'value': value}
2262 The above ``SendCommandExecutor`` executor class can be used for any call to
2263 ``MgrModule.send_command``. This means that we should need just one custom
2264 executor class implementation for each non-blocking API that we use in our
2267 The default executor, used when no executor object is passed to
2268 ``TaskManager.run``, is the ``ThreadedExecutor``. You can check its
2269 implementation in the ``tools.py`` file.
2272 How to update the execution progress of an asynchronous task?
2273 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2275 The asynchronous tasks infrastructure provides support for updating the
2276 execution progress of an executing task.
2277 The progress can be updated from within the code the task is executing, which
2278 usually is the place where we have the progress information available.
2280 To update the progress from within the task code, the ``TaskManager`` class
2281 provides a method to retrieve the current task object::
2283 TaskManager.current_task()
2285 The above method is only available when using the default executor
2286 ``ThreadedExecutor`` for executing the task.
2287 The ``current_task()`` method returns the current ``Task`` object. The
2288 ``Task`` object provides two public methods to update the execution progress
2289 value: the ``set_progress(percentage)``, and the ``inc_progress(delta)``
2292 The ``set_progress`` method receives as argument an integer value representing
2293 the absolute percentage that we want to set to the task.
2295 The ``inc_progress`` method receives as argument an integer value representing
2296 the delta we want to increment to the current execution progress percentage.
2298 Take the following example of a controller that triggers a new task and
2299 updates its progress:
2301 .. code-block:: python
2306 from ..tools import TaskManager, ApiController, BaseController
2309 @ApiController('dummy_task')
2310 class DummyTask(BaseController):
2312 top = random.randrange(100)
2313 for i in range(top):
2314 TaskManager.current_task().set_progress(i*100/top)
2315 # or TaskManager.current_task().inc_progress(100/top)
2320 @cherrypy.tools.json_out()
2322 task = TaskManager.run("dummy/task", {}, self._dummy)
2323 return task.wait(5) # wait for five seconds
2326 How to deal with asynchronous tasks in the front-end?
2327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2329 All executing and most recently finished asynchronous tasks are displayed on
2330 "Background-Tasks" and if finished on "Recent-Notifications" in the menu bar.
2331 For each task a operation name for three states (running, success and failure),
2332 a function that tells who is involved and error descriptions, if any, have to
2333 be provided. This can be achieved by appending
2334 ``TaskManagerMessageService.messages``. This has to be done to achieve
2335 consistency among all tasks and states.
2338 Ensures consistency among all tasks. It consists of three verbs for each
2339 different state f.e.
2340 ``{running: 'Creating', failure: 'create', success: 'Created'}``.
2342 #. Put running operations in present participle f.e. ``'Updating'``.
2343 #. Failed messages always start with ``'Failed to '`` and should be continued
2344 with the operation in present tense f.e. ``'update'``.
2345 #. Put successful operations in past tense f.e. ``'Updated'``.
2348 Ensures consistency among all messages of a task, it resembles who's
2349 involved by the operation. It's a function that returns a string which
2350 takes the metadata from the task to return f.e.
2351 ``"RBD 'somePool/someImage'"``.
2353 Both combined create the following messages:
2355 * Failure => ``"Failed to create RBD 'somePool/someImage'"``
2356 * Running => ``"Creating RBD 'somePool/someImage'"``
2357 * Success => ``"Created RBD 'somePool/someImage'"``
2359 For automatic task handling use ``TaskWrapperService.wrapTaskAroundCall``.
2361 If for some reason ``wrapTaskAroundCall`` is not working for you,
2362 you have to subscribe to your asynchronous task manually through
2363 ``TaskManagerService.subscribe``, and provide it with a callback,
2364 in case of a success to notify the user. A notification can
2365 be triggered with ``NotificationService.notifyTask``. It will use
2366 ``TaskManagerMessageService.messages`` to display a message based on the state
2369 Notifications of API errors are handled by ``ApiInterceptorService``.
2373 .. code-block:: javascript
2375 export class TaskManagerMessageService {
2378 // Messages for task 'rbd/create'
2379 'rbd/create': new TaskManagerMessage(
2381 ['create', 'Creating', 'Created'],
2383 (metadata) => `RBD '${metadata.pool_name}/${metadata.image_name}'`,
2385 // Error code and description
2386 '17': `Name is already used by RBD '${metadata.pool_name}/${
2387 metadata.image_name}'.`
2395 export class RBDFormComponent {
2398 const request = this.createRequest();
2399 // Subscribes to 'call' with submitted 'task' and handles notifications
2400 return this.taskWrapper.wrapTaskAroundCall({
2401 task: new FinishedTask('rbd/create', {
2402 pool_name: request.pool_name,
2403 image_name: request.name
2405 call: this.rbdService.create(request)
2412 REST API documentation
2413 ~~~~~~~~~~~~~~~~~~~~~~
2414 Ceph-Dashboard provides two types of documentation for the **Ceph RESTful API**:
2416 * **Static documentation**: available at :ref:`mgr ceph api`. This comes from a versioned specification located at ``src/pybind/mgr/dashboard/openapi.yaml``.
2417 * **Interactive documentation**: available from a running Ceph-Dashboard instance (top-right ``?`` icon > API Docs).
2419 If changes are made to the ``controllers/`` directory, it's very likely that
2420 they will result in changes to the generated OpenAPI specification. For that
2421 reason, a checker has been implemented to block unintended changes. This check
2422 is automatically triggered by the Pull Request CI (``make check``) and can be
2423 also manually invoked: ``tox -e openapi-check``.
2425 If that checker failed, it means that the current Pull Request is modifying the
2426 Ceph API and therefore:
2428 #. The versioned OpenAPI specification should be updated explicitly: ``tox -e openapi-fix``.
2429 #. The team @ceph/api will be requested for reviews (this is automated via Github CODEOWNERS), in order to asses the impact of changes.
2431 Additionally, Sphinx documentation can be generated from the OpenAPI
2432 specification with ``tox -e openapi-doc``.
2434 The Ceph RESTful OpenAPI specification is dynamically generated from the
2435 ``Controllers`` in ``controllers/`` directory. However, by default it is not
2436 very detailed, so there are two decorators that can and should be used to add
2439 * ``@EndpointDoc()`` for documentation of endpoints. It has four optional arguments
2440 (explained below): ``description``, ``group``, ``parameters`` and
2442 * ``@ControllerDoc()`` for documentation of controller or group associated with
2443 the endpoints. It only takes the two first arguments: ``description`` and
2447 ``description``: A a string with a short (1-2 sentences) description of the object.
2450 ``group``: By default, an endpoint is grouped together with other endpoints
2451 within the same controller class. ``group`` is a string that can be used to
2452 assign an endpoint or all endpoints in a class to another controller or a
2453 conceived group name.
2456 ``parameters``: A dict used to describe path, query or request body parameters.
2457 By default, all parameters for an endpoint are listed on the Swagger UI page,
2458 including information of whether the parameter is optional/required and default
2459 values. However, there will be no description of the parameter and the parameter
2460 type will only be displayed in some cases.
2461 When adding information, each parameters should be described as in the example
2462 below. Note that the parameter type should be expressed as a built-in python
2463 type and not as a string. Allowed values are ``str``, ``int``, ``bool``, ``float``.
2465 .. code-block:: python
2467 @EndpointDoc(parameters={'my_string': (str, 'Description of my_string')})
2468 def method(my_string): pass
2470 For body parameters, more complex cases are possible. If the parameter is a
2471 dictionary, the type should be replaced with a ``dict`` containing its nested
2472 parameters. When describing nested parameters, the same format as other
2473 parameters is used. However, all nested parameters are set as required by default.
2474 If the nested parameter is optional this must be specified as for ``item2`` in
2475 the example below. If a nested parameters is set to optional, it is also
2476 possible to specify the default value (this will not be provided automatically
2477 for nested parameters).
2479 .. code-block:: python
2481 @EndpointDoc(parameters={
2483 'item1': (str, 'Description of item1'),
2484 'item2': (str, 'Description of item2', True), # item2 is optional
2485 'item3': (str, 'Description of item3', True, 'foo'), # item3 is optional with 'foo' as default value
2486 }, 'Description of my_dictionary')})
2487 def method(my_dictionary): pass
2489 If the parameter is a ``list`` of primitive types, the type should be
2490 surrounded with square brackets.
2492 .. code-block:: python
2494 @EndpointDoc(parameters={'my_list': ([int], 'Description of my_list')})
2495 def method(my_list): pass
2497 If the parameter is a ``list`` with nested parameters, the nested parameters
2498 should be placed in a dictionary and surrounded with square brackets.
2500 .. code-block:: python
2502 @EndpointDoc(parameters={
2504 'list_item': (str, 'Description of list_item'),
2505 'list_item2': (str, 'Description of list_item2')
2506 }], 'Description of my_list')})
2507 def method(my_list): pass
2510 ``responses``: A dict used for describing responses. Rules for describing
2511 responses are the same as for request body parameters, with one difference:
2512 responses also needs to be assigned to the related response code as in the
2515 .. code-block:: python
2517 @EndpointDoc(responses={
2518 '400':{'my_response': (str, 'Description of my_response')}})
2522 Error Handling in Python
2523 ~~~~~~~~~~~~~~~~~~~~~~~~
2525 Good error handling is a key requirement in creating a good user experience
2526 and providing a good API.
2528 Dashboard code should not duplicate C++ code. Thus, if error handling in C++
2529 is sufficient to provide good feedback, a new wrapper to catch these errors
2530 is not necessary. On the other hand, input validation is the best place to
2531 catch errors and generate the best error messages. If required, generate
2532 errors as soon as possible.
2534 The backend provides few standard ways of returning errors.
2536 First, there is a generic Internal Server Error::
2540 "version": <cherrypy version, e.g. 13.1.0>,
2541 "detail": "The server encountered an unexpected condition which prevented it from fulfilling the request.",
2545 For errors generated by the backend, we provide a standard error
2550 "detail": str(e), # E.g. "[errno -42] <some error message>"
2551 "component": "rbd", # this can be null to represent a global error code
2552 "code": "3", # Or a error name, e.g. "code": "some_error_key"
2556 In case, the API Endpoints uses @ViewCache to temporarily cache results,
2557 the error looks like so::
2561 "detail": str(e), # E.g. "[errno -42] <some error message>"
2562 "component": "rbd", # this can be null to represent a global error code
2563 "code": "3", # Or a error name, e.g. "code": "some_error_key"
2564 'status': 3, # Indicating the @ViewCache error status
2567 In case, the API Endpoints uses a task the error looks like so::
2571 "detail": str(e), # E.g. "[errno -42] <some error message>"
2572 "component": "rbd", # this can be null to represent a global error code
2573 "code": "3", # Or a error name, e.g. "code": "some_error_key"
2574 "task": { # Information about the task itself
2581 Our WebUI should show errors generated by the API to the user. Especially
2582 field-related errors in wizards and dialogs or show non-intrusive notifications.
2584 Handling exceptions in Python should be an exception. In general, we
2585 should have few exception handlers in our project. Per default, propagate
2586 errors to the API, as it will take care of all exceptions anyway. In general,
2587 log the exception by adding ``logger.exception()`` with a description to the
2590 We need to distinguish between user errors from internal errors and
2591 programming errors. Using different exception types will ease the
2592 task for the API layer and for the user interface:
2594 Standard Python errors, like ``SystemError``, ``ValueError`` or ``KeyError``
2595 will end up as internal server errors in the API.
2597 In general, do not ``return`` error responses in the REST API. They will be
2598 returned by the error handler. Instead, raise the appropriate exception.
2603 New functionality can be provided by means of a plug-in architecture. Among the
2604 benefits this approach brings in, loosely coupled development is one of the most
2605 notable. As the Ceph Dashboard grows in feature richness, its code-base becomes
2606 more and more complex. The hook-based nature of a plug-in architecture allows to
2607 extend functionality in a controlled manner, and isolate the scope of the
2610 Ceph Dashboard relies on `Pluggy <https://pluggy.readthedocs.io>`_ to provide
2611 for plug-ing support. On top of pluggy, an interface-based approach has been
2612 implemented, with some safety checks (method override and abstract method
2615 In order to create a new plugin, the following steps are required:
2617 #. Add a new file under ``src/pybind/mgr/dashboard/plugins``.
2618 #. Import the ``PLUGIN_MANAGER`` instance and the ``Interfaces``.
2619 #. Create a class extending the desired interfaces. The plug-in library will
2620 check if all the methods of the interfaces have been properly overridden.
2621 #. Register the plugin in the ``PLUGIN_MANAGER`` instance.
2622 #. Import the plug-in from within the Ceph Dashboard ``module.py`` (currently no
2623 dynamic loading is implemented).
2625 The available Mixins (helpers) are:
2627 - ``CanMgr``: provides the plug-in with access to the ``mgr`` instance under ``self.mgr``.
2629 The available Interfaces are:
2631 - ``Initializable``: requires overriding ``init()`` hook. This method is run at
2632 the very beginning of the dashboard module, right after all imports have been
2634 - ``Setupable``: requires overriding ``setup()`` hook. This method is run in the
2635 Ceph Dashboard ``serve()`` method, right after CherryPy has been configured,
2636 but before it is started. It's a placeholder for the plug-in initialization
2638 - ``HasOptions``: requires overriding ``get_options()`` hook by returning a list
2639 of ``Options()``. The options returned here are added to the
2641 - ``HasCommands``: requires overriding ``register_commands()`` hook by defining
2642 the commands the plug-in can handle and decorating them with ``@CLICommand``.
2643 The commands can be optionally returned, so that they can be invoked
2644 externally (which makes unit testing easier).
2645 - ``HasControllers``: requires overriding ``get_controllers()`` hook by defining
2646 and returning the controllers as usual.
2647 - ``FilterRequest.BeforeHandler``: requires overriding
2648 ``filter_request_before_handler()`` hook. This method receives a
2649 ``cherrypy.request`` object for processing. A usual implementation of this
2650 method will allow some requests to pass or will raise a ``cherrypy.HTTPError``
2651 based on the ``request`` metadata and other conditions.
2653 New interfaces and hooks should be added as soon as they are required to
2654 implement new functionality. The above list only comprises the hooks needed for
2655 the existing plugins.
2657 A sample plugin implementation would look like this:
2659 .. code-block:: python
2661 # src/pybind/mgr/dashboard/plugins/mute.py
2663 from . import PLUGIN_MANAGER as PM
2664 from . import interfaces as I
2666 from mgr_module import CLICommand, Option
2670 class Mute(I.CanMgr, I.Setupable, I.HasOptions, I.HasCommands,
2671 I.FilterRequest.BeforeHandler, I.HasControllers):
2673 def get_options(self):
2674 return [Option('mute', default=False, type='bool')]
2678 self.mute = self.mgr.get_module_option('mute')
2681 def register_commands(self):
2682 @CLICommand("dashboard mute")
2685 self.mgr.set_module_option('mute', True)
2689 def filter_request_before_handler(self, request):
2691 raise cherrypy.HTTPError(500, "I'm muted :-x")
2694 def get_controllers(self):
2695 from ..controllers import ApiController, RESTController
2697 @ApiController('/mute')
2698 class MuteController(RESTController):
2702 return [MuteController]
2705 Additionally, a helper for creating plugins ``SimplePlugin`` is provided. It
2706 facilitates the basic tasks (Options, Commands, and common Mixins). The previous
2707 plugin could be rewritten like this:
2709 .. code-block:: python
2711 from . import PLUGIN_MANAGER as PM
2712 from . import interfaces as I
2713 from .plugin import SimplePlugin as SP
2718 class Mute(SP, I.Setupable, I.FilterRequest.BeforeHandler, I.HasControllers):
2720 SP.Option('mute', default=False, type='bool')
2724 self.set_option('mute', True)
2729 SP.Command("dashboard mute", handler=shut_up)
2734 self.mute = self.get_option('mute')
2737 def filter_request_before_handler(self, request):
2739 raise cherrypy.HTTPError(500, "I'm muted :-x")
2742 def get_controllers(self):
2743 from ..controllers import ApiController, RESTController
2745 @ApiController('/mute')
2746 class MuteController(RESTController):
2750 return [MuteController]