Update lua_call behavior: config option and supervised failover tutor…

…ial (#4648)

Resolves #4462

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

@@ -5,7 +5,7 @@ credentials:
       roles: [ replication ]
       privileges:
       - permissions: [ execute ]
-        functions: [ 'failover.execute' ]
+        lua_call: [ 'failover.execute' ]
 
 iproto:
   advertise:
@@ -23,8 +23,6 @@ failover:
     keepalive_interval: 5
     renew_interval: 1
 
-roles: [ 'supervised_instance' ]
-
 groups:
   group001:
     replicasets:

doc/platform/replication/supervised_failover.rst

@@ -106,49 +106,96 @@ Configuring a cluster
 
 To configure a cluster to work with an external failover coordinator, follow the steps below:
 
-1.  (Optional) If you need to run :ref:`several failover coordinators <supervised_failover_overview_fault_tolerance>` to increase fault tolerance, set up an etcd-based configuration storage, as described in :ref:`configuration_etcd`.
+#.  (Optional) If you need to run :ref:`several failover coordinators <supervised_failover_overview_fault_tolerance>` to increase fault tolerance, set up an etcd-based configuration storage, as described in :ref:`configuration_etcd`.
 
-2.  Set the :ref:`replication.failover <configuration_reference_replication_failover>` option to ``supervised``:
+#.  Set the :ref:`replication.failover <configuration_reference_replication_failover>` option to ``supervised``:
 
     ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml
         :language: yaml
         :start-at: replication:
         :end-at: failover: supervised
         :dedent:
 
-3.  Grant a user used for replication :ref:`permissions <configuration_credentials_managing_users_roles_granting_privileges>` to execute the ``failover.execute`` function:
+#.  Grant a user used for replication :ref:`permissions <configuration_credentials_managing_users_roles_granting_privileges>` to execute the ``failover.execute`` function:
 
     ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml
         :language: yaml
         :start-at: credentials:
         :end-at: failover.execute
         :dedent:
 
-4.  Create the ``failover.execute`` function in the application code.
-    For example, you can create a :ref:`custom role <application_roles>` for this purpose:
+    .. note::
 
-    ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/supervised_instance.lua
-        :language: lua
-        :dedent:
-
-    Then, you need to enable this role for all storage instances:
-
-    ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml
-        :language: yaml
-        :start-at: supervised_instance
-        :end-before: groups:
-        :dedent:
+        In Tarantool 3.0 and 3.1, the configuration is different and the function
+        must be created in the application code. See :ref:`supervised_failover_configuration_with_role` for details.
 
-5.  (Optional) Configure options that control how a failover coordinator operates in the :ref:`failover <configuration_reference_failover>` section:
+#.  (Optional) Configure options that control how a failover coordinator operates in the :ref:`failover <configuration_reference_failover>` section:
 
     ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/supervised_failover/source.yaml
         :language: yaml
         :start-after: failover: supervised
-        :end-before: supervised_instance
+        :end-before: groups
         :dedent:
 
 You can find the full example on GitHub: `supervised_failover <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/replication/instances.enabled/supervised_failover>`_.
 
+.. _supervised_failover_configuration_with_role:
+
+Tarantool 3.0 and 3.1 configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before version 3.2, Tarantool used another mechanism to grant execute access to Lua
+functions. In Tarantool 3.0 and 3.1, the ``credentials`` configuration section
+should look as follows:
+
+.. code-block:: yaml
+
+    # Tarantool 3.0 and 3.1
+    credentials:
+      users:
+        replicator:
+          password: 'topsecret'
+          roles: [ replication ]
+          privileges:
+          - permissions: [ execute ]
+            functions: [ 'failover.execute' ]
+
+Additionally, you should create the ``failover.execute`` function in the application code.
+For example, you can create a :ref:`custom role <application_roles>` for this purpose:
+
+.. code-block:: lua
+
+    -- Tarantool 3.0 and 3.1 --
+    -- 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,
+    }
+
+Then, enable this role for all storage instances:
+
+.. code-block:: yaml
+
+    # Tarantool 3.0 and 3.1
+    roles: [ 'supervised_instance' ]
 
 .. _supervised_failover_start_coordinator:
 

doc/reference/configuration/configuration_reference.rst

@@ -1445,7 +1445,11 @@ credentials.users.*
 
 .. confval:: <user_or_role_name>.privileges.lua_call
 
-    Whether this user or a user with this role can call any global user-defined Lua function.
+    A list of global user-defined Lua functions that this user or a user with this role can call.
+    To allow calling all such functions, specify the ``all`` value.
+
+    This option should be configured together with the ``execute``
+    :ref:`permission <configuration_reference_credentials_privileges_permissions>`.
 
 ..  _configuration_reference_credentials_privileges_sql: