From d66d1b1a4487d0acc797675b612a90b81bd1a964 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 16 Jul 2024 16:23:39 +0700 Subject: [PATCH 1/8] Add conditional config docs --- .../instances.enabled/conditional/config.yaml | 17 +++++++ .../conditional/instances.yml | 1 + doc/concepts/configuration.rst | 39 +++++++++++++++ .../configuration/configuration_reference.rst | 50 +++++++++++++++++++ 4 files changed, 107 insertions(+) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/conditional/config.yaml create mode 100644 doc/code_snippets/snippets/config/instances.enabled/conditional/instances.yml diff --git a/doc/code_snippets/snippets/config/instances.enabled/conditional/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/conditional/config.yaml new file mode 100644 index 0000000000..e12a18735c --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/conditional/config.yaml @@ -0,0 +1,17 @@ +conditional: + - if: tarantool_version < 3.1.0 + labels: + upgraded: 'false' + - if: tarantool_version >= 3.1.0 + labels: + upgraded: 'true' + compat: + box_error_serialize_verbose: 'new' + box_error_unpack_type_and_code: 'new' + +groups: + group001: + replicasets: + replicaset001: + instances: + instance001: {} \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/conditional/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/conditional/instances.yml new file mode 100644 index 0000000000..aa60c2fc42 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/conditional/instances.yml @@ -0,0 +1 @@ +instance001: diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index ff49259ac5..f5e9c99244 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -355,7 +355,46 @@ In the example below, ``{{ instance_name }}`` is replaced with *instance001*. As a result, the paths to :ref:`snapshots and write-ahead logs ` differ for different instances. +.. _configuration_conditional: +Conditional configuration sections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A YAML configuration can include parts that apply only to instances that meet certain conditions. +This is useful for cluster upgrade scenarios when instances can be running different +Tarantool versions and therefore require different configurations. + +Conditional parts are defined in the ``conditional`` top-level configuration section, +which includes one or more ``if`` subsections. Each ``if`` subsection defines conditions +and configuration parts that applies to instances that meet these conditions. + +The example below shows a ``conditional`` section for cluster upgrade from Tarantool 3.0.0 +to Tarantool 3.1.0: + +- The user-defined :ref:`label ` ``upgraded`` is ``true`` + on instances that are running Tarantool 3.1.0 or later. On older versions, it is ``false``. +- Two ``compat`` options that were introduced in 3.1.0 are defined for Tarantool 3.1.0 + instances. On older versions, they would cause an error. + +.. literalinclude:: /code_snippets/snippets/config/instances.enabled/conditional/config.yaml + :language: yaml + :start-at: conditional: + :end-before: groups: + :dedent: + +Example on GitHub: `conditional `_ + +The ``if`` clauses can use one variable -- ``tarantool_version``. It contains +a three-number Tarantool version and compares with values of the same format +using the comparison operators ``>``, ``<``, ``>=``, ``<=``, ``==``, and ``!=``. +You can write complex conditions using the logical operators ``||`` (OR) and ``&&`` (AND). +Parentheses ``()`` can be used to define the operators precedence. + +.. code-block:: yaml + + conditional: + - if: (tarantool_version > 3.2.0 || tarantool_version == 3.1.3) && tarantool_version <= 3.99.0 + -- < ... > .. _configuration_environment_variable: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 4ddc71050a..26669bbe44 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -688,6 +688,56 @@ The ``compat`` section defines values of the :ref:`compat ` modul | Default: 'new' | Environment variable: TT_COMPAT_YAML_PRETTY_MULTILINE + +.. _configuration_reference_conditional: + +conditional +----------- + +The ``conditional`` section defines the configuration parts that apply to instances +that meet certain conditions. + +.. NOTE:: + + ``conditional`` can be defined in the global :ref:`scope ` only. + +* :ref:`conditional.if ` + +.. _configuration_reference_conditional_if: + +.. confval:: conditional.if + + Specify a conditional section of the configuration. The configuration options + defined inside a ``conditional.if`` section apply only if the + + Conditions can include one variable: + + - ``tarantool_version``: a three-component version, for example, 3.1.0 + + The following operations are available: + + - comparison: ``>``, ``<``, ``>=``, ``<=``, ``==``, ``!=`` + - logical operators ``||`` (OR) and ``&&`` + - parentheses ``()`` + + **Example**: + + In this example, different configuration parts apply to instances running + Tarantool versions above and below 3.1.0: + + - On versions less than 3.1.0, the ``upgraded`` label is set to ``false``. + - On versions 3.1.0 or newer, the ``upgraded`` label is set to ``true``. + Additionally, new ``compat`` options are defined. These options were introduced + in version 3.1.0, so on older versions they would lead to validation errors. + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/conditional/config.yaml + :language: yaml + :start-at: conditional: + :end-before: groups: + :dedent: + + See also: :ref:`configuration_conditional` + .. _configuration_reference_config: config From 5e1aeb0d4cfa5b906dee7de8bb5fb97cb01468df Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 16 Jul 2024 16:56:44 +0700 Subject: [PATCH 2/8] fix --- doc/concepts/configuration.rst | 12 ++++++------ .../configuration/configuration_reference.rst | 7 ++++--- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index f5e9c99244..db1154ae01 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -361,17 +361,17 @@ Conditional configuration sections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A YAML configuration can include parts that apply only to instances that meet certain conditions. -This is useful for cluster upgrade scenarios when instances can be running different -Tarantool versions and therefore require different configurations. +This is useful for cluster upgrade scenarios: during an upgrade, instances can be running +different Tarantool versions and therefore require different configurations. -Conditional parts are defined in the ``conditional`` top-level configuration section, -which includes one or more ``if`` subsections. Each ``if`` subsection defines conditions -and configuration parts that applies to instances that meet these conditions. +Conditional parts are defined in the ``conditional`` configuration section in the global scope +It includes one or more ``if`` subsections. Each ``if`` subsection defines conditions +and configuration parts that apply to instances that meet these conditions. The example below shows a ``conditional`` section for cluster upgrade from Tarantool 3.0.0 to Tarantool 3.1.0: -- The user-defined :ref:`label ` ``upgraded`` is ``true`` +- The user-defined :ref:`label ` ``upgraded`` is ``true`` on instances that are running Tarantool 3.1.0 or later. On older versions, it is ``false``. - Two ``compat`` options that were introduced in 3.1.0 are defined for Tarantool 3.1.0 instances. On older versions, they would cause an error. diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 26669bbe44..46436c06b1 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -708,13 +708,14 @@ that meet certain conditions. .. confval:: conditional.if Specify a conditional section of the configuration. The configuration options - defined inside a ``conditional.if`` section apply only if the + defined inside a ``conditional.if`` section apply only to instances on which + the specified condition is true. Conditions can include one variable: - ``tarantool_version``: a three-component version, for example, 3.1.0 - The following operations are available: + The following operators are available in conditions: - comparison: ``>``, ``<``, ``>=``, ``<=``, ``==``, ``!=`` - logical operators ``||`` (OR) and ``&&`` @@ -728,7 +729,7 @@ that meet certain conditions. - On versions less than 3.1.0, the ``upgraded`` label is set to ``false``. - On versions 3.1.0 or newer, the ``upgraded`` label is set to ``true``. Additionally, new ``compat`` options are defined. These options were introduced - in version 3.1.0, so on older versions they would lead to validation errors. + in version 3.1.0, so on older versions they would cause an error. .. literalinclude:: /code_snippets/snippets/config/instances.enabled/conditional/config.yaml :language: yaml From 3530e1ce1359c95c72cf6fb5c0115e11ce8b8c16 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 16 Jul 2024 17:13:00 +0700 Subject: [PATCH 3/8] Fix --- doc/concepts/configuration.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index db1154ae01..9de3ca3c09 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -384,7 +384,8 @@ to Tarantool 3.1.0: Example on GitHub: `conditional `_ -The ``if`` clauses can use one variable -- ``tarantool_version``. It contains + +``if`` sections can use one variable -- ``tarantool_version``. It contains a three-number Tarantool version and compares with values of the same format using the comparison operators ``>``, ``<``, ``>=``, ``<=``, ``==``, and ``!=``. You can write complex conditions using the logical operators ``||`` (OR) and ``&&`` (AND). @@ -396,6 +397,22 @@ Parentheses ``()`` can be used to define the operators precedence. - if: (tarantool_version > 3.2.0 || tarantool_version == 3.1.3) && tarantool_version <= 3.99.0 -- < ... > + +If the same option is set in multiple ``if`` sections that are true for an instance, +this option receives the value from the section declared last in the configuration. + +Example: + +.. code-block:: yaml + +conditional: + - if: tarantool_version >= 3.0.0 + label: + version: '3.0' -- applies to versions >= 3.0.0 and < 3.1.0 + - if: tarantool_version >= 3.1.0 + label: + version: '3.1+ -- applies to versions >= 3.1.0 + .. _configuration_environment_variable: Environment variables From 19d7d5fd91bd2bb83cd1d8d93ce43e67f55931fe Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 16 Jul 2024 17:16:24 +0700 Subject: [PATCH 4/8] Fix --- doc/concepts/configuration.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 9de3ca3c09..23195b4640 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -407,11 +407,11 @@ Example: conditional: - if: tarantool_version >= 3.0.0 - label: - version: '3.0' -- applies to versions >= 3.0.0 and < 3.1.0 + labels: + version: '3.0' # applies to versions >= 3.0.0 and < 3.1.0 - if: tarantool_version >= 3.1.0 - label: - version: '3.1+ -- applies to versions >= 3.1.0 + labels: + version: '3.1+ # applies to versions >= 3.1.0 .. _configuration_environment_variable: From e744153af4cf421b38adbd18805443e129662c2c Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 16 Jul 2024 17:52:46 +0700 Subject: [PATCH 5/8] Fix --- doc/concepts/configuration.rst | 14 +++++++------- .../configuration/configuration_reference.rst | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 23195b4640..6413fcc895 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -405,13 +405,13 @@ Example: .. code-block:: yaml -conditional: - - if: tarantool_version >= 3.0.0 - labels: - version: '3.0' # applies to versions >= 3.0.0 and < 3.1.0 - - if: tarantool_version >= 3.1.0 - labels: - version: '3.1+ # applies to versions >= 3.1.0 + conditional: + - if: tarantool_version >= 3.0.0 + labels: + version: '3.0' # applies to versions >= 3.0.0 and < 3.1.0 + - if: tarantool_version >= 3.1.0 + labels: + version: '3.1+ # applies to versions >= 3.1.0 .. _configuration_environment_variable: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 46436c06b1..6206c35066 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -711,9 +711,9 @@ that meet certain conditions. defined inside a ``conditional.if`` section apply only to instances on which the specified condition is true. - Conditions can include one variable: - - - ``tarantool_version``: a three-component version, for example, 3.1.0 + Conditions can include one variable -- ``tarantool_version``: a three-number + Tarantool version running on the instance, for example, 3.1.0. It compares to + *version literal* values that include three numbers separated by periods (``x.y.z``). The following operators are available in conditions: From 862f32f7348e6df5570f3dd6c31fe9e91a69cc3f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 16 Jul 2024 18:00:47 +0700 Subject: [PATCH 6/8] Fix --- doc/concepts/configuration.rst | 2 +- doc/reference/configuration/configuration_reference.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 6413fcc895..0c80c0e358 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -411,7 +411,7 @@ Example: version: '3.0' # applies to versions >= 3.0.0 and < 3.1.0 - if: tarantool_version >= 3.1.0 labels: - version: '3.1+ # applies to versions >= 3.1.0 + version: '3.1+' # applies to versions >= 3.1.0 .. _configuration_environment_variable: diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 6206c35066..8f84112aff 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -718,7 +718,7 @@ that meet certain conditions. The following operators are available in conditions: - comparison: ``>``, ``<``, ``>=``, ``<=``, ``==``, ``!=`` - - logical operators ``||`` (OR) and ``&&`` + - logical operators ``||`` (OR) and ``&&`` (AND) - parentheses ``()`` **Example**: From c4849ab7bbc4166de15efba005bea6b4c383b2ea Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 17 Jul 2024 14:06:04 +0700 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Andrey Aksenov <38073144+andreyaksenov@users.noreply.github.com> --- doc/concepts/configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 0c80c0e358..24a1fa7cc4 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -364,7 +364,7 @@ A YAML configuration can include parts that apply only to instances that meet ce This is useful for cluster upgrade scenarios: during an upgrade, instances can be running different Tarantool versions and therefore require different configurations. -Conditional parts are defined in the ``conditional`` configuration section in the global scope +Conditional parts are defined in the ``conditional`` configuration section in the global scope. It includes one or more ``if`` subsections. Each ``if`` subsection defines conditions and configuration parts that apply to instances that meet these conditions. @@ -373,7 +373,7 @@ to Tarantool 3.1.0: - The user-defined :ref:`label ` ``upgraded`` is ``true`` on instances that are running Tarantool 3.1.0 or later. On older versions, it is ``false``. -- Two ``compat`` options that were introduced in 3.1.0 are defined for Tarantool 3.1.0 +- Two :ref:`compat ` options that were introduced in 3.1.0 are defined for Tarantool 3.1.0 instances. On older versions, they would cause an error. .. literalinclude:: /code_snippets/snippets/config/instances.enabled/conditional/config.yaml From fa28fa7d2af1210d8e8ad3f6ff3fbaf13248cad0 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 17 Jul 2024 14:07:46 +0700 Subject: [PATCH 8/8] Update configuration.rst --- doc/concepts/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst index 24a1fa7cc4..40b578d022 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -364,7 +364,7 @@ A YAML configuration can include parts that apply only to instances that meet ce This is useful for cluster upgrade scenarios: during an upgrade, instances can be running different Tarantool versions and therefore require different configurations. -Conditional parts are defined in the ``conditional`` configuration section in the global scope. +Conditional parts are defined in the :ref:`conditional ` configuration section in the global scope. It includes one or more ``if`` subsections. Each ``if`` subsection defines conditions and configuration parts that apply to instances that meet these conditions.