diff --git a/doc/code_snippets/snippets/config/instances.enabled/labels/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/labels/config.yaml new file mode 100644 index 0000000000..e64da49b39 --- /dev/null +++ b/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' diff --git a/doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index a895e31e32..ff49259ac5 100644 --- a/doc/concepts/configuration.rst +++ b/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 `_ + +To access instance labels from the application code, call the :ref:`config: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 `. .. _configuration_predefined_variables: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 97ee00e65f..eb6f1e7f4c 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2166,6 +2166,37 @@ instances Any configuration parameter that can be defined in the instance :ref:`scope `. For example, :ref:`iproto ` and :ref:`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 `. + +- :ref:`labels.\ ` + +.. _configuration_reference_labels_name: + +.. confval:: labels. + + 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 diff --git a/doc/release/3.1.0.rst b/doc/release/3.1.0.rst index 6274e6047c..94b906a3a0 100644 --- a/doc/release/3.1.0.rst +++ b/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 ` 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 `. .. _3-1-accessing_configuration: