From 4fddb181dee81e62fb63359804a8fde117c75e04 Mon Sep 17 00:00:00 2001 From: John Spray Date: Tue, 3 Jul 2018 13:11:53 +0100 Subject: [PATCH] doc/mgr: add docs for missing functions Some functions had docstrings but were not linked into plugins.rst, some needed more text added. Signed-off-by: John Spray --- doc/mgr/plugins.rst | 58 +++++++++++++++++++++++++++++++++++- src/pybind/mgr/mgr_module.py | 15 ++++++++-- 2 files changed, 69 insertions(+), 4 deletions(-) diff --git a/doc/mgr/plugins.rst b/doc/mgr/plugins.rst index 8e67819e010d6..bc8b5d69b1713 100644 --- a/doc/mgr/plugins.rst +++ b/doc/mgr/plugins.rst @@ -71,6 +71,13 @@ EPERM, or 0 for no error), ``stdout`` is a string containing any non-error output, and ``stderr`` is a string containing any progress or error explanation output. Either or both of the two strings may be empty. +Implement the ``handle_command`` function to respond to the commands +when they are sent: + + +.. py:currentmodule:: mgr_module +.. automethod:: MgrModule.handle_command + Configuration options --------------------- @@ -125,7 +132,6 @@ Hints for using config options: * To delete a config value (i.e. revert to default), just pass ``None`` to set_config. -.. py:currentmodule:: mgr_module .. automethod:: MgrModule.get_config .. automethod:: MgrModule.set_config .. automethod:: MgrModule.get_localized_config @@ -187,7 +193,23 @@ function. This will result in a circular locking exception. .. automethod:: MgrModule.get_server .. automethod:: MgrModule.list_servers .. automethod:: MgrModule.get_metadata +.. automethod:: MgrModule.get_daemon_status +.. automethod:: MgrModule.get_perf_schema .. automethod:: MgrModule.get_counter +.. automethod:: MgrModule.get_mgr_id + +Exposing health checks +---------------------- + +Modules can raise first class Ceph health checks, which will be reported +in the output of ``ceph status`` and in other places that report on the +cluster's health. + +If you use ``set_health_checks`` to report a problem, be sure to call +it again with an empty dict to clear your health check when the problem +goes away. + +.. automethod:: MgrModule.set_health_checks What if the mons are down? -------------------------- @@ -227,6 +249,40 @@ to the cluster. .. automethod:: MgrModule.send_command +Receiving notifications +----------------------- + +The manager daemon calls the ``notify`` function on all active modules +when certain important pieces of cluster state are updated, such as the +cluster maps. + +The actual data is not passed into this function, rather it is a cue for +the module to go and read the relevant structure if it is interested. Most +modules ignore most types of notification: to ignore a notification +simply return from this function without doing anything. + +.. automethod:: MgrModule.notify + +Accessing RADOS or CephFS +------------------------- + +If you want to use the librados python API to access data stored in +the Ceph cluster, you can access the ``rados`` attribute of your +``MgrModule`` instance. This is an instance of ``rados.Rados`` which +has been constructed for you using the existing Ceph context (an internal +detail of the C++ Ceph code) of the mgr daemon. + +Always use this specially constructed librados instance instead of +constructing one by hand. + +Similarly, if you are using libcephfs to access the filesystem, then +use the libcephfs ``create_with_rados`` to construct it from the +``MgrModule.rados`` librados instance, and thereby inherit the correct context. + +Remember that your module may be running while other parts of the cluster +are down: do not assume that librados or libcephfs calls will return +promptly -- consider whether to use timeouts or to block if the rest of +the cluster is not fully available. Implementing standby mode ------------------------- diff --git a/src/pybind/mgr/mgr_module.py b/src/pybind/mgr/mgr_module.py index c6ac24ce52d95..2c27ee2a93911 100644 --- a/src/pybind/mgr/mgr_module.py +++ b/src/pybind/mgr/mgr_module.py @@ -282,6 +282,14 @@ class MgrModule(ceph_module.BaseMgrModule): """ Called by the ceph-mgr service to notify the Python plugin that new state is available. + + :param notify_type: string indicating what kind of notification, + such as osd_map, mon_map, fs_map, mon_status, + health, pg_summary, command, service_map + :param notify_id: string (may be empty) that optionally specifies + which entity is being notified about. With + "command" notifications this is set to the tag + ``from send_command``. """ pass @@ -502,11 +510,11 @@ class MgrModule(ceph_module.BaseMgrModule): def set_health_checks(self, checks): """ - Set module's health checks - Set the module's current map of health checks. Argument is a dict of check names to info, in this form: + :: + { 'CHECK_FOO': { 'severity': 'warning', # or 'error' @@ -545,7 +553,8 @@ class MgrModule(ceph_module.BaseMgrModule): def get_mgr_id(self): """ - Retrieve the mgr id. + Retrieve the name of the manager daemon where this plugin + is currently being executed (i.e. the active manager). :return: str """ -- 2.39.5