From 5a92513a211f313a59f6379d33be3b2271fb7e44 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 11 Jul 2024 13:11:25 +0700 Subject: [PATCH 1/5] Add config labels documentation --- .../instances.enabled/labels/config.yaml | 12 +++++++ .../instances.enabled/labels/instances.yml | 1 + doc/concepts/configuration.rst | 32 +++++++++++++++++++ .../configuration/configuration_reference.rst | 29 +++++++++++++++++ doc/release/3.1.0.rst | 3 +- 5 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/labels/config.yaml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/labels/instances.yml 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..c182ad457c 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -296,8 +296,40 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the farewell: 'Bye' +.. _configuration_labels: +Adding custom labels +~~~~~~~~~~~~~~~~~~~~ + +Labels allow adding custom attributes to your cluster configuration. A label is +a ``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 in belongs to. A ``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 the labels from the application code, call the :ref:`config:get() ` function: + +.. code-block:: lua + + require('config'):get('labels') + +// how to use in connpool +ref:`connpool module <3-1-experimental_connpool>` .. _configuration_predefined_variables: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 97ee00e65f..1eaba18443 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2166,6 +2166,35 @@ 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: + .. _configuration_reference_log: log diff --git a/doc/release/3.1.0.rst b/doc/release/3.1.0.rst index 6274e6047c..b536670923 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 From a7c706ce3fb6d2aa16c8053f3039871385ac3919 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 11 Jul 2024 14:39:47 +0700 Subject: [PATCH 2/5] Add config labels documentation --- doc/concepts/configuration.rst | 30 ++++++++++++++----- .../configuration/configuration_reference.rst | 2 ++ doc/release/3.1.0.rst | 1 + 3 files changed, 25 insertions(+), 8 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index c182ad457c..8f0d5e484e 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -301,8 +301,8 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the Adding custom labels ~~~~~~~~~~~~~~~~~~~~ -Labels allow adding custom attributes to your cluster configuration. A label is -a ``key: value`` pair with a string key and value. +*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 @@ -313,7 +313,7 @@ a ``key: value`` pair with a string key and value. Labels can be defined in any configuration scope. An instance receives labels from all scopes in belongs to. A ``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. +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 @@ -321,15 +321,29 @@ the instance level or add instance-specific labels define another ``labels`` sec Example on GitHub: `labels `_ -To access the labels from the application code, call the :ref:`config:get() ` function: +To access instance labels from the application code, call the :ref:`config:get() ` function: -.. code-block:: lua +.. code-block:: tarantoolsession - require('config'):get('labels') + myapp:instance001> require('config'):get('labels') + --- + - production: 'true' + rack: '10' + dc: east + ... -// how to use in connpool +Labels can be used to direct function calls to instances that match certain criteria +using the :ref:`connpool module <3-1-experimental_connpool>`. For example, call a +function on any instance that has the ``dc`` label with the ``west`` value. -ref:`connpool module <3-1-experimental_connpool>` +.. code-block:: tarantoolsession + + myapp:instance001> connpool = require('experimental.connpool') + --- + ... + + myapp:instance001> connpool.call('box.stat', nil, { labels = { dc = 'east' }) + --- .. _configuration_predefined_variables: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 1eaba18443..eb6f1e7f4c 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2195,6 +2195,8 @@ Attributes must be ``key: value`` pairs with string keys and values. :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 b536670923..bd61c9c6f4 100644 --- a/doc/release/3.1.0.rst +++ b/doc/release/3.1.0.rst @@ -217,6 +217,7 @@ 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 From 53e99387e3e06c08d2d5e1e52407b3385e1e44e6 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 12 Jul 2024 18:11:25 +0700 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Andrey Aksenov <38073144+andreyaksenov@users.noreply.github.com> --- doc/concepts/configuration.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 8f0d5e484e..8491cdc360 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -311,7 +311,7 @@ an arbitrary ``key: value`` pair with a string key and value. :dedent: Labels can be defined in any configuration scope. An instance receives labels from -all scopes in belongs to. A ``labels`` section in a group or a replica set scope +all scopes in 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. @@ -333,8 +333,8 @@ To access instance labels from the application code, call the :ref:`config:get() ... Labels can be used to direct function calls to instances that match certain criteria -using the :ref:`connpool module <3-1-experimental_connpool>`. For example, call a -function on any instance that has the ``dc`` label with the ``west`` value. +using the :ref:`connpool module `. For example, call a +function on any instance that has the ``dc`` label with the ``east`` value. .. code-block:: tarantoolsession From 5c894c96fc7a7baffa3749cbbe1350f0db6c2f08 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 12 Jul 2024 18:13:25 +0700 Subject: [PATCH 4/5] Fix --- doc/concepts/configuration.rst | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 8491cdc360..ff49259ac5 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -298,8 +298,8 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the .. _configuration_labels: -Adding custom 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. @@ -311,7 +311,7 @@ an arbitrary ``key: value`` pair with a string key and value. :dedent: Labels can be defined in any configuration scope. An instance receives labels from -all scopes in belongs to. The ``labels`` section in a group or a replica set scope +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. @@ -333,17 +333,7 @@ To access instance labels from the application code, call the :ref:`config:get() ... Labels can be used to direct function calls to instances that match certain criteria -using the :ref:`connpool module `. For example, call a -function on any instance that has the ``dc`` label with the ``east`` value. - -.. code-block:: tarantoolsession - - myapp:instance001> connpool = require('experimental.connpool') - --- - ... - - myapp:instance001> connpool.call('box.stat', nil, { labels = { dc = 'east' }) - --- +using the :ref:`connpool module `. .. _configuration_predefined_variables: From 823704ff3cc5c9f3abc049e4a153fd47a084814c Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 12 Jul 2024 18:15:45 +0700 Subject: [PATCH 5/5] Fix --- doc/release/3.1.0.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/release/3.1.0.rst b/doc/release/3.1.0.rst index bd61c9c6f4..94b906a3a0 100644 --- a/doc/release/3.1.0.rst +++ b/doc/release/3.1.0.rst @@ -223,6 +223,7 @@ In the 3.1 version, this module provides the following API: - 500 ... +Learn more in the ``experimental.connpool`` :ref:`module reference `. .. _3-1-accessing_configuration: