Skip to content

Add conditional config docs #4364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jul 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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: {}
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
instance001:
56 changes: 56 additions & 0 deletions doc/concepts/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <configuration_persistence>` 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_reference_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 <configuration_labels>` ``upgraded`` is ``true``
on instances that are running Tarantool 3.1.0 or later. On older versions, it is ``false``.
- Two :ref:`compat <configuration_reference_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 <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/config/instances.enabled/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:

Expand Down
51 changes: 51 additions & 0 deletions doc/reference/configuration/configuration_reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -688,6 +688,57 @@ The ``compat`` section defines values of the :ref:`compat <compat-module>` 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 <configuration_scopes>` only.

* :ref:`conditional.if <configuration_reference_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
Expand Down
Loading