Skip to content

Describe vshard router master discovery #2848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 25, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions doc/reference/reference_rock/vshard/vshard_ref.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down
15 changes: 15 additions & 0 deletions doc/reference/reference_rock/vshard/vshard_router.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down