doc: describe how to implement standby modules

Signed-off-by: John Spray <john.spray@redhat.com>

diff --git a/doc/mgr/index.rst b/doc/mgr/index.rst
index f939141a50e017c6c15a061ec04154f675f439d0..53844ba24ed2c2e1ae265f7315f7734fe4af9c22 100644 (file)
--- a/doc/mgr/index.rst
+++ b/doc/mgr/index.rst
@@ -26,11 +26,11 @@ sensible.
     :maxdepth: 1
 
     Installation and Configuration <administrator>
+    Writing plugins <plugins>
     Dashboard plugin <dashboard>
     Local pool plugin <localpool>
     RESTful plugin <restful>
     Zabbix plugin <zabbix>
     Prometheus plugin <prometheus>
-    Writing plugins <plugins>
     Influx plugin <influx>
 

diff --git a/doc/mgr/plugins.rst b/doc/mgr/plugins.rst
index 465f2cc0db221b48c6facac24483367eaf055a5b..654c50537bc7f8dde97a9011dae67d9b2e495973 100644 (file)
--- a/doc/mgr/plugins.rst
+++ b/doc/mgr/plugins.rst
@@ -160,6 +160,31 @@ a command completes, the ``notify()`` callback on the MgrModule
 instance is triggered, with notify_type set to "command", and
 notify_id set to the tag of the command.
 
+Implementing standby mode
+-------------------------
+
+For some modules, it is useful to run on standby manager daemons as well
+as on the active daemon.  For example, an HTTP server can usefully
+serve HTTP redirect responses from the standby managers so that
+the user can point his browser at any of the manager daemons without
+having to worry about which one is active.
+
+Standby manager daemons look for a class called ``StandbyModule``
+in each module.  If the class is not found then the module is not
+used at all on standby daemons.  If the class is found, then
+its ``serve`` method is called.  Implementations of ``StandbyModule``
+must inherit from ``mgr_module.MgrStandbyModule``.
+
+The interface of ``MgrStandbyModule`` is much restricted compared to
+``MgrModule`` -- none of the Ceph cluster state is available to
+the module.  ``serve`` and ``shutdown`` methods are used in the same
+way as a normal module class.  The ``get_active_uri`` method enables
+the standby module to discover the address of its active peer in
+order to make redirects.  See the ``MgrStandbyModule`` definition
+in the Ceph source code for the full list of methods.
+
+For an example of how to use this interface, look at the source code
+of the ``dashboard`` module.
 
 Logging
 -------