server compat and setup cluster pages (#913)

iamfortune · torcolvin · web-flow · commit 201ce819e586 · 2025-09-04T17:40:56.000+01:00
* server compat and setup cluster pages

* updated to reflect changes and style guide compliance

* style guide compliance in older docs page

* Update modules/deploy/pages/setting-up-dr-cluster.adoc

Co-authored-by: Tor Colvin &lt;tor.colvin@couchbase.com&gt;

* Update modules/server-compatibility/pages/server-compatibility-xdcr.adoc

Co-authored-by: Tor Colvin &lt;tor.colvin@couchbase.com&gt;

* Move SGW 4.0+ requirement to top of active-active DR section

---------

Co-authored-by: Tor Colvin &lt;tor.colvin@couchbase.com&gt;
diff --git a/modules/ROOT/assets/images/xdcr-active-active-replication.png b/modules/ROOT/assets/images/xdcr-active-active-replication.png
diff --git a/modules/deploy/pages/setting-up-dr-cluster.adoc b/modules/deploy/pages/setting-up-dr-cluster.adoc
@@ -19,6 +19,7 @@ include::ROOT:partial$_set_page_context.adoc[]
 :image-sgw-xdcr-dr-same-regn-in-recovery: sgw-xdcr-dr-same-regn-in-recovery.png
 :image-sgw-xdcr-dr-diff-regn-setup: sgw-xdcr-dr-diff-regn-setup.png
 :image-sgw-xdcr-dr-diff-regn-in-recovery: sgw-xdcr-dr-diff-regn-in-recovery.png
+:image-xdcr-active-active-replication: xdcr-active-active-replication.png
 
 //  end::page-attributes[]
 
@@ -35,38 +36,74 @@ include::ROOT:partial$_show_page_header_block.adoc[]
 == Introduction
 
 {server-xdcr--xref} (XDCR) replicates data between two or more autonomous Couchbase Server clusters.
-It serves an important role in supporting Disaster Recovery (DR) and Data Migration, even where Sync Gateway is the normal replicator of choice for mobile data.
+It plays an important role in supporting Disaster Recovery (DR) and Data Migration, even where Sync Gateway is the normal replicator of choice for mobile data.
 
 
 == Recommended Deployment Models
 
+
+=== Zero Downtime Active-Active Disaster Recovery
+// tag::zero-downtime-active-active[]
+
+This model provides zero-downtime disaster recovery using bi-directional XDCR between two active mobile clusters.
+This requires running Sync Gateway 4.0+ on both sides of the active-active XDCR setup.
+Both clusters remain operational, with seamless fail-over through load balancer switching.
+You must configure both clusters with `import_docs=true`.
+
+.Set Up
+To set up zero-downtime disaster recovery:
+
+. Configure bi-directional XDCR between the Primary and disaster recovery clusters. +
+Enable automatic filtering of cluster specific metadata.
+. Deploy Sync Gateway in active mode on both clusters.
+. Configure users, roles, and databases independently on both clusters. +
+XDCR replicates documents and attachments, but you must configure users, roles, and databases separately on each cluster.
+. Configure your load balancer to route traffic primarily to the Primary cluster.
+. Verify replication health between the two active clusters.
+
+[#fig-dr-active-active-setup]
+.DR Cluster Setup (Active-Active)
+image::ROOT:{image-xdcr-active-active-replication}[,{std-image-size}]
+
+
+.Activation
+To activate disaster recovery:
+
+. Update load balancer configuration to redirect traffic to the disaster recovery cluster. +
+This process requires no Sync Gateway service interruption.
+. Verify disaster recovery cluster is handling traffic properly.
+. Maintain bi-directional replication for recovery preparedness. +
+The original primary becomes the new DR cluster automatically and requires no manual XDCR reconfiguration.
+
+// end::zero-downtime-active-active[]
+
 === Clusters in Same Region
 // tag::clusters-in-same-region[]
 
-This model caters for situations where the Active and Disaster Recovery clusters are in the same region or data center -- see: <<fig-dr-same-regn>>.
-It includes an optional optimization step, which will ensure that there is no downtime during the activation stage.
+This model caters for situations where the Active and Disaster Recovery clusters are in the same region or datacenter -- see: <<fig-dr-same-regn>>.
+It includes an optional optimization step, which confirms that there is no downtime during the activation stage.
 
 .Set Up
 To set up and maintain a disaster recovery cluster:
 
-. [_Optional step -- for optimization_] Connect Sync Gateway to the Disaster Recovery cluster just long enough to create indexes.
-Having everything reindexed lowers switching costs. +
-If you skip this test, you will incur latency when Sync Gateway is switched to the Disaster Recovery cluster and Sync Gateway rebuilds its indexes.
+. [*Optional step -- for optimization*] Start Sync Gateway with `offline: true` in the Disaster Recovery cluster to asynchronously create indexes.
+Creating all indexes beforehand reduces switching costs. +
+If you skip this test, you'll incur latency when Sync Gateway switches to the Disaster Recovery cluster and Sync Gateway rebuilds its indexes.
 . Connect Sync Gateway to your Primary cluster.
-. Initiate the *unidirectional* XDCR from the Primary cluster to the Disaster Recovery cluster.
+. Start the *unidirectional* XDCR from the Primary cluster to the Disaster Recovery cluster.
 
 [#fig-dr-same-regn]
 .DR Cluster Setup (Clusters in Same Regions)
 image::ROOT:{image-sgw-xdcr-dr-same-regn-setup}[,{std-image-size}]
 
 .Activation
-When you are ready to switch to Disaster Recovery operations:
+When you're ready to switch to Disaster Recovery operations:
 
 . Stop the replication (XDCR) from the Primary cluster to Disaster Recovery cluster.
-. *When XDCR is stopped:* Switch the Load Balancer to point to the Sync Gateway on the Disaster Recovery cluster.
-This maintains the deployment of Sync Gateway at only one end of the XDCR replication.
+. *After you stop XDCR:* Switch the Load Balancer to point to the Sync Gateway on the Disaster Recovery cluster.
+This approach keeps the deployment of Sync Gateway at only 1 end of the XDCR replication.
 . Promote the Disaster Recovery cluster to Primary and the *old* Primary to Disaster Recovery.
-. Flush all replicated buckets in the Primary cluster; as a precaution against any spurious writes coming into the Primary cluster that had not been replicated when XDCR was stopped.
+. Flush all replicated buckets in the Primary cluster as a precaution against any spurious writes that enter the Primary cluster and XDCR fails to replicate when you stop it.
 . Reverse the XDCR to replicate from the newly promoted Primary to the old Primary to set up a new Backup.
 
 [#fig-dr-same-regn-in-recovery]
@@ -75,38 +112,36 @@ image::ROOT:{image-sgw-xdcr-dr-same-regn-in-recovery}[,{std-image-size}]
 
 // end::clusters-in-same-region[]
 
-
 === Clusters in Different Regions or Data Centers
 // tag::clusters-in-diff-region[]
 
 This model caters for situations where the Active and Disaster Recovery clusters are in different regions or data centers.
-Although the model has a separate Sync Gateway cluster attached to the Disaster Recovery cluster, it maintains the deployment of Sync Gateway at only one end of the XDCR replication.
-The optional optimization step will ensure that there is no downtime during the activation stage.
+Although the model has a separate Sync Gateway cluster attached to the Disaster Recovery cluster, this approach keeps the deployment of Sync Gateway at only 1 end of the XDCR replication.
+The optional optimization step confirms that there is no downtime during the activation stage.
 
 
 .Set Up
 To set up and maintain a disaster recovery cluster - see: <<fig-dr-diff-regn-setup>>:
 
-. [_Optional step -- for optimization_] Turn on _Sync Gateway_ in the Disaster Recovery cluster just long enough to create indexes.
-Having everything re-indexed lowers switching costs. +
-If you skip this test, you will incur latency when Sync Gateway is switched to the Disaster Recovery cluster and Sync Gateway rebuilds its indexes.
-. [_Critical step_] Turn off *all* the Sync Gateways in the Disaster Recovery cluster.
-. Initiate the *unidirectional* XDCR from the Primary cluster to the Disaster Recovery cluster.
+. [*Optional step -- for optimization*] Start Sync Gateway with `offline: true` in the Disaster Recovery cluster to asynchronously create indexes.
+If you skip this test, you'll incur latency when you switch Sync Gateway to the Disaster Recovery cluster and Sync Gateway rebuilds its indexes.
+. [*Critical step*] Turn off *all* the Sync Gateways in the Disaster Recovery cluster.
+. Start the *unidirectional* XDCR from the Primary cluster to the Disaster Recovery cluster.
 
 [#fig-dr-diff-regn-setup]
 .DR Cluster Setup (Clusters in Different Regions)
 image::ROOT:{image-sgw-xdcr-dr-diff-regn-setup}[,{std-image-size}]
 
 
 .Activation
-When you are ready to switch to Disaster Recovery operations -- see: <<fig-dr-diff-regn-in-recovery>>:
+When you're ready to switch to Disaster Recovery operations -- see: <<fig-dr-diff-regn-in-recovery>>:
 
 . Stop Sync Gateway on the Primary cluster
 . Stop the replication (XDCR) from the Primary cluster to the Disaster Recovery cluster.
-. Ensure that any and all Load Balancer(s) are updated to direct all traffic to the new Sync Gateway cluster(s).
-. Turn on the Sync Gateway cluster(s) in the Disaster Recovery cluster.
-. Promote the Disaster Recovery cluster to be the *new* Primary cluster, and make the *old* Primary cluster the *new* Disaster Recovery cluster
-. Flush all replicated buckets in the  Primary cluster; as a precaution against any spurious writes coming into the Primary cluster that had not been replicated when XDCR was stopped.
+. Verify that any and all Load Balancer updates to direct all traffic to the new Sync Gateway clusters.
+. Turn on the Sync Gateway cluster in the Disaster Recovery cluster.
+. Assign the Disaster Recovery cluster to be the *new* Primary cluster, and make the *old* Primary cluster the *new* Disaster Recovery cluster.
+. Flush all replicated buckets in the Primary cluster as a precaution against any spurious writes coming into the Primary cluster that XDCR did not replicate when you stopped it.
 . Reverse the original XDCR to replicate from the newly promoted Primary to the old Primary, to set up a new Backup.
 
 [#fig-dr-diff-regn-in-recovery]
diff --git a/modules/server-compatibility/pages/server-compatibility-xdcr.adoc b/modules/server-compatibility/pages/server-compatibility-xdcr.adoc
@@ -15,6 +15,7 @@ include::ROOT:partial$_set_page_context.adoc[]
 // BEGIN -- Page Attributes
 :image-xdcr-data-replication-to-read-only: xdcr-data-replication-to-read-only.png
 :image-icr-active-mobile-sync: icr-active-mobile-sync.png
+:image-xdcr-active-active-replication: xdcr-active-active-replication.png
 // END -- Page Attributes
 
 
@@ -43,18 +44,18 @@ Here we provide details on how XDCR feature relates to the {cbm} ecosystem.
 
 
 If you need to sync mobile clusters, you should use Inter-Sync Gateway replication -- see: {sync-inter-syncgateway-overview--xref}.
-It was designed to keep mobile clusters in different data centers in sync.
+It's designed to keep mobile clusters in different data centers in sync.
 The ideal use-case being the need to replicate edge clusters containing active Sync{nbsp}Gateway nodes between geographically separate cloud-based Sync Gateway deployments.
-A typical architecture for this use case is shown in <<icr-active-mobile>>.
+<<icr-active-mobile>> shows a typical architecture for this use case.
 
-Inter-Sync Gateway replication provides bi-directional read/write replications that ensure:
+Inter-Sync Gateway replication provides bi-directional read/write replications that make sure:
 
-* Cluster specific security is observed; by invoking the appropriate Sync Function.
-* The integrity of security history is maintained.
-Historical access rules are held and maintained in the Sync Gateway metadata.
+* Sync Gateway observes cluster-specific security by invoking the appropriate Sync Function.
+* Sync Gateway maintains the integrity of security history.
+Sync Gateway holds and maintains historical access rules in its metadata.
 This history is necessary to consistently handle the revocation of access grants.
-* A consistent Revision Id is used across all clusters, allowing clients to identify a revision regardless of the cluster it is on.
-* Cluster-specific _sync documents are not replicated to other mobile clusters
+* All clusters use a consistent Revision Id, allowing clients to identify a revision regardless of which cluster it's on.
+* Cluster-specific `_sync` documents are not replicated to other mobile clusters
 
 [[icr-active-mobile]]
 .Active-to-active mobile synchronization
@@ -70,7 +71,11 @@ XDCR replicates all of Sync Gateway’s metadata (_sync xattr) along with associ
 
 Your default preference for the replication of {cbm} changes should always be to use inter-Sync{nbsp}Gateway replication.
 
-XDCR can be useful though in use-cases where the entire dataset from a source bucket is replicated to a target bucket. This could include categories such as active standby, disaster recovery, data migration and _lift-and-shift_ cases in hybrid cloud.
+XDCR proves useful in use-cases where you replicate the entire dataset from a source bucket to a target bucket.
+These categories include active standby, disaster recovery, data migration and _lift-and-shift_ cases in hybrid cloud.
+
+
+=== Unidirectional XDCR
 
 In all these categories you should run XDCR in unidirectional mode, deploying Sync Gateway only at one end of the XDCR-replicated bucket (source, or target) -- see: <<ex-xdcr-data-repl>>.
 
@@ -79,22 +84,52 @@ In all these categories you should run XDCR in unidirectional mode, deploying Sy
 ====
 In this example XDCR deployment:
 
-* XDCR is run unidirectionally.
-It pushes data from the primary data center to the secondary data centers, where it is pulled by Sync Gateway for downstream clients.
+* XDCR runs unidirectionally.
+It pushes data from the primary datacenter to the secondary datacenter, where it's pulled by Sync Gateway for downstream clients.
 * Sync Gateway, although deployed at both ends of the XDCR replication, crucially is in *read-only* mode at the target end.
 
 .XDCR Replication
 image::ROOT:{image-xdcr-data-replication-to-read-only}[,std-image-size]
 ====
 
+=== Bi-directional Active-Active XDCR
+
+Sync Gateway supports bi-directional replication using XDCR between two active mobile clusters.
+This enables active-active deployments where both clusters can process writes simultaneously.
+
+TIP: Verify that you installed Couchbase Server 7.6.5 or later and configured your Sync Gateway nodes with `shared_bucket_access=true` and `import_docs=true`
+
+Bi-directional XDCR allows for both clusters to process writes simultaneously, with automatic conflict resolution.
+The setup supports different sync functions between clusters and provides unified replication for both mobile and non-mobile documents.
+
+[#ex-xdcr-bi-data-repl]
+.Bi-directional XDCR Replication
+====
+In this example XDCR deployment:
+
+* XDCR runs bi-directionally between two active mobile clusters.
+Both clusters can simultaneously process writes from Sync Gateway clients and replicate changes to each other.
+* Both clusters deploy Sync Gateway in active mode, enabling full read-write operations.
+Automatic conflict resolution ensures data consistency across clusters.
+* Clients can switch between clusters seamlessly without data loss, as both clusters maintain synchronized datasets.
+
+.XDCR Replication
+image::ROOT:{image-xdcr-active-active-replication}[,std-image-size]
+
+====
+
 [#lbl-prov-drc]
 == Disaster Recovery Scenario
 
 In a Disaster Recovery scenario XDCR serves an important role in setting-up target mobile clusters.
 
 Here XDCR supports Disaster Recovery and Data Migration.
-Even though Sync Gateway is the operational replicator of choice for mobile data, it is only ever deployed at one end of the unidirectional XDCR replication.
+Even though Sync Gateway is the operational replicator of choice for mobile data, it's only ever deployed at one end of the unidirectional XDCR replication.
+
+
+=== Zero Downtime Active-Active Disaster Recovery
 
+include::deploy:setting-up-dr-cluster.adoc[tags=zero-downtime-active-active]
 
 === Clusters in Same Region
 
