Supervised failover (#4265)

Author: andreyaksenov

doc/book/admin/start_stop_instance.rst

@@ -21,16 +21,12 @@ To get more context on how the application's environment might look, refer to :r
 
 
 .. _configuration_run_instance:
+.. _configuration_run_instance_tt:
 
 Starting Tarantool instances
 ----------------------------
 
-.. _configuration_run_instance_tt:
-
-Starting instances using the tt utility
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The :ref:`tt <tt-cli>` utility is the recommended way to start Tarantool instances.
+To start Tarantool instances use the :ref:`tt start <tt-start>` command:
 
 .. code-block:: console
 
@@ -56,24 +52,6 @@ In the system launch mode, artifacts are created in these locations:
 *   ``/var/run/tarantool/<instance_name>/``
 
 
-.. _configuration_run_instance_tarantool:
-
-Starting an instance using the tarantool command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``tarantool`` command provides additional :ref:`options <configuration_command_options>` that might be helpful for development purposes.
-Below is the syntax for starting a Tarantool instance configured in a file:
-
-..  code-block:: console
-
-    $ tarantool [OPTION ...] --name INSTANCE_NAME --config CONFIG_FILE_PATH
-
-The command below starts ``router-a-001`` configured in the ``config.yaml`` file:
-
-.. code-block:: console
-
-    $ tarantool --name router-a-001 --config config.yaml
-
 
 
 .. _admin-start_stop_instance_management:
@@ -252,138 +230,3 @@ by semicolons:
 
 If an error happens during the execution of the preload script or module, Tarantool
 reports the problem and exits.
-
-
-
-
-.. _configuration_command_options:
-
-tarantool command-line options
-------------------------------
-
-Options that can be passed when :ref:`starting a Tarantool instance <configuration_run_instance_tarantool>`:
-
-..  option:: -h, --help
-
-    Print an annotated list of all available options and exit.
-
-..  option:: --help-env-list
-
-    **Since:** :doc:`3.0.0 </release/3.0.0>`.
-
-    Show a list of :ref:`environment variables <configuration_environment_variable>` that can be used to configure Tarantool.
-
-.. _index-tarantool_version:
-
-..  option:: -v, -V, --version
-
-    Print the product name and version.
-
-    **Example**
-
-    ..  code-block:: console
-
-        $ tarantool --version
-        Tarantool Enterprise 3.0.0-beta1-2-gcbb569b4c-r607-gc64
-        Target: Linux-x86_64-RelWithDebInfo
-        ...
-
-    In this example:
-
-    *   ``3.0.0`` is a Tarantool version.
-        Tarantool follows semantic versioning, which is described in the :ref:`Tarantool release policy <release-policy>` section.
-
-    *   ``Target`` is the platform Tarantool is built on.
-        Platform-specific details may follow this line.
-
-
-..  option:: -c, --config PATH
-
-    **Since:** :doc:`3.0.0 </release/3.0.0>`.
-
-    Set a path to a :ref:`YAML configuration file <configuration_file>`.
-    You can also configure this value using the ``TT_CONFIG`` environment variable.
-
-    See also: :ref:`Starting an instance using the tarantool command <configuration_run_instance_tarantool>`
-
-..  option:: -n, --name INSTANCE
-
-    **Since:** :doc:`3.0.0 </release/3.0.0>`.
-
-    Set the name of an instance to run.
-    You can also configure this value using the ``TT_INSTANCE_NAME`` environment variable.
-
-    See also: :ref:`Starting an instance using the tarantool command <configuration_run_instance_tarantool>`
-
-
-..  option:: -i
-
-    Enter an :ref:`interactive mode <interactive_console>`.
-
-    **Example**
-
-    ..  code-block:: console
-
-        $ tarantool -i
-
-
-..  option:: -e EXPR
-
-    Execute the 'EXPR' string. See also: `lua man page <https://www.lua.org/manual/5.3/lua.html>`_.
-
-    **Example**
-
-    ..  code-block:: console
-
-        $ tarantool -e 'print("Hello, world!")'
-        Hello, world!
-
-..  option:: -l NAME
-
-    Require the 'NAME' library. See also: `lua man page <https://www.lua.org/manual/5.3/lua.html>`_.
-
-    **Example**
-
-    ..  code-block:: console
-
-        $ tarantool -l luatest.coverage script.lua
-
-..  option:: -j cmd
-
-    Perform a LuaJIT control command. See also: `Command Line Options <https://luajit.org/running.html>`_.
-
-    **Example**
-
-    ..  code-block:: console
-
-        $ tarantool -j off app.lua
-
-..  option:: -b ...
-
-    Save or list bytecode. See also: `Command Line Options <https://luajit.org/running.html>`_.
-
-    **Example**
-
-    ..  code-block:: console
-
-        $ tarantool -b test.lua test.out
-
-..  option:: -d SCRIPT
-
-    Activate a debugging session for 'SCRIPT'. See also: `luadebug.lua <https://github.com/tarantool/tarantool/blob/master/third_party/lua/README-luadebug.md>`_.
-
-    **Example**
-
-    ..  code-block:: console
-
-        $ tarantool -d app.lua
-
-
-..  option:: --
-
-    Stop handling options. See also: `lua man page <https://www.lua.org/manual/5.3/lua.html>`_.
-
-
-..  option:: -
-
-    Stop handling options and execute the standard input as a file. See also: `lua man page <https://www.lua.org/manual/5.3/lua.html>`_.

doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/README.md

@@ -0,0 +1,31 @@
+# Master-replica: supervised failover
+
+A sample application demonstrating how to bootstrap a replica set that uses an [external failover coordinator](https://www.tarantool.io/doc/latest/concepts/replication/supervised_failover/).
+The failover coordinator's state is stored in etcd along with a replica set configuration.
+
+
+## Running
+
+1. Start etcd:
+
+   ```console
+   $ etcd
+   ```
+   
+2. Publish a replica set configuration to etcd by executing the `tt cluster publish` command in the [replication](../../../replication) directory:
+
+   ```console
+   $ tt cluster publish "http://localhost:2379/myapp" instances.enabled/supervised_failover/source.yaml
+   ```
+   
+3. To start the failover coordinator, execute the `tarantool` command with the `--failover` option:
+
+   ```console
+   $ tarantool --failover --config instances.enabled/supervised_failover/config.yaml
+   ```
+
+4. Then, start the application as follows:
+
+   ```console
+   $ tt start supervised_failover
+   ```

doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/config.yaml

@@ -0,0 +1,8 @@
+config:
+  etcd:
+    endpoints:
+    - http://localhost:2379
+    prefix: /myapp
+    http:
+      request:
+        timeout: 3

doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/instances.yml

@@ -0,0 +1,3 @@
+instance001:
+instance002:
+instance003:

doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml

@@ -0,0 +1,44 @@
+credentials:
+  users:
+    replicator:
+      password: 'topsecret'
+      roles: [ replication ]
+      privileges:
+      - permissions: [ execute ]
+        functions: [ 'failover.execute' ]
+
+iproto:
+  advertise:
+    peer:
+      login: replicator
+
+replication:
+  failover: supervised
+
+failover:
+  probe_interval: 5
+  lease_interval: 15
+  renew_interval: 5
+  stateboard:
+    keepalive_interval: 5
+    renew_interval: 1
+
+roles: [ 'supervised_instance' ]
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'
+          instance002:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3302'
+          instance003:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3303'

doc/code_snippets/snippets/replication/instances.enabled/supervised_failover/supervised_instance.lua

@@ -0,0 +1,23 @@
+-- supervised_instance.lua --
+return {
+    validate = function()
+    end,
+    apply = function()
+        if box.info.ro then
+            return
+        end
+        local func_name = 'failover.execute'
+        local opts = { if_not_exists = true }
+        box.schema.func.create(func_name, opts)
+    end,
+    stop = function()
+        if box.info.ro then
+            return
+        end
+        local func_name = 'failover.execute'
+        if not box.schema.func.exists(func_name) then
+            return
+        end
+        box.schema.func.drop(func_name)
+    end,
+}

doc/concepts/replication/images/tarantool_supervised_failover.png

@@ -19,6 +19,7 @@ This section includes the following topics:
     repl_architecture
     repl_sync
     repl_leader_elect
+    supervised_failover
 
 For practical guides to replication, see :ref:`Replication tutorials <how-to-replication>`.
 You can learn about bootstrapping a replica set, adding instances to the replica set, or removing them.