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 000000000..e12a18735 --- /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 000000000..aa60c2fc4 --- /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 ff49259ac..40b578d02 100644 --- a/doc/concepts/configuration.rst +++ b/doc/concepts/configuration.rst @@ -355,7 +355,63 @@ 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: during an upgrade, instances can be running +different Tarantool versions and therefore require different configurations. + +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. + +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 :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 + :language: yaml + :start-at: conditional: + :end-before: groups: + :dedent: + +Example on GitHub: `conditional `_ + + +``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). +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 + -- < ... > + + +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 + 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 4ddc71050..8f84112af 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -688,6 +688,57 @@ 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 to instances on which + the specified condition is true. + + 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: + + - comparison: ``>``, ``<``, ``>=``, ``<=``, ``==``, ``!=`` + - logical operators ``||`` (OR) and ``&&`` (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 cause an error. + + .. 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