Describe vshard router master discovery (#2848)

Resolves #2268 

* Add description of the `master` parameter and the `master_search_wakeup()` function

Co-authored-by: Patience Daur <[email protected]>

Author: veod32

doc/reference/reference_rock/vshard/vshard_ref.rst

@@ -21,6 +21,7 @@ Basic parameters
 * :ref:`rebalancer_max_receiving <cfg_basic-rebalancer_max_receiving>`
 * :ref:`rebalancer_max_sending <cfg_basic-rebalancer_max_sending>`
 * :ref:`discovery_mode <cfg_basic-discovery_mode>`
+* :ref:`master <cfg_basic-master>`
 
 .. _cfg_basic-sharding:
 
@@ -174,6 +175,73 @@ Basic parameters
     | Default: 'on'
     | Dynamic: yes
 
+..  _cfg_basic-master:
+
+..  confval:: master
+
+    Turns on automated master discovery in a replica set if set to ``auto``.
+    Applicable only to the configuration of a router; the storage configuration ignores this parameter.
+
+    The parameter should be specified per replica set and is not compatible with manual master selection.
+
+    **Examples**
+
+    Correct configuration:
+
+    ..  code-block:: kconfig
+        :emphasize-lines: 4
+
+        config = {
+            sharding = {
+                <replicaset uuid> = {
+                    master = 'auto',
+                    replicas = {...},
+                },
+                ...
+            },
+            ...
+        }
+
+    Incorrect configuration:
+
+    ..  code-block:: kconfig
+        :emphasize-lines: 4, 7, 11
+
+        config = {
+            sharding = {
+                <replicaset uuid> = {
+                    master = 'auto',
+                    replicas = {
+                        <replica uuid1> = {
+                            master = true,
+                            ...
+                        },
+                        <replica uuid2> = {
+                            master = false,
+                            ...
+                        },
+                    },
+                },
+                ...
+            },
+            ...
+        }
+
+    If configuration is incorrect configuration, it is not applied, and the ``vshard.router.cfg()`` call throws an error.
+
+
+    If the ``master`` parameter is set to ``auto`` for some replica sets, the router goes to these replica sets, discovers the master in each of them, and periodically checks if the master instance still has its master status.
+    When the master in the replica set stops being a master, the router goes around all the nodes of the replica set and finds out which one is the new master.
+
+    Without this setting, the router cannot detect master nodes in the configured replica sets on its own.
+    It relies only on how they are specified in the configuration.
+    This becomes a problem when the master changes and the change is not delivered to the router's configuration:
+    for instance, in case the router doesn't rely on a central configuration provider
+    or the provider cannot deliver a new configuration due to some reason.
+
+    | Type: string
+    | Default: ``nil``
+    | Dynamic: yes
 
 .. _vshard-config-replica-set-funcs:
 

doc/reference/reference_rock/vshard/vshard_router.rst

@@ -895,6 +895,21 @@ Router public API
             * result of ``function_name`` on success
             * nil, err otherwise
 
+..  _router_api-master-search-wakeup:
+
+..  function:: vshard.router.master_search_wakeup()
+
+    :ref:`Automated master discovery <cfg_basic-master>` works in its own fiber on a router,
+    which is activated only if at least one replica set is configured to look for the master (the ``master`` parameter is set to ``auto``).
+    The fiber wakes up within a certain period. But it is possible to wake it up on demand by using this function.
+
+    Manual fiber wakeup can help speed up tests for master change.
+    Another use case is performing some actions with a router in the router console.
+
+    The function does nothing if master search is not :ref:`configured <cfg_basic-master>` for any replica set.
+
+    :return: none
+
 ..  _vshard_api_reference-router_internal_api:
 
 Router internal API