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: v12.2.2~61^2~5
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=a46c5733881403f65872ca36d300ab6a4ca9d2cc;p=ceph.git

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 f939141a50e..53844ba24ed 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 b5a13cc3ead..a75c14c8494 100644
--- 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
 -------