Skip to content

Commit 474ddff

Browse files
authored
More context to warning message (neo4j#551) (neo4j#619)
As per request Cherry-picked from neo4j#551
1 parent adb6360 commit 474ddff

File tree

1 file changed

+32
-3
lines changed

1 file changed

+32
-3
lines changed

modules/ROOT/pages/clustering/internals.adoc

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -182,11 +182,40 @@ If you are running a multi-data center cluster, then upstream strategies for bot
182182
Remember that for Read Replicas this also affects from where transactions are pulled.
183183
See more in xref:clustering-advanced/multi-data-center/configuration.adoc[Configure for multi-data center operations].
184184

185+
=== Using the Replica instance in case of failure
185186

186-
[WARNING]
187+
In case of failure (e.g. a partial failure of a cluster due to the loss of an instance, but not of the majority), you may transform a Read Replica instance into a Core instance as a way to restore the cluster's core availability.
188+
However, keep in mind that this is not advised as it could cause data loss and complications in the Raft group.
189+
190+
To avoid that, the _read_replica_ instance must not be initialized as a *single* instance, nor be introduced in a different or new cluster.
191+
This action would cause an override of the raft state, thus preventing the replica from successfully joining the targeted cluster.
192+
193+
After performing that change, follow these instructions to unbind the Replica instance and update the discovery configurations amongst cluster members:
194+
195+
. Ensure that the converted _read_replica_ currently belongs to the same cluster that it will be re-introduced back to, as a _core_.
196+
This can be done by performing `CALL dbms.cluster.overview()` and verifying the instance's address and cluster mode.
197+
198+
. Stop and unbind the _read_replica_ instance.
199+
200+
. Update the cluster mode configuration in _neo4j.conf_, from `dbms.mode=READ_REPLICA` to `dbms.mode=CORE`.
201+
202+
. Stop Neo4j on the removed core instances that are not intended to serve as core members.
203+
204+
. Unbind those instances from the cluster by performing `neo4j-admin unbind` while they are stopped.
205+
This action will prevent such instances from subsequently attempting to rejoin the running cluster.
206+
207+
At this point, the previous _read_replica_ (now _core_) instance may be introduced into the running cluster.
208+
To persist this change in the cluster's architecture, the following configuration updates are advised:
209+
210+
- On the previous _read_replica_ (now _core_) instance, set `causal_clustering.discovery_advertised_address` and `causal_clustering.discovery_listen_address` as appropriate.
211+
212+
- Update the `causal_clustering.initial_discovery_members` configuration with the currently valid list of discovery addresses for each member of the cluster.
213+
This should replace the addresses of any removed _core(s)_ with the discovery addresses of the previous _read_replica_ (now _core_) instance.
214+
+
215+
[NOTE]
187216
====
188-
* Do not transform a Read Replica into a Core.
189-
* Do not transform a Core into a Read Replica.
217+
In cases where `causal_clustering.discovery_type` is other than `LIST`, make sure to update the corresponding address resolution addresses records.
218+
For example, DNS A records for discovery types DNS and SRV, and any Kubernetes service address alternate to reflect the inclusion of the _read_replica_ discovery address.
190219
====
191220

192221
[[causal-clustering-on-disk-state]]

0 commit comments

Comments
 (0)