Roles reference

Author: andreyaksenov

doc/reference/configuration/configuration_reference.rst

@@ -2861,11 +2861,12 @@ The ``replication`` section defines configuration parameters related to :ref:`re
 roles
 -----
 
-This section describes configuration parameters related to roles.
+This section describes configuration parameters related to application roles.
+An application role is a Lua module that implements specific functions or logic.
 
 .. NOTE::
 
-    Configuration parameters related to roles can be defined in any :ref:`scope <configuration_scopes>`.
+    Configuration parameters related to application roles can be defined in any :ref:`scope <configuration_scopes>`.
 
 -   :ref:`roles <configuration_reference_roles>`
 -   :ref:`roles_cfg <configuration_reference_roles_cfg>`
@@ -2877,6 +2878,120 @@ This section describes configuration parameters related to roles.
 
     **Since:** :doc:`3.0.0 </release/3.0.0>`.
 
+    Specify the roles of an instance.
+    To specify a role's configuration, use the :ref:`roles_cfg <configuration_reference_roles_cfg>` option.
+
+    There are two types of application roles:
+
+    -   Built-in roles. For example, the `CRUD <https://github.com/tarantool/crud>`__ module provides the ``roles.crud-storage`` and ``roles.crud-router`` roles that enable CRUD operations in a sharded cluster.
+    -   Custom roles. For example, you create a custom role to define a stored procedure or implement a supplementary service, such as an e-mail notifier or a replicator.
+
+    To create a custom role, you need to define the following methods and fields:
+
+    -   ``validate()``
+
+        Validate a role's configuration.
+        This method is called when the initial configuration is applied or the configuration is reloaded for the instance with this role.
+        ``validate()`` should throw an error if the validation fails.
+
+    -   ``apply()``
+
+        Apply a role's configuration.
+        This method is called when the initial configuration is applied or the configuration is reloaded for the instance with this role.
+        ``apply()`` should throw an error if the specified configuration can't be applied.
+
+    -   ``stop()``
+
+        Stop a role.
+        This method is called on configuration reload if the role is removed from ``roles`` for the given instance.
+        ``stop()`` should cancel all background fibers and clean up used resources.
+        If these actions can't be performed, ``stop()`` should throw an error.
+
+    -   (Optional) ``dependencies``
+
+        Define a role's dependencies as an array.
+        For roles that depend on each other, their ``validate()`` and ``apply()`` methods are executed taking into account the dependencies.
+        Suppose, there are three roles that depend on each other as follows:
+
+        ..  code-block:: none
+
+            role1
+                └─── role2
+                         └─── role3
+
+        In this case, ``validate()`` and ``apply()`` for these roles are executed in the following order:
+
+        ..  code-block:: none
+
+            role3 -> role2 -> role1
+
+
+    **Example: Built-in role**
+
+    The examples below show how to enable the router and storage-specific roles provided by the `CRUD <https://github.com/tarantool/crud>`__ module:
+
+    -   ``roles.crud-router``:
+
+        ..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml
+            :language: yaml
+            :start-at: routers
+            :end-at: roles.crud-router
+            :dedent:
+
+    -   ``roles.crud-storage``:
+
+        ..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml
+            :language: yaml
+            :start-at: storages
+            :end-at: roles.crud-storage
+            :dedent:
+
+    You can find the full example here: `sharded_cluster_crud <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud>`_.
+
+    **Example: Custom role**
+
+    The configuration below shows how to enable the custom ``greeter`` role for ``instance001`` and specify the configuration for this role using :ref:`roles_cfg <configuration_reference_roles_cfg>`:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role/config.yaml
+        :language: yaml
+        :start-at: instance001
+        :end-at: greeting
+        :dedent:
+
+    You can define the ``validate()``, ``apply()``, and ``stop()`` functions in the role's code as follows:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role/greeter.lua
+        :language: lua
+        :dedent:
+
+    You can find the full example here: `application_role <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/application_role>`_.
+
+    **Example: Role dependency**
+
+    The example below implements the ``greeter`` role:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_dependency/greeter.lua
+        :language: lua
+        :dedent:
+
+    The ``byeer`` role has the ``greeter`` role in the ``dependencies`` field:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_dependency/byeer.lua
+        :language: lua
+        :dedent:
+
+    In the configuration, an instance cannot have only the ``byeer`` role because it depends on the ``greeter`` role.
+    In this example, ``instance001`` has both roles enabled:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_dependency/config.yaml
+        :language: yaml
+        :start-at: instance001
+        :end-at: byeer
+        :dedent:
+
+    You can find the full example here: `application_role_dependency <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/application_role_dependency>`_.
+
+
     |
     | Type: array
     | Default: nil
@@ -2889,6 +3004,40 @@ This section describes configuration parameters related to roles.
 
     **Since:** :doc:`3.0.0 </release/3.0.0>`.
 
+    Specify a role's configuration.
+    This option accepts a role name as the key and a role's configuration as the value.
+    To specify the roles of an instance, use the :ref:`roles <configuration_reference_roles>` option.
+
+    **Example: Built-in role**
+
+    The example below shows how to enable and configure the ``roles.crud-router`` role provided by the `CRUD <https://github.com/tarantool/crud>`__ module:
+
+    ..  literalinclude:: /code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml
+        :language: yaml
+        :start-at: roles.crud-router
+        :end-at: stats_quantile_max_age_time
+        :dedent:
+
+    You can find the full example here: `sharded_cluster_crud <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud>`_.
+
+    **Example: Custom role**
+
+    The configuration below shows how to enable the custom ``greeter`` role for ``instance001`` and specify the configuration for this role:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role/config.yaml
+        :language: yaml
+        :start-at: instance001
+        :end-at: greeting
+        :dedent:
+
+    You can define the ``validate()``, ``apply()``, and ``stop()`` functions in the role's code as follows:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role/greeter.lua
+        :language: lua
+        :dedent:
+
+    You can find the full example here: `application_role <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/application_role>`_.
+
     |
     | Type: map
     | Default: nil