From: John Spray <john.spray@redhat.com>
Date: Wed, 1 Nov 2017 10:28:30 +0000 (-0400)
Subject: doc: describe how to implement standby modules
X-Git-Tag: v13.0.1~332^2~2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=ceb2a91190441b19171e5b5726748e43ee4d1e92;p=ceph.git

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 f939141a50e0..53844ba24ed2 100644
--- 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 465f2cc0db22..654c50537bc7 100644
--- 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
 -------