doc: describe how to implement standby modules

Signed-off-by: John Spray <john.spray@redhat.com>
(cherry picked from commit ceb2a91190441b19171e5b5726748e43ee4d1e92)

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 b5a13cc3eada1b9ef4964b880a2c1cae706ad229..a75c14c849463c5213f2afdec1b7d2e1d3d3cbad 100644 (file)
--- a/doc/mgr/plugins.rst
+++ b/doc/mgr/plugins.rst
@@ -157,6 +157,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
 -------