From ea275521bd354feb379d53a190d745ec38d6190d Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Tue, 27 May 2025 16:58:24 +0300 Subject: [PATCH 1/5] Adds isolated instance mode description The ```isolated:true``` option moves the instance to RO mode In this mode, various debugging & maintanance operations can be performed Fixes #4632 --- .../isolated_mode/config.yaml | 10 ++++++ .../configuration/configuration_reference.rst | 34 +++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml diff --git a/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml new file mode 100644 index 000000000..6120fbbb1 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml @@ -0,0 +1,10 @@ +groups: + g: + replicasets: + r: + instances: + i-001: {} + i-002: {} + i-003: {} + i-004: + isolated: true \ No newline at end of file diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 8a0b8a2a2..e52a2f14f 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2836,6 +2836,40 @@ Attributes must be ``key: value`` pairs with string keys and values. See also: :ref:`configuration_labels` +.. _configuration_reference_isolated_mode: + +isolated mode +------ + +Since version :doc:`3.3.0 `, a new ``isolated`` option is added to instance configuration. + +The option takes boolean values, by default it is set to ``false``. + +When set to ``true``, it moves the instance it has been applied at to the **isolated** mode. + +The isolated mode allows the user to temporarily isolate an instance and perform maintenance activities on it. + +The isolated mode moves the instance to the read-only state, in which: + +* iproto stops listening for new connections +* iproto drops all the current connections +* The instance is disconnected from all the replication upstreams +* Other replicaset members exclude the isolated instance from the replication upstreams + +Once the mode is enabled, After any requests that try to change persistent data will fail with the ``ER_READONLY`` error. + +.. NOTE:: + + isolated instance can't be bootstrapped (a local snapshot is required to start). + + **Example** + + The example below shows how to isolate an instance: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml + :language: yaml + :dedent: + .. _configuration_reference_log: log From 18170cc09949f1d6d898e57eede0685a972ea6fc Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Wed, 28 May 2025 08:38:47 +0300 Subject: [PATCH 2/5] Adds note to troubleshooting guide Fixes language and syntax --- doc/admin/troubleshoot.rst | 4 ++++ doc/reference/configuration/configuration_reference.rst | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/admin/troubleshoot.rst b/doc/admin/troubleshoot.rst index 0e12b5183..dd2edac25 100644 --- a/doc/admin/troubleshoot.rst +++ b/doc/admin/troubleshoot.rst @@ -254,6 +254,10 @@ This issue can be fixed in two ways: - Manually: :ref:`reseed ` one master from another by removing write-ahead logs and snapshots. - Programmatically: set up a :ref:`conflict resolution trigger `. +.. NOTE:: + + To avoid brain split between two masters, one of the instances may be put in the :ref:`isolated mode <_configuration_reference_isolated_mode>`. + Then, restart replication as described in :ref:`Restarting replication `. diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index e52a2f14f..b9599d947 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2856,13 +2856,13 @@ The isolated mode moves the instance to the read-only state, in which: * The instance is disconnected from all the replication upstreams * Other replicaset members exclude the isolated instance from the replication upstreams -Once the mode is enabled, After any requests that try to change persistent data will fail with the ``ER_READONLY`` error. +Once the mode is enabled, any request trying to change persistent data will fail with the ``ER_READONLY`` error. .. NOTE:: - isolated instance can't be bootstrapped (a local snapshot is required to start). + Isolated instance can't be bootstrapped (a local snapshot is required to start). - **Example** +**Example** The example below shows how to isolate an instance: From 8ea9848e1f0a9e74b687fb07bfc19535b3b98d14 Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Wed, 28 May 2025 08:50:12 +0300 Subject: [PATCH 3/5] Updates style & language --- doc/reference/configuration/configuration_reference.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index b9599d947..1cb7ab95b 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2844,8 +2844,7 @@ isolated mode Since version :doc:`3.3.0 `, a new ``isolated`` option is added to instance configuration. The option takes boolean values, by default it is set to ``false``. - -When set to ``true``, it moves the instance it has been applied at to the **isolated** mode. +``isolated:true`` moves the instance it has been applied at to the **isolated** mode. The isolated mode allows the user to temporarily isolate an instance and perform maintenance activities on it. From a1aacf7dd69f332d2252422ebfa1bec4ceb4ac61 Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Thu, 29 May 2025 13:52:03 +0300 Subject: [PATCH 4/5] Updates by comments --- doc/admin/troubleshoot.rst | 2 +- .../config/instances.enabled/isolated_mode/config.yaml | 2 +- doc/reference/configuration/configuration_reference.rst | 5 ++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/admin/troubleshoot.rst b/doc/admin/troubleshoot.rst index dd2edac25..ec1ec63cc 100644 --- a/doc/admin/troubleshoot.rst +++ b/doc/admin/troubleshoot.rst @@ -256,7 +256,7 @@ This issue can be fixed in two ways: .. NOTE:: - To avoid brain split between two masters, one of the instances may be put in the :ref:`isolated mode <_configuration_reference_isolated_mode>`. + If one of the instances must be isolated during troubleshooting, it can be put to the :ref:`isolated mode <_configuration_reference_isolated_mode>`. Then, restart replication as described in :ref:`Restarting replication `. diff --git a/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml index 6120fbbb1..aed96e565 100644 --- a/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml +++ b/doc/code_snippets/snippets/config/instances.enabled/isolated_mode/config.yaml @@ -7,4 +7,4 @@ groups: i-002: {} i-003: {} i-004: - isolated: true \ No newline at end of file + isolated: true diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 1cb7ab95b..787b21e37 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2848,15 +2848,14 @@ The option takes boolean values, by default it is set to ``false``. The isolated mode allows the user to temporarily isolate an instance and perform maintenance activities on it. -The isolated mode moves the instance to the read-only state, in which: +In the isolated mode: +* The instance is moved to the read-only state * iproto stops listening for new connections * iproto drops all the current connections * The instance is disconnected from all the replication upstreams * Other replicaset members exclude the isolated instance from the replication upstreams -Once the mode is enabled, any request trying to change persistent data will fail with the ``ER_READONLY`` error. - .. NOTE:: Isolated instance can't be bootstrapped (a local snapshot is required to start). From bb91a69888f622c27315544f1429503de8bf8193 Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Mon, 2 Jun 2025 08:59:37 +0300 Subject: [PATCH 5/5] updates by comments --- .../configuration/configuration_reference.rst | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 787b21e37..9d4da2382 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -2805,37 +2805,6 @@ 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_isolated_mode: isolated mode @@ -2844,7 +2813,7 @@ isolated mode Since version :doc:`3.3.0 `, a new ``isolated`` option is added to instance configuration. The option takes boolean values, by default it is set to ``false``. -``isolated:true`` moves the instance it has been applied at to the **isolated** mode. +``isolated: true`` moves the instance it has been applied at to the **isolated** mode. The isolated mode allows the user to temporarily isolate an instance and perform maintenance activities on it. @@ -2868,6 +2837,37 @@ In the isolated mode: :language: yaml :dedent: +.. _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