Add config labels documentation (#4360)

Resolves #4096 

Co-authored-by: Andrey Aksenov <[email protected]>

Author: p7nov

doc/code_snippets/snippets/config/instances.enabled/labels/config.yaml

@@ -0,0 +1,12 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        labels:
+          dc: 'east'
+          production: 'false'
+        instances:
+          instance001:
+            labels:
+              rack: '10'
+              production: 'true'

doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml

@@ -0,0 +1 @@
+instance001:

doc/concepts/configuration.rst

@@ -296,8 +296,44 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the
                       farewell: 'Bye'
 
 
+.. _configuration_labels:
 
+Adding labels
+~~~~~~~~~~~~~
+
+*Labels* allow adding custom attributes to your cluster configuration. A label is
+an arbitrary ``key: value`` pair with a string key and value.
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/labels/config.yaml
+    :language: yaml
+    :start-at: labels:
+    :end-at: 'false'
+    :dedent:
+
+Labels can be defined in any configuration scope. An instance receives labels from
+all scopes it belongs to. The ``labels`` section in a group or a replica set scope
+applies to all instances of the group or a replica set. To override these labels on
+the instance level or add instance-specific labels, define another ``labels`` section in the instance scope.
+
+..  literalinclude:: /code_snippets/snippets/config/instances.enabled/labels/config.yaml
+    :language: yaml
+    :dedent:
+
+Example on GitHub: `labels <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/labels>`_
+
+To access instance labels from the application code, call the :ref:`config:get() <config_api_reference_get>` function:
+
+.. code-block:: tarantoolsession
+
+    myapp:instance001> require('config'):get('labels')
+    ---
+    - production: 'true'
+      rack: '10'
+      dc: east
+    ...
 
+Labels can be used to direct function calls to instances that match certain criteria
+using the :ref:`connpool module <connpool_module>`.
 
 .. _configuration_predefined_variables:
 

doc/reference/configuration/configuration_reference.rst

@@ -2462,6 +2462,37 @@ instances
     Any configuration parameter that can be defined in the instance :ref:`scope <configuration_scopes>`.
     For example, :ref:`iproto <configuration_reference_iproto>` and :ref:`database <configuration_reference_database>` configuration parameters defined at the instance level are applied to this instance only.
 
+..  _configuration_reference_labels:
+
+labels
+------
+
+The ``labels`` section allows adding custom attributes to the configuration.
+Attributes must be ``key: value`` pairs with string keys and values.
+
+
+..  NOTE::
+
+    ``labels`` can be defined in any :ref:`scope <configuration_scopes>`.
+
+-   :ref:`labels.\<label_name\> <configuration_reference_labels_name>`
+
+..  _configuration_reference_labels_name:
+
+.. confval:: labels.<label_name>
+
+    A value of the label with the specified name.
+
+    **Example**
+
+    The example below shows how to define labels on the replica set and instance levels:
+
+    ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/labels/config.yaml
+        :language: yaml
+        :dedent:
+
+    See also: :ref:`configuration_labels`
+
 ..  _configuration_reference_log:
 
 log

doc/release/3.1.0.rst

@@ -197,7 +197,8 @@ In the 3.1 version, this module provides the following API:
 
 
 *   The ``filter()`` function returns the names of instances that match the specified conditions.
-    In the example below, this function returns a list of instances with the ``storage`` role and specified label value:
+    In the example below, this function returns a list of instances with the ``storage`` role and specified
+    :ref:`label <configuration_labels>` value:
 
     .. code-block:: tarantoolsession
 
@@ -216,11 +217,13 @@ In the 3.1 version, this module provides the following API:
 
     .. code-block:: tarantoolsession
 
+        sharded_cluster:router-a-001> connpool.call('vshard.storage.buckets_count', nil, { roles = { 'storage' }, labels = { dc = 'west' }, mode = 'rw' })
         sharded_cluster:router-a-001> connpool.call('vshard.storage.buckets_count', nil, { roles = { 'storage' }, labels = { dc = 'west' }, mode = 'rw' })
         ---
         - 500
         ...
 
+Learn more in the ``experimental.connpool`` :ref:`module reference <connpool_module>`.
 
 
 .. _3-1-accessing_configuration: