Document the 'replication.anon' config option (#4344)

tarantool · Jul 10, 2024 · b0ef2dd · b0ef2dd
1 parent 089122e
commit b0ef2dd
Show file tree

Hide file tree

Showing 7 changed files with 102 additions and 29 deletions.
diff --git a/...ode_snippets/snippets/replication/instances.enabled/anonymous_replica/README.md b/...ode_snippets/snippets/replication/instances.enabled/anonymous_replica/README.md
@@ -0,0 +1,11 @@
+# Anonymous replica
+
+A sample application demonstrating how to add an anonymous replica to a replica set.
+
+## Running
+
+To start all instances, execute the following command in the [replication](../../../replication) directory:
+
+```console
+$ tt start anonymous_replica
+```
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/config.yaml
@@ -0,0 +1,34 @@
+credentials:
+  users:
+    replicator:
+      password: 'topsecret'
+      roles: [replication]
+
+iproto:
+  advertise:
+    peer:
+      login: replicator
+
+replication:
+  failover: manual
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        leader: instance001
+        instances:
+          instance001:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3301'
+          instance002:
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3302'
+          instance003:
+            replication:
+              anon: true
+            iproto:
+              listen:
+              - uri: '127.0.0.1:3303'
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica/instances.yml
@@ -0,0 +1,3 @@
+instance001:
+instance002:
+instance003:
diff --git a/doc/dev_guide/internals/iproto/keys.rst b/doc/dev_guide/internals/iproto/keys.rst
@@ -229,7 +229,7 @@ General replication
         *   -   :ref:`IPROTO_BALLOT_IS_ANON <internals-iproto-keys-ballot>`
             -   0x05 |br| MP_BOOL
             -   True if the replica is anonymous.
-                Corresponds to :ref:`box.cfg.replication_anon <cfg_replication-replication_anon>`.
+                Corresponds to :ref:`replication.anon <configuration_reference_replication_anon>`.
                 Since :doc:`2.7.1 </release/2.7.1>`
 
         *   -   :ref:`IPROTO_BALLOT_IS_BOOTED <internals-iproto-keys-ballot>`

diff --git a/doc/dev_guide/internals/iproto/replication.rst b/doc/dev_guide/internals/iproto/replication.rst
@@ -45,7 +45,7 @@ General
         *   -   IPROTO_FETCH_SNAPSHOT
             -   0x45
             -   Fetch the master's snapshot and start anonymous replication.
-                See :ref:`replication_anon <cfg_replication-replication_anon>`
+                See :ref:`replication.anon <configuration_reference_replication_anon>`
 
         *   -   IPROTO_REGISTER
             -   0x46

diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst
@@ -2841,6 +2841,37 @@ The ``replication`` section defines configuration parameters related to :ref:`re
 
 .. confval:: replication.anon
 
+    Whether to make the current instance act as an anonymous replica.
+    Anonymous replicas are read-only and can be used, for example, for backups.
+
+    To make the specified instance act as an anonymous replica, set ``replication.anon`` to ``true``:
+
+    ..  literalinclude:: /code_snippets/snippets/replication/instances.enabled/anonymous_replica/config.yaml
+        :language: yaml
+        :start-at: instance003
+        :end-at: anon: true
+        :dedent:
+
+    You can find the full example on GitHub: `anonymous_replica <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/replication/instances.enabled/anonymous_replica>`_.
+
+    Anonymous replicas are not displayed in the :ref:`box.info.replication <box_info_replication>` section.
+    You can check their status using :ref:`box.info.replication_anon() <box_info_replication-anon>`.
+
+    While anonymous replicas are read-only, you can write data to replication-local and temporary spaces (:ref:`created <box_schema-space_create>` with ``is_local = true`` and ``temporary = true``, respectively).
+    Given that changes to replication-local spaces are allowed, an anonymous replica might increase the ``0`` component of the :ref:`vclock <box_introspection-box_info>` value.
+
+    Here are the limitations of having anonymous replicas in a replica set:
+
+    *   A replica set must contain at least one non-anonymous instance.
+    *   An anonymous replica can't be configured as a writable instance by setting :ref:`database.mode <configuration_reference_database_mode>` to ``rw`` or making it a leader using :ref:`<replicaset_name>.leader <configuration_reference_replicasets_name_leader>`.
+    *   If :ref:`replication.failover <configuration_reference_replication_failover>` is set to ``election``, an anonymous replica can have :ref:`replication.election_mode <configuration_reference_replication_election_mode>` set to ``off`` only.
+    *   If :ref:`replication.failover <configuration_reference_replication_failover>` is set to ``supervised``, an external failover coordinator doesn't consider anonymous replicas when selecting a bootstrap or replica set leader.
+
+    ..  NOTE::
+
+        Anonymous replicas are not registered in the :ref:`_cluster <box_space-cluster>` table.
+        This means that there is no :ref:`limitation <limitations_replicas>` on the number of anonymous replicas in a replica set.
+
     |
     | Type: boolean
     | Default: ``false``

diff --git a/doc/reference/reference_lua/box_info/replication_anon.rst b/doc/reference/reference_lua/box_info/replication_anon.rst
@@ -8,7 +8,7 @@ box.info.replication_anon()
 
 .. function:: replication_anon()
 
-    List all the :ref:`anonymous replicas <cfg_replication-replication_anon>`
+    List all the :ref:`anonymous replicas <configuration_reference_replication_anon>`
     following the instance.
 
     The output is similar to the one produced by ``box.info.replication`` with
@@ -24,32 +24,26 @@ box.info.replication_anon()
 
     **Example:**
 
-    .. code-block:: tarantoolsession
-
-      tarantool> box.info.replication_anon
-      ---
-      - count: 2
-      ...
-
-      tarantool> box.info.replication_anon()
-      ---
-      - 3a6a2cfb-7e47-42f6-8309-7a25c37feea1:
-          id: 0
-          uuid: 3a6a2cfb-7e47-42f6-8309-7a25c37feea1
-          lsn: 0
-          downstream:
-            status: follow
-            idle: 0.76203499999974
-            vclock: {1: 1}
-        f58e4cb0-e0a8-42a1-b439-591dd36c8e5e:
-          id: 0
-          uuid: f58e4cb0-e0a8-42a1-b439-591dd36c8e5e
-          lsn: 0
-          downstream:
-            status: follow
-            idle: 0.0041349999992235
-            vclock: {1: 1}
-      ...
+    ..  code-block:: tarantoolsession
+
+        anonymous_replica:instance001> box.info.replication_anon
+        ---
+        - count: 1
+        ...
+
+        anonymous_replica:instance001> box.info.replication_anon()
+        ---
+        - 44237cb4-de83-4347-b6db-46274b940acf:
+            id: 0
+            uuid: 44237cb4-de83-4347-b6db-46274b940acf
+            lsn: 0
+            downstream:
+              status: follow
+              idle: 0.81613899999866
+              vclock: {1: 7}
+              lag: 0
+            name: null
+        ...
 
     Notice that anonymous replicas hide their ``lsn`` from the others, so an
     anonymous replica ``lsn`` will always be reported as zero, even if an anonymous