From 20f9e3425a7ae0f51e64d57d2b2a886e00c1d71d Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Wed, 15 Apr 2026 16:39:30 +0530 Subject: [PATCH 1/6] initial-draft-of-xdcr-cng --- modules/ROOT/nav.adoc | 1 + .../xdcr-support-for-cng.adoc | 434 ++++++++++++++++++ 2 files changed, 435 insertions(+) create mode 100644 modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index c6db029fd3..a1ef759981 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -88,6 +88,7 @@ include::third-party:partial$nav.adoc[] **** xref:learn:clusters-and-availability/xdcr-conflict-logging-feature.adoc[XDCR Conflict Logging] ***** xref:learn:clusters-and-availability/xdcr-viewing-conflict-logs.adoc[Viewing Conflict Logs] **** xref:learn:clusters-and-availability/xdcr-active-active-sgw.adoc[XDCR Active-Active with Sync Gateway] + **** xref:learn:clusters-and-availability/xdcr-support-for-cng.adoc[XDCR Support for Cloud Native Gateway] *** xref:learn:clusters-and-availability/groups.adoc[Server Group Awareness] * xref:learn:security/security-overview.adoc[Security] ** xref:learn:security/authentication.adoc[Authentication] diff --git a/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc new file mode 100644 index 0000000000..df0e1fcfd8 --- /dev/null +++ b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc @@ -0,0 +1,434 @@ += XDCR Support for Cloud Native Gateway +:description: pass:q[Learn how to configure and use XDCR with Cloud Native Gateway to replicate data across Couchbase clusters using gRPC over HTTPS.] +:page-edition: Enterprise Edition +:page-toclevels: 3 + +[abstract] +{description} + +Couchbase Server 8.1 introduces XDCR (Cross Data Center Replication) support for Cloud Native Gateway (CNG). +This feature allows XDCR to replicate data to a target cluster through its CNG interface, using gRPC over HTTPS ports instead of direct node-to-node Couchbase TCP connections. + +This document covers the concepts, configuration, usage, and behavior of XDCR over CNG for Couchbase Server administrators and operators. + +NOTE: This document does not cover Cloud Native Gateway installation. +For CNG installation instructions, see the installation instructions for Cloud Native Gateway *_available as a separate download to run with Couchbase Server 8.1 and above (DOC-13917)._* + +IMPORTANT: This feature is available in Enterprise Edition only. +It's not available in Community Edition. + +== Cloud Native Gateway in Couchbase + +The Couchbase Cloud Native Gateway (CNG) provides a gRPC interface to Couchbase services so that Couchbase clients do not need to be aware of cluster topology details. +CNG uses a set of RPC network endpoints based on gRPC over HTTP/2, an efficient binary wire protocol suited to the high performance of Couchbase Server. + +CNG allows the details of a cluster to be hidden behind a single service endpoint. +Applications and clients connect to a single hostname and port and are load-balanced across that service. +Cloud Native Gateway handles cluster topology changes transparently, so nothing changes within the cluster itself when clients connect through CNG. + +== Deploying CNG + +In Kubernetes environments, Cloud Native Gateway is deployed as a sidecar image alongside each Couchbase Server node. +The sidecar is managed by the Couchbase Autonomous Operator (CAO). +Kubernetes load balancers and OpenShift routes can be configured to expose the CNG service to clients outside the cluster. + +On Capella, Cloud Native Gateway will be available to enable per cluster. +When CNG is enabled on a Capella cluster, XDCR from a self-managed source cluster can replicate to the Capella cluster using the CNG address. + +== Using CNG for XDCR + +Couchbase clients, including XDCR, are smart clients that are cluster topology-aware and connect directly to the node where data is located. +In cloud environments, this requires exposing multiple ports on every node across an entire cluster, which creates significant complexity and imposes strict limitations in the following scenarios: + +* OpenShift environments: +OpenShift Routes and Kubernetes Ingress objects only support HTTP/HTTPS traffic. +Without CNG, XDCR cannot use these standard networking mechanisms, which are the recommended approaches for exposing cluster services in OpenShift. +* Private Link environments: +Cloud Service Provider (CSP) private link services impose strict limits on the number of ports that can be exposed, and the configuration required for direct XDCR node-to-node connections is complex and difficult to maintain. +* General Kubernetes and cloud networking: +Any network service or proxy that only supports HTTP/HTTPS or gRPC will work naturally with CNG, whereas direct XDCR connections require custom TCP port configuration that is environment-specific and fragile. + +CNG allows the entire XDCR connection to flow over a single HTTPS port using gRPC, eliminating topology exposure and simplifying all of the above networking scenarios. + +== CNG for Incoming Connections + +CNG fronts incoming connections to a cluster. +When a target cluster has CNG deployed, incoming XDCR connections from a source cluster can connect through CNG. +However, outgoing connections from a source cluster do not go through CNG. + +NOTE: For bi-directional XDCR using CNG, both clusters must have CNG installed, since each cluster acts as a target for traffic from the other. + +== Version and Environment Requirements + +=== Version Requirements + +The following version requirements apply to XDCR over CNG: + +[cols="1,1,2",options="header"] +|=== +|Replication Role |Component |Requirement + +|Source cluster +|Couchbase Server +|Version 8.1 (Totoro) or later + +|Source cluster +|Cloud Native Gateway +|Not required on source cluster + +|Target cluster +|Couchbase Server +|Any version that supports CNG (earlier versions are supported as target; however, both clusters must be 8.1+ for bi-directional CNG replication) + +|Target cluster +|Cloud Native Gateway +|Version with XDCR support (required) +|=== + +IMPORTANT: The source cluster must be running Couchbase Server 8.1 or later, as it must understand the CNG/gRPC protocol. +The target cluster must have a compatible version of CNG installed that supports XDCR. + +=== One-Way vs Two-Way Replication Requirements + +[cols="1,2,2",options="header"] +|=== +|Replication Type |Source Cluster Requirements |Target Cluster Requirements + +|One-way (unidirectional) +|Server version 8.1 or later. +CNG not required. +|CNG with XDCR support installed. +Server version can be earlier than 8.1 (for example, 7.6.x or 8.0.x). + +|Two-way (bidirectional) +|Server version 8.1 or later. +CNG with XDCR support installed (acting as a target). +|Server version 8.1 or later. +CNG with XDCR support installed (acting as a target). +|=== + +NOTE: In a bi-directional setup, each cluster is both a source and a target. +As a source, it must be running Server 8.1 or later. +As a target, it must have CNG installed. + +== Limitations + +The following limitations apply to the initial release of XDCR support for CNG: + +* Buckets that have `enableCrossClusterVersioning` set to `true` (HLV-enabled buckets) cannot be used with XDCR over CNG. +Attempting to create a replication with an HLV-enabled bucket will return an error. +HLV support for CNG is planned for Phase 2. +* The `xdcrDiffer` tool does not support CNG in Phase 1. +Attempting to use `xdcrDiffer` with a CNG remote reference will return an error. +`xdcrDiffer` support for CNG is planned for Phase 2. + +== Working of XDCR Over CNG + +=== Connection Model + +When a remote cluster reference is created with the `couchbase2://` prefix, XDCR on the source cluster connects to the target cluster through its CNG interface. +Data is transmitted over HTTPS using the gRPC protocol instead of direct vBucket-to-vBucket TCP connections. + +The CNG on the target cluster handles load balancing and routes traffic to the appropriate nodes and vBuckets within the target cluster. +Cluster topology changes in the target cluster are handled by CNG transparently. +The source cluster XDCR process does not need to track or update topology maps for the target. + +=== Protocol Switching + +XDCR supports dynamically switching a remote cluster reference between CNG-based and direct node-to-node connections. +When the remote reference for an existing replication is updated to change between these two protocols, for example, switching from `couchbase2://` to a direct hostname or vice versa, the replication resumes using the existing XDCR checkpoints. +No data needs to be re-replicated from the beginning. + +This means that in a multi-cluster topology, individual replication legs can use CNG while others use direct connections. + +NOTE: Updating the remote reference's hostname or protocol may require updating the root certificate if the CNG certificate differs from the direct cluster certificate. + +=== Error Handling + +XDCR returns clear error messages in the following scenarios: + +* If `couchbase2://` is specified but CNG is not installed or available on the target cluster, XDCR returns an error stating that CNG was not found on the target and advises trying without the `couchbase2://` prefix if direct node-to-node connections are available. +* If `couchbase2://` is not specified but direct node-to-node connections are failing and the target cluster has CNG enabled, XDCR returns an error suggesting that the user try the `couchbase2://` prefix. + +XDCR does not attempt to automatically infer or switch the protocol. +The user is responsible for choosing the correct prefix and for acting on the error messages. + +== Configuring XDCR Over CNG + +=== Creating a Remote Cluster Reference + +To configure XDCR to replicate to a target cluster through its CNG interface, specify the target cluster hostname using the `couchbase2://` prefix when creating the remote cluster reference. + +=== Hostname Prefix + +Use the `couchbase2://` prefix with the target cluster CNG hostname or load balancer address: + +[source,text] +---- +couchbase2:// +---- + +IMPORTANT: Use the prefix `couchbase2://`, not `couchbases2://`. +There is no `s` after `couchbase` in the prefix. + +=== Security and Encryption + +TLS is required when using CNG. +Set the security type to full encryption when creating or updating the remote reference: + +[source,text] +---- +secureType=full +---- + +NOTE: Half-secure (`secureType=half`) is not supported for CNG remote references. +Full encryption must be used. + +=== Certificate + +You must provide the root CNG certificate for the target cluster. +This certificate is used to verify the CNG endpoint on the target cluster. + +The username and password, or client certificate and key, for the remote reference are the same credentials used for direct XDCR connections. +These are the Server credentials for the target cluster, not CNG-specific credentials. + +=== REST API + +Use the following REST API endpoints to create or update a remote cluster reference for CNG: + +[cols="1,1",options="header"] +|=== +|Operation |API Endpoint + +|Create remote reference +|`POST /pools/default/remoteClusters` + +|Update remote reference +|`POST /pools/default/remoteClusters/{REFERENCE_NAME}` + +|List remote references +|`GET /pools/default/remoteClusters` +|=== + +.Example: Create a remote reference to a CNG target cluster +[source,bash] +---- +curl -u Administrator:password -X POST \ + http://source-cluster:8091/pools/default/remoteClusters \ + -d "name=my-cng-target" \ + -d "hostname=couchbase2://target-cng-loadbalancer.example.com" \ + -d "username=admin" \ + -d "password=target-password" \ + -d "secureType=full" \ + --data-urlencode "certificate=" +---- + +When `GET /pools/default/remoteClusters` is called, a remote reference using CNG can be identified by the `couchbase2://` prefix in the `hostname` field. + +=== CLI + +The `couchbase-cli xdcr-setup` command can be used to create or manage remote references for CNG. +Specify the `couchbase2://` prefix in the `--xdcr-cluster-address` parameter. + +[source,bash] +---- +couchbase-cli xdcr-setup -c source-cluster:8091 \ + -u Administrator -p password \ + --create \ + --xdcr-cluster-name my-cng-target \ + --xdcr-cluster-address couchbase2://target-cng-loadbalancer.example.com \ + --xdcr-username admin --xdcr-password target-password \ + --xdcr-secure-connection full \ + --xdcr-certificate /path/to/root-cng-cert.pem +---- + +NOTE: Verify that the version of `couchbase-cli` supports `couchbase2://` in the cluster address. +No additional flags specific to CNG are required beyond using the correct prefix. + +=== Couchbase Web Console (UI) + +When creating or editing an XDCR remote reference in the Couchbase Web Console, enter the CNG hostname with the `couchbase2://` prefix in the hostname field. +The UI displays a Cloud Native Gateway label for any remote reference whose hostname uses the `couchbase2://` prefix. + +Ensure that the Encryption setting is set to Full (TLS) for CNG remote references. + +== Deployment Use Cases + +=== Self-Managed to Self-Managed + +Two self-managed clusters, both running Couchbase Server 8.1, can replicate data using XDCR over CNG. +This enables bi-directional replication without requiring direct node-to-node network access between the clusters. + +Typical requirements for this scenario: + +* Both clusters run Couchbase Server 8.1 or later. +* Both clusters have a compatible version of CNG installed. +* Remote references are created using the `couchbase2://` prefix and the CNG load balancer address for each target cluster. +* Remote references are configured with full TLS encryption (`secureType=full`). +* The clusters do not require shared DNS, alternate addresses, or direct node-to-node network connectivity. + +=== OpenShift Environment + +CNG is the recommended approach for using XDCR with clusters deployed on Red Hat OpenShift. +OpenShift Routes and Kubernetes Ingress are limited to HTTP/HTTPS traffic. +XDCR data can be sent over HTTPS only through CNG. + +In an OpenShift deployment managed by the Couchbase Autonomous Operator (CAO), CNG is deployed as a sidecar to each Couchbase Server node. +Administrators define OpenShift routes that expose the CNG service to external clients. +XDCR from any Couchbase cluster can replicate into the OpenShift-hosted cluster by creating a remote reference with the `couchbase2://` prefix and the route address. + +NOTE: CAO manages the installation and lifecycle of CNG in Kubernetes and OpenShift environments. +When creating XDCR remote references in a CAO-managed cluster, the `couchbase2://` prefix and CNG address should be allowed in the CAO XDCR configuration. + +=== Self-Managed to Capella Over Public Network + +A self-managed cluster running Server 8.1 can replicate data to a Capella cluster using CNG over the public internet. +To use this scenario: + +* The Capella cluster must have CNG enabled and an XDCR-compatible version of CNG installed. +* On the Capella cluster, add all source cluster node IP addresses to the Allowed IP Addresses list. +* On the source cluster, create a remote reference using the `couchbase2://` prefix and the public Capella CNG hostname. +* The source cluster does not require alternate addresses. + +=== Capella to Self-Managed Over Public Network + +A Capella cluster running Server 8.1 can replicate data to a self-managed cluster using CNG over the public internet. +To use this scenario: + +* The self-managed target cluster must have CNG installed and enabled. +* On the self-managed target cluster, allow connections from the Capella cluster node IP addresses. +* On the Capella cluster, create a remote reference using the `couchbase2://` prefix and the self-managed cluster CNG hostname. + +=== Self-Managed to Capella Over Private Link + +XDCR from a self-managed cluster to a Capella cluster over a private link using CNG requires: + +* The self-managed source cluster running Couchbase Server 8.1 or later. +* The Capella cluster having CNG enabled with XDCR support. +* A CNG-based private endpoint configured on the Capella cluster. +* The source cluster creating a remote reference using the `couchbase2://` prefix and the private endpoint CNG address. + +NOTE: Capella infrastructure support for CNG-based private endpoints is not required to ship simultaneously with this Server feature. +However, once both are available, self-managed-to-Capella XDCR over private link using CNG will be fully supported. + +== Performance Considerations + +=== Steady-State Replication Performance + +During steady-state replication, ongoing mutations only, the performance of XDCR over CNG is comparable to that of direct node-to-node XDCR. +The gRPC protocol over HTTPS provides efficient data transfer at steady state. + +=== Initial Replication Performance + +When the full dataset is first replicated from the source to the target cluster, initial replication, there can be a significant performance reduction when using CNG compared to direct XDCR. +This reduction can be as high as 50% in throughput compared to direct node-to-node XDCR. + +When direct node-to-node XDCR is an option, consider this performance impact when deciding whether to use CNG for the initial replication phase. + +=== Performance Baselines + +Performance baselines for XDCR over CNG should be established using the following test configurations: + +* Average initial XDCR rate (items/sec), 1-node to 1-node, 2 source nozzles, 4 target nozzles, 1 bucket x 100M items x 1 KB +* Average initial XDCR rate (items/sec), 2-node to 2-node, 2 source nozzles, 4 target nozzles, 1 bucket x 100M items x 1 KB +* Average initial XDCR rate (items/sec), 5-node to 5-node, 2 source nozzles, 4 target nozzles, 1 bucket x 250M items x 1 KB +* 95th percentile replication lag (ms), 5-node to 5-node, 2 source nozzles, 4 target nozzles, 1 bucket x 1B items x 1 KB, 40K updates/sec + +== Reference + +=== Connection Strings + +[cols="1,2",options="header"] +|=== +|Prefix |Usage + +|`couchbase2://` +|Specifies a CNG/gRPC connection to the target cluster. +Required when replicating via CNG. + +|`couchbase://` +|Standard Couchbase connection string format. +Supported as a connection string only, not for CCCP. +No change to existing behavior. + +|`couchbases://` +|Standard Couchbase TLS connection string format. +Supported as a connection string only, not for CCCP. +No change to existing behavior. +|=== + +=== Parameters for Remote Reference + +[cols="1,1,2",options="header"] +|=== +|Parameter |Required for CNG |Description + +|`hostname` +|Yes +|CNG hostname or load balancer address, prefixed with `couchbase2://` + +|`secureType` +|Yes +|Must be set to `full`. +Half encryption is not supported for CNG. + +|`certificate` +|Yes +|Root CNG certificate for the target cluster. + +|`username` +|Yes +|Target cluster Server username, same as for direct XDCR. + +|`password` +|Yes +|Target cluster Server password, same as for direct XDCR. +|=== + +=== Phase 1 vs. Phase 2 Summary + +[cols="1,1,1",options="header"] +|=== +|Feature |Phase 1 (8.1) |Phase 2 + +|XDCR over CNG (gRPC/HTTPS) +|Supported +|Supported + +|`couchbase2://` prefix +|Supported +|Supported + +|Full TLS encryption +|Required +|Required + +|Protocol switching (CNG to direct and back) +|Supported +|Supported + +|Checkpoint preservation on protocol switch +|Supported +|Supported + +|HLV (`enableCrossClusterVersioning`) buckets +|Not supported (error returned) +|Planned + +|`xdcrDiffer` support +|Not supported (error returned) +|Planned +|=== + +=== Edition Support + +[cols="1,1",options="header"] +|=== +|Edition |XDCR over CNG Support + +|Enterprise Edition +|Supported + +|Community Edition +|Not supported (XDCR is not available in Community Edition) +|=== From b419a30e0b003cd41083c60e6cc279cdef6db661 Mon Sep 17 00:00:00 2001 From: rao-shwe Date: Thu, 7 May 2026 18:05:05 +0530 Subject: [PATCH 2/6] minor edits --- .../xdcr-support-for-cng.adoc | 72 ------------------- 1 file changed, 72 deletions(-) diff --git a/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc index df0e1fcfd8..c8dc51a69a 100644 --- a/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc +++ b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc @@ -12,7 +12,6 @@ This feature allows XDCR to replicate data to a target cluster through its CNG i This document covers the concepts, configuration, usage, and behavior of XDCR over CNG for Couchbase Server administrators and operators. NOTE: This document does not cover Cloud Native Gateway installation. -For CNG installation instructions, see the installation instructions for Cloud Native Gateway *_available as a separate download to run with Couchbase Server 8.1 and above (DOC-13917)._* IMPORTANT: This feature is available in Enterprise Edition only. It's not available in Community Edition. @@ -311,29 +310,6 @@ XDCR from a self-managed cluster to a Capella cluster over a private link using NOTE: Capella infrastructure support for CNG-based private endpoints is not required to ship simultaneously with this Server feature. However, once both are available, self-managed-to-Capella XDCR over private link using CNG will be fully supported. -== Performance Considerations - -=== Steady-State Replication Performance - -During steady-state replication, ongoing mutations only, the performance of XDCR over CNG is comparable to that of direct node-to-node XDCR. -The gRPC protocol over HTTPS provides efficient data transfer at steady state. - -=== Initial Replication Performance - -When the full dataset is first replicated from the source to the target cluster, initial replication, there can be a significant performance reduction when using CNG compared to direct XDCR. -This reduction can be as high as 50% in throughput compared to direct node-to-node XDCR. - -When direct node-to-node XDCR is an option, consider this performance impact when deciding whether to use CNG for the initial replication phase. - -=== Performance Baselines - -Performance baselines for XDCR over CNG should be established using the following test configurations: - -* Average initial XDCR rate (items/sec), 1-node to 1-node, 2 source nozzles, 4 target nozzles, 1 bucket x 100M items x 1 KB -* Average initial XDCR rate (items/sec), 2-node to 2-node, 2 source nozzles, 4 target nozzles, 1 bucket x 100M items x 1 KB -* Average initial XDCR rate (items/sec), 5-node to 5-node, 2 source nozzles, 4 target nozzles, 1 bucket x 250M items x 1 KB -* 95th percentile replication lag (ms), 5-node to 5-node, 2 source nozzles, 4 target nozzles, 1 bucket x 1B items x 1 KB, 40K updates/sec - == Reference === Connection Strings @@ -384,51 +360,3 @@ Half encryption is not supported for CNG. |Yes |Target cluster Server password, same as for direct XDCR. |=== - -=== Phase 1 vs. Phase 2 Summary - -[cols="1,1,1",options="header"] -|=== -|Feature |Phase 1 (8.1) |Phase 2 - -|XDCR over CNG (gRPC/HTTPS) -|Supported -|Supported - -|`couchbase2://` prefix -|Supported -|Supported - -|Full TLS encryption -|Required -|Required - -|Protocol switching (CNG to direct and back) -|Supported -|Supported - -|Checkpoint preservation on protocol switch -|Supported -|Supported - -|HLV (`enableCrossClusterVersioning`) buckets -|Not supported (error returned) -|Planned - -|`xdcrDiffer` support -|Not supported (error returned) -|Planned -|=== - -=== Edition Support - -[cols="1,1",options="header"] -|=== -|Edition |XDCR over CNG Support - -|Enterprise Edition -|Supported - -|Community Edition -|Not supported (XDCR is not available in Community Edition) -|=== From 773dc189943622442de5e142a69c6d30ccb110ee Mon Sep 17 00:00:00 2001 From: supritha-kumar Date: Fri, 10 Jul 2026 15:46:14 +0530 Subject: [PATCH 3/6] Updated xdcr-support-for-cng.adoc updated with port info and edits --- .../xdcr-support-for-cng.adoc | 56 +++++++++++-------- 1 file changed, 32 insertions(+), 24 deletions(-) diff --git a/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc index c8dc51a69a..f32cd18bab 100644 --- a/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc +++ b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc @@ -1,12 +1,11 @@ = XDCR Support for Cloud Native Gateway -:description: pass:q[Learn how to configure and use XDCR with Cloud Native Gateway to replicate data across Couchbase clusters using gRPC over HTTPS.] +:description: pass:q[Learn how to configure and use XDCR with Cloud Native Gateway (CNG) to replicate data across Couchbase clusters using gRPC over HTTPS.] :page-edition: Enterprise Edition :page-toclevels: 3 [abstract] {description} -Couchbase Server 8.1 introduces XDCR (Cross Data Center Replication) support for Cloud Native Gateway (CNG). This feature allows XDCR to replicate data to a target cluster through its CNG interface, using gRPC over HTTPS ports instead of direct node-to-node Couchbase TCP connections. This document covers the concepts, configuration, usage, and behavior of XDCR over CNG for Couchbase Server administrators and operators. @@ -59,6 +58,8 @@ NOTE: For bi-directional XDCR using CNG, both clusters must have CNG installed, == Version and Environment Requirements +This section outlines the version and environment requirements for deploying and using XDCR over Cloud Native Gateway. + === Version Requirements The following version requirements apply to XDCR over CNG: @@ -69,7 +70,7 @@ The following version requirements apply to XDCR over CNG: |Source cluster |Couchbase Server -|Version 8.1 (Totoro) or later +|the next major release or later |Source cluster |Cloud Native Gateway @@ -77,14 +78,14 @@ The following version requirements apply to XDCR over CNG: |Target cluster |Couchbase Server -|Any version that supports CNG (earlier versions are supported as target; however, both clusters must be 8.1+ for bi-directional CNG replication) +|Any version that supports CNG (earlier versions are supported as target; however, both clusters must support the next major release or later for bi-directional CNG replication) |Target cluster |Cloud Native Gateway |Version with XDCR support (required) |=== -IMPORTANT: The source cluster must be running Couchbase Server 8.1 or later, as it must understand the CNG/gRPC protocol. +IMPORTANT: The source cluster must be running the next major release or later, as it must understand the CNG/gRPC protocol. The target cluster must have a compatible version of CNG installed that supports XDCR. === One-Way vs Two-Way Replication Requirements @@ -94,39 +95,39 @@ The target cluster must have a compatible version of CNG installed that supports |Replication Type |Source Cluster Requirements |Target Cluster Requirements |One-way (unidirectional) -|Server version 8.1 or later. +|The next major release. CNG not required. |CNG with XDCR support installed. -Server version can be earlier than 8.1 (for example, 7.6.x or 8.0.x). +Server version can be earlier than the next major release(for example, 7.6.x or 8.0.x). |Two-way (bidirectional) -|Server version 8.1 or later. +|The next major release. CNG with XDCR support installed (acting as a target). -|Server version 8.1 or later. +|The next major release. CNG with XDCR support installed (acting as a target). |=== NOTE: In a bi-directional setup, each cluster is both a source and a target. -As a source, it must be running Server 8.1 or later. +As a source, it must be running the next major release. As a target, it must have CNG installed. == Limitations The following limitations apply to the initial release of XDCR support for CNG: -* Buckets that have `enableCrossClusterVersioning` set to `true` (HLV-enabled buckets) cannot be used with XDCR over CNG. +* *HLV-enabled buckets*: Buckets that have `enableCrossClusterVersioning` set to `true` cannot be used with XDCR over CNG. Attempting to create a replication with an HLV-enabled bucket will return an error. -HLV support for CNG is planned for Phase 2. -* The `xdcrDiffer` tool does not support CNG in Phase 1. -Attempting to use `xdcrDiffer` with a CNG remote reference will return an error. -`xdcrDiffer` support for CNG is planned for Phase 2. +* *xdcrDiffer*: The `xdcrDiffer` tool does not support CNG in Phase 1. Attempting to use `xdcrDiffer` with a CNG remote reference will return an error. +* *Conflict Logging*: Conflict logging is not supported for XDCR over CNG connections. +* *Sync Gateway Interop*: XDCR over CNG does not support replication scenarios involving Sync Gateway. == Working of XDCR Over CNG +This section explains how XDCR communicates with the target cluster through Cloud Native Gateway, including the connection model, protocol switching capabilities, and error handling mechanisms. + === Connection Model -When a remote cluster reference is created with the `couchbase2://` prefix, XDCR on the source cluster connects to the target cluster through its CNG interface. -Data is transmitted over HTTPS using the gRPC protocol instead of direct vBucket-to-vBucket TCP connections. +When a remote cluster reference is created with the `couchbase2://` prefix, XXDCR transmits data over HTTPS using the gRPC protocol. By default, this traffic uses port *18098* on the Cloud Native Gateway. The CNG on the target cluster handles load balancing and routes traffic to the appropriate nodes and vBuckets within the target cluster. Cluster topology changes in the target cluster are handled by CNG transparently. @@ -154,6 +155,9 @@ The user is responsible for choosing the correct prefix and for acting on the er == Configuring XDCR Over CNG +This section explains how to set up XDCR to replicate data through Cloud Native Gateway. +You will learn how to create remote cluster references, configure security settings, and use the available tools. + === Creating a Remote Cluster Reference To configure XDCR to replicate to a target cluster through its CNG interface, specify the target cluster hostname using the `couchbase2://` prefix when creating the remote cluster reference. @@ -168,7 +172,7 @@ couchbase2:// ---- IMPORTANT: Use the prefix `couchbase2://`, not `couchbases2://`. -There is no `s` after `couchbase` in the prefix. +The prefix does not contain an `s` after `couchbase`. === Security and Encryption @@ -249,18 +253,20 @@ No additional flags specific to CNG are required beyond using the correct prefix When creating or editing an XDCR remote reference in the Couchbase Web Console, enter the CNG hostname with the `couchbase2://` prefix in the hostname field. The UI displays a Cloud Native Gateway label for any remote reference whose hostname uses the `couchbase2://` prefix. -Ensure that the Encryption setting is set to Full (TLS) for CNG remote references. +Make sure that the Encryption setting is set to Full (TLS) for CNG remote references. == Deployment Use Cases +This section describes common deployment scenarios for XDCR over Cloud Native Gateway, including self-managed clusters, Kubernetes and OpenShift environments, and hybrid deployments with Capella. + === Self-Managed to Self-Managed -Two self-managed clusters, both running Couchbase Server 8.1, can replicate data using XDCR over CNG. +Two self-managed clusters, both running the next major release, can replicate data using XDCR over CNG. This enables bi-directional replication without requiring direct node-to-node network access between the clusters. Typical requirements for this scenario: -* Both clusters run Couchbase Server 8.1 or later. +* Both clusters run the next major release or later. * Both clusters have a compatible version of CNG installed. * Remote references are created using the `couchbase2://` prefix and the CNG load balancer address for each target cluster. * Remote references are configured with full TLS encryption (`secureType=full`). @@ -281,7 +287,7 @@ When creating XDCR remote references in a CAO-managed cluster, the `couchbase2:/ === Self-Managed to Capella Over Public Network -A self-managed cluster running Server 8.1 can replicate data to a Capella cluster using CNG over the public internet. +A self-managed cluster running the next major release can replicate data to a Capella cluster using CNG across the public Internet. To use this scenario: * The Capella cluster must have CNG enabled and an XDCR-compatible version of CNG installed. @@ -291,7 +297,7 @@ To use this scenario: === Capella to Self-Managed Over Public Network -A Capella cluster running Server 8.1 can replicate data to a self-managed cluster using CNG over the public internet. +A Capella cluster running the next major release can replicate data to a self-managed cluster using CNG across the public Internet. To use this scenario: * The self-managed target cluster must have CNG installed and enabled. @@ -302,7 +308,7 @@ To use this scenario: XDCR from a self-managed cluster to a Capella cluster over a private link using CNG requires: -* The self-managed source cluster running Couchbase Server 8.1 or later. +* The self-managed source cluster running the next major release or later. * The Capella cluster having CNG enabled with XDCR support. * A CNG-based private endpoint configured on the Capella cluster. * The source cluster creating a remote reference using the `couchbase2://` prefix and the private endpoint CNG address. @@ -312,6 +318,8 @@ However, once both are available, self-managed-to-Capella XDCR over private link == Reference +This section provides reference information for configuring and using XDCR over Cloud Native Gateway, including connection string formats and remote reference parameters. + === Connection Strings [cols="1,2",options="header"] From ccc00dc9d12b65c71c3f2227a1798d237d5c349d Mon Sep 17 00:00:00 2001 From: supritha-kumar Date: Fri, 10 Jul 2026 15:58:15 +0530 Subject: [PATCH 4/6] Updated create-xdcr-reference.adoc updated with securetype is full, a=documented switching between direct and CNG, and added that hostname can accept couchbase2:// prefixed connection --- .../pages/manage-xdcr/create-xdcr-reference.adoc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc b/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc index eee8667a3e..573142f1c7 100644 --- a/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc +++ b/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc @@ -22,12 +22,25 @@ The possible roles are _Full_, and _XDCR Inbound_ (either for the individual buc + Note that the administrator setting up XDCR must have the _Full Admin_, _Cluster Admin_ or _XDCR Admin_ role, on the source cluster. +* When creating a remote cluster reference for a target cluster fronted by Cloud Native Gateway (CNG), use the `couchbase2://` prefix in the hostname field. +This instructs XDCR to use gRPC over HTTPS instead of direct node-to-node TCP connections. +The default port for CNG-based XDCR connections is *18098*. +Ensure your load balancer or gateway is configured to route traffic on this port. + * Whether the the connection between source and target clusters will be managed securely, and if so, by what secure methodology. Corresponding TLS certificates may need to be provided. Securing a connection is described in detail in xref:manage:manage-xdcr/secure-xdcr-replication.adoc[Secure a Replication]. Once the reference has been saved, it can be used to specify a target cluster, when an XDCR replication is created. +IMPORTANT: When using the `couchbase2://` connection scheme, you must set the secureType parameter to full. +Connections using `couchbase2://` with any other security setting (such as half or none) will be rejected. +This ensures that XDCR traffic is encrypted over HTTPS as required by the CNG architecture. + +[#switching-protocols] +== Switching Protocols +You can dynamically switch an existing remote cluster reference between direct (couchbase://) and CNG (couchbase2://) connections. Updating the protocol does not require deleting and recreating the reference. XDCR will resume using existing checkpoints, ensuring data consistency is maintained during the transition. Note: If the CNG certificate differs from the direct cluster certificate, you may need to update the root certificate associated with the reference. + [#examples-on-this-page-create-reference] == Examples on This Page From a4444a1415635df4164c7f3c978058bb963d5df8 Mon Sep 17 00:00:00 2001 From: supritha-kumar Date: Thu, 16 Jul 2026 16:45:53 +0530 Subject: [PATCH 5/6] Updated xdcr-support-for-cng.adoc incorporated PM comments --- .../xdcr-support-for-cng.adoc | 110 +++++++----------- 1 file changed, 45 insertions(+), 65 deletions(-) diff --git a/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc index f32cd18bab..08ed0c3233 100644 --- a/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc +++ b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc @@ -1,12 +1,12 @@ = XDCR Support for Cloud Native Gateway -:description: pass:q[Learn how to configure and use XDCR with Cloud Native Gateway (CNG) to replicate data across Couchbase clusters using gRPC over HTTPS.] +:description: pass:q[Learn how to configure and use XDCR with Cloud Native Gateway (CNG) to replicate data across Couchbase clusters using gRPC instead of using direct node-to-node connections.] :page-edition: Enterprise Edition :page-toclevels: 3 [abstract] {description} -This feature allows XDCR to replicate data to a target cluster through its CNG interface, using gRPC over HTTPS ports instead of direct node-to-node Couchbase TCP connections. +This feature allows XDCR to replicate data to a target cluster through its CNG interface, using gRPC over HTTPS instead of direct node-to-node Couchbase connections. This document covers the concepts, configuration, usage, and behavior of XDCR over CNG for Couchbase Server administrators and operators. @@ -30,29 +30,26 @@ In Kubernetes environments, Cloud Native Gateway is deployed as a sidecar image The sidecar is managed by the Couchbase Autonomous Operator (CAO). Kubernetes load balancers and OpenShift routes can be configured to expose the CNG service to clients outside the cluster. -On Capella, Cloud Native Gateway will be available to enable per cluster. -When CNG is enabled on a Capella cluster, XDCR from a self-managed source cluster can replicate to the Capella cluster using the CNG address. - == Using CNG for XDCR Couchbase clients, including XDCR, are smart clients that are cluster topology-aware and connect directly to the node where data is located. -In cloud environments, this requires exposing multiple ports on every node across an entire cluster, which creates significant complexity and imposes strict limitations in the following scenarios: +In cloud environments, this requires exposing multiple ports on every node across an entire cluster, which creates significant complexity and friction in the following scenarios: -* OpenShift environments: +* OpenShift and Kubernetes environments: OpenShift Routes and Kubernetes Ingress objects only support HTTP/HTTPS traffic. -Without CNG, XDCR cannot use these standard networking mechanisms, which are the recommended approaches for exposing cluster services in OpenShift. +With CNG, instead of a custom solution to expose all of the cluster's nodes externally, you can use the standard approaches for exposing cluster services like OpenShift Routes and Kubernetes LoadBalancer and only expose CNG. +For more information, see xref:docs-operator:concept-cloud-native-gateway.adoc. * Private Link environments: -Cloud Service Provider (CSP) private link services impose strict limits on the number of ports that can be exposed, and the configuration required for direct XDCR node-to-node connections is complex and difficult to maintain. -* General Kubernetes and cloud networking: -Any network service or proxy that only supports HTTP/HTTPS or gRPC will work naturally with CNG, whereas direct XDCR connections require custom TCP port configuration that is environment-specific and fragile. +Cloud Service Provider (CSP) private link services expect a single load-balanced resource, and the configuration required for direct XDCR node-to-node connections is complex and difficult to maintain. +* General cloud networking: +Any network interface or proxy that supports HTTPS or gRPC will work naturally with CNG, whereas direct XDCR connections require custom solutions that will be environment-specific and fragile. -CNG allows the entire XDCR connection to flow over a single HTTPS port using gRPC, eliminating topology exposure and simplifying all of the above networking scenarios. +CNG allows the XDCR connection to flow over a single gRPC interface, eliminating the need to expose the target cluster topology and simplifying all of the above networking scenarios. == CNG for Incoming Connections CNG fronts incoming connections to a cluster. When a target cluster has CNG deployed, incoming XDCR connections from a source cluster can connect through CNG. -However, outgoing connections from a source cluster do not go through CNG. NOTE: For bi-directional XDCR using CNG, both clusters must have CNG installed, since each cluster acts as a target for traffic from the other. @@ -82,11 +79,11 @@ The following version requirements apply to XDCR over CNG: |Target cluster |Cloud Native Gateway -|Version with XDCR support (required) +|CNG version 1.2.1 or later |=== -IMPORTANT: The source cluster must be running the next major release or later, as it must understand the CNG/gRPC protocol. -The target cluster must have a compatible version of CNG installed that supports XDCR. +IMPORTANT: The Couchbase Server on the source cluster must be running the next major release or later, as the XDCR in the Server must understand the gRPC protocol and support Cloud Native Gateway as a target. +The target cluster must have Cloud Native Gateway version 1.2.1 or later, as 1.2.1 includes XDCR support. === One-Way vs Two-Way Replication Requirements @@ -98,7 +95,7 @@ The target cluster must have a compatible version of CNG installed that supports |The next major release. CNG not required. |CNG with XDCR support installed. -Server version can be earlier than the next major release(for example, 7.6.x or 8.0.x). +Server version can be any version that works with CNG 1.2.1. |Two-way (bidirectional) |The next major release. @@ -107,9 +104,9 @@ CNG with XDCR support installed (acting as a target). CNG with XDCR support installed (acting as a target). |=== -NOTE: In a bi-directional setup, each cluster is both a source and a target. +NOTE: In a bi-directional setup, each cluster is both an XDCR source and a target. As a source, it must be running the next major release. -As a target, it must have CNG installed. +As a target, it must have CNG version 1.2.1 or later installed. == Limitations @@ -118,8 +115,8 @@ The following limitations apply to the initial release of XDCR support for CNG: * *HLV-enabled buckets*: Buckets that have `enableCrossClusterVersioning` set to `true` cannot be used with XDCR over CNG. Attempting to create a replication with an HLV-enabled bucket will return an error. * *xdcrDiffer*: The `xdcrDiffer` tool does not support CNG in Phase 1. Attempting to use `xdcrDiffer` with a CNG remote reference will return an error. -* *Conflict Logging*: Conflict logging is not supported for XDCR over CNG connections. -* *Sync Gateway Interop*: XDCR over CNG does not support replication scenarios involving Sync Gateway. +* *Conflict Logging*: Conflict logging is not supported for XDCR over CNG since Conflict logging requires cross cluster versioning to be enabled on the bucket. +* *Sync Gateway Interop*: Mobile buckets (Sync Gateway / App Services) are only supported for one-way (uni-directional) XDCR replication with CNG since bi-directional support requires cross cluster versioning to be enabled on the bucket. == Working of XDCR Over CNG @@ -127,7 +124,7 @@ This section explains how XDCR communicates with the target cluster through Clou === Connection Model -When a remote cluster reference is created with the `couchbase2://` prefix, XXDCR transmits data over HTTPS using the gRPC protocol. By default, this traffic uses port *18098* on the Cloud Native Gateway. +When a remote cluster reference is created with the `couchbase2://` prefix, XDCR transmits data over HTTPS using the gRPC protocol. By default, this traffic uses port *18098* on the Cloud Native Gateway. The CNG on the target cluster handles load balancing and routes traffic to the appropriate nodes and vBuckets within the target cluster. Cluster topology changes in the target cluster are handled by CNG transparently. @@ -136,10 +133,10 @@ The source cluster XDCR process does not need to track or update topology maps f === Protocol Switching XDCR supports dynamically switching a remote cluster reference between CNG-based and direct node-to-node connections. -When the remote reference for an existing replication is updated to change between these two protocols, for example, switching from `couchbase2://` to a direct hostname or vice versa, the replication resumes using the existing XDCR checkpoints. +When the remote reference for an existing replication is updated to change between these two protocols, for example, switching from `couchbase2://` to a direct cluster hostname or vice versa, the replication resumes using the existing XDCR checkpoints. No data needs to be re-replicated from the beginning. -This means that in a multi-cluster topology, individual replication legs can use CNG while others use direct connections. +This means that in a multi-cluster XDCR topology, some replication legs can use CNG while others use direct node-to-node connections. NOTE: Updating the remote reference's hostname or protocol may require updating the root certificate if the CNG certificate differs from the direct cluster certificate. @@ -164,7 +161,9 @@ To configure XDCR to replicate to a target cluster through its CNG interface, sp === Hostname Prefix -Use the `couchbase2://` prefix with the target cluster CNG hostname or load balancer address: +As shown below, use the couchbase2:// prefix with the target cluster CNG hostname or load balancer address. +If the CNG is using the default gRPC port, 18098, you do not need to add the port to the hostname. +However, if the CNG is using a different port, then, you must add the port to the hostname. [source,text] ---- @@ -189,8 +188,9 @@ Full encryption must be used. === Certificate -You must provide the root CNG certificate for the target cluster. -This certificate is used to verify the CNG endpoint on the target cluster. +You must provide the root TLS certificate for the Cloud Native Gateway (CNG). +When the remote reference is for the CNG, the TLS certificate must be the certificate for the CNG. +This certificate is used to verify the CNG endpoint. The username and password, or client certificate and key, for the remote reference are the same credentials used for direct XDCR connections. These are the Server credentials for the target cluster, not CNG-specific credentials. @@ -226,7 +226,10 @@ curl -u Administrator:password -X POST \ --data-urlencode "certificate=" ---- -When `GET /pools/default/remoteClusters` is called, a remote reference using CNG can be identified by the `couchbase2://` prefix in the `hostname` field. +When `GET /pools/default/remoteClusters` is called, a remote reference using CNG can be identified by the "remoteType": "cng". +For a remote reference to the remote cluster directly (for direct, node-to-node connections), it displays "remoteType": "cbcluster". + +NOTE: The REST API output will not have the "couchbase2://" prefix in the hostname. The UI will show the "couchbase2://" prefix in the hostname since the UI does not have any other way to indicate that the remote reference is for a Cloud Native Gateway. === CLI @@ -251,7 +254,6 @@ No additional flags specific to CNG are required beyond using the correct prefix === Couchbase Web Console (UI) When creating or editing an XDCR remote reference in the Couchbase Web Console, enter the CNG hostname with the `couchbase2://` prefix in the hostname field. -The UI displays a Cloud Native Gateway label for any remote reference whose hostname uses the `couchbase2://` prefix. Make sure that the Encryption setting is set to Full (TLS) for CNG remote references. @@ -267,16 +269,15 @@ This enables bi-directional replication without requiring direct node-to-node ne Typical requirements for this scenario: * Both clusters run the next major release or later. -* Both clusters have a compatible version of CNG installed. -* Remote references are created using the `couchbase2://` prefix and the CNG load balancer address for each target cluster. +* Both clusters have CNG version 1.2.1 or later installed. +* Remote references are created using the `couchbase2://` prefix and the hostname of the target Cloud Native Gateway. * Remote references are configured with full TLS encryption (`secureType=full`). -* The clusters do not require shared DNS, alternate addresses, or direct node-to-node network connectivity. +* The clusters do not require alternate addresses or direct node-to-node network connectivity. === OpenShift Environment -CNG is the recommended approach for using XDCR with clusters deployed on Red Hat OpenShift. -OpenShift Routes and Kubernetes Ingress are limited to HTTP/HTTPS traffic. -XDCR data can be sent over HTTPS only through CNG. +With Cloud Native Gateway (CNG), instead of a custom solution to expose all of the cluster's nodes externally, you can use the standard approaches for exposing cluster services like OpenShift Routes and Kubernetes LoadBalancer and only expose the CNG service outside of the k8s environment. +For more information, see xref:docs-operator:concept-cloud-native-gateway.adoc. In an OpenShift deployment managed by the Couchbase Autonomous Operator (CAO), CNG is deployed as a sidecar to each Couchbase Server node. Administrators define OpenShift routes that expose the CNG service to external clients. @@ -285,37 +286,15 @@ XDCR from any Couchbase cluster can replicate into the OpenShift-hosted cluster NOTE: CAO manages the installation and lifecycle of CNG in Kubernetes and OpenShift environments. When creating XDCR remote references in a CAO-managed cluster, the `couchbase2://` prefix and CNG address should be allowed in the CAO XDCR configuration. -=== Self-Managed to Capella Over Public Network - -A self-managed cluster running the next major release can replicate data to a Capella cluster using CNG across the public Internet. -To use this scenario: - -* The Capella cluster must have CNG enabled and an XDCR-compatible version of CNG installed. -* On the Capella cluster, add all source cluster node IP addresses to the Allowed IP Addresses list. -* On the source cluster, create a remote reference using the `couchbase2://` prefix and the public Capella CNG hostname. -* The source cluster does not require alternate addresses. - === Capella to Self-Managed Over Public Network -A Capella cluster running the next major release can replicate data to a self-managed cluster using CNG across the public Internet. +A Capella cluster running the next major release can replicate data to a self-managed cluster using CNG across the public network or private network using VPC Peering. To use this scenario: * The self-managed target cluster must have CNG installed and enabled. -* On the self-managed target cluster, allow connections from the Capella cluster node IP addresses. +* The self-managed CNG must allow connections from the Capella cluster nodes. * On the Capella cluster, create a remote reference using the `couchbase2://` prefix and the self-managed cluster CNG hostname. -=== Self-Managed to Capella Over Private Link - -XDCR from a self-managed cluster to a Capella cluster over a private link using CNG requires: - -* The self-managed source cluster running the next major release or later. -* The Capella cluster having CNG enabled with XDCR support. -* A CNG-based private endpoint configured on the Capella cluster. -* The source cluster creating a remote reference using the `couchbase2://` prefix and the private endpoint CNG address. - -NOTE: Capella infrastructure support for CNG-based private endpoints is not required to ship simultaneously with this Server feature. -However, once both are available, self-managed-to-Capella XDCR over private link using CNG will be fully supported. - == Reference This section provides reference information for configuring and using XDCR over Cloud Native Gateway, including connection string formats and remote reference parameters. @@ -328,16 +307,16 @@ This section provides reference information for configuring and using XDCR over |`couchbase2://` |Specifies a CNG/gRPC connection to the target cluster. -Required when replicating via CNG. +When using this prefix, the default CNG gRPC port is 18098. If you are not using the default port, the port must be specified in the hostname. |`couchbase://` -|Standard Couchbase connection string format. -Supported as a connection string only, not for CCCP. +|Standard non-encrypted Couchbase Server connection string format. +When using this prefix, the default port is 8091. If you are not using this default port, the port must be specified in the hostname. No change to existing behavior. |`couchbases://` |Standard Couchbase TLS connection string format. -Supported as a connection string only, not for CCCP. +When using this prefix, the default port is 18091. If you are not using this default port, the port must be specified in the hostname. No change to existing behavior. |=== @@ -349,7 +328,8 @@ No change to existing behavior. |`hostname` |Yes -|CNG hostname or load balancer address, prefixed with `couchbase2://` +|CNG hostname or load balancer address, prefixed with `couchbase2://`. +The default CNG gRPC port is 18098. If you are not using the default port, then you must specify the port with the hostname. |`secureType` |Yes @@ -358,7 +338,7 @@ Half encryption is not supported for CNG. |`certificate` |Yes -|Root CNG certificate for the target cluster. +|Root TLS certificate for the CNG. |`username` |Yes From 4cbea3c0913919706a287c32b03144cf9d48e7f2 Mon Sep 17 00:00:00 2001 From: supritha-kumar Date: Thu, 16 Jul 2026 17:36:44 +0530 Subject: [PATCH 6/6] Updated create-xdcr-reference.adoc PM comments and some Vale changes --- .../manage-xdcr/create-xdcr-reference.adoc | 39 ++++++++++--------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc b/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc index 573142f1c7..e98f83c112 100644 --- a/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc +++ b/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc @@ -7,27 +7,28 @@ [#understanding-references] == Understanding References -A _reference_ is the registration, on the local cluster, of details that identify a target cluster for XDCR replication. +A `reference` is the registration, on the local cluster, of details that identify a target cluster for XDCR replication. The reference must contain the following details: * The name of the target cluster. * The IP address or hostname of a node within the target cluster. IPv4 and IPv6 both can be used: however, a valid IPv6 address must be enclosed within brackets (`[` and `]`). -Note that if the target cluster has an _alternate address_, this address can be used to identify the target cluster. +If the target cluster has an alternate address, this address can be used to identify the target cluster. See xref:learn:clusters-and-availability/connectivity.adoc#alternate-addresses[Alternate Addresses]. -* A username and password, associated on the target cluster with a role that allows one or more buckets to receive documents from an XDCR replication. -The possible roles are _Full_, and _XDCR Inbound_ (either for the individual bucket that will later be specified as the target bucket for the replication, or for all buckets on the target cluster). +* A username and password, associated on the target cluster with a role that allows 1 or more buckets to receive documents from an XDCR replication. +The possible roles are `Full`, and `XDCR Inbound` (either for the individual bucket that will later be specified as the target bucket for the replication, or for all buckets on the target cluster). + -Note that the administrator setting up XDCR must have the _Full Admin_, _Cluster Admin_ or _XDCR Admin_ role, on the source cluster. +The administrator setting up XDCR must have the `Full Admin`, `Cluster Admin` or `XDCR Admin` role, on the source cluster. * When creating a remote cluster reference for a target cluster fronted by Cloud Native Gateway (CNG), use the `couchbase2://` prefix in the hostname field. -This instructs XDCR to use gRPC over HTTPS instead of direct node-to-node TCP connections. -The default port for CNG-based XDCR connections is *18098*. -Ensure your load balancer or gateway is configured to route traffic on this port. +This instructs XDCR to use gRPC over HTTPS instead of direct node-to-node connections. +The default CNG gRPC port is *18098*. +If the target CNG is not using the default port, then, the remote reference hostname must include the port. +Make sure your load balancer or gateway is configured to route traffic on this port. -* Whether the the connection between source and target clusters will be managed securely, and if so, by what secure methodology. +* Whether the connection between source and target clusters will be managed securely, and if so, by what secure methodology. Corresponding TLS certificates may need to be provided. Securing a connection is described in detail in xref:manage:manage-xdcr/secure-xdcr-replication.adoc[Secure a Replication]. @@ -39,7 +40,10 @@ This ensures that XDCR traffic is encrypted over HTTPS as required by the CNG ar [#switching-protocols] == Switching Protocols -You can dynamically switch an existing remote cluster reference between direct (couchbase://) and CNG (couchbase2://) connections. Updating the protocol does not require deleting and recreating the reference. XDCR will resume using existing checkpoints, ensuring data consistency is maintained during the transition. Note: If the CNG certificate differs from the direct cluster certificate, you may need to update the root certificate associated with the reference. +You can dynamically switch an existing remote cluster reference between direct (couchbase:// or couchbases://) and CNG (couchbase2://) connections. +Updating the protocol does not require deleting and recreating the reference. +XDCR will resume using existing checkpoints, ensuring data consistency is maintained during the transition. +NOTE: If the CNG certificate differs from the direct cluster certificate, you may need to update the root certificate associated with the reference. [#examples-on-this-page-create-reference] == Examples on This Page @@ -47,7 +51,7 @@ You can dynamically switch an existing remote cluster reference between direct ( The examples in the subsections below show how to create the same reference; using the xref:manage:manage-xdcr/create-xdcr-reference.adoc#create-an-xdcr-reference-with-the-ui[UI], the xref:manage:manage-xdcr/create-xdcr-reference.adoc#create-an-xdcr-reference-with-the-cli[CLI], and the xref:manage:manage-xdcr/create-xdcr-reference.adoc#create-an-xdcr-reference-with-the-rest-api[REST API] respectively. The examples assume: -* Two clusters already exist; each containing a single node. +* 2 clusters already exist; each containing a single node. These are named after their IP addresses: `10.144.210.101` and `10.144.210.102`. * Each cluster contains a single bucket, which is the `travel-sample` bucket. @@ -101,7 +105,7 @@ With the exception of *Check Connection*, the fields in this dialog are explaine . For *Cluster Name*, provide a name for the target cluster: this name is for use on the _source_ cluster only, and so need not be identical to any name defined on the _target_ cluster. For *IP/Hostname*, specify the IP address (if appropriate, the _alternate address_), the hostname, or the _fully qualified domain-name_ of the target cluster: in this case, the IP address `10.144.210.102` is to be used. -(Note that if the IPv6 address family were being used, the IP address would need to be enclosed in square brackets.) +NOTE: If the IPv6 address family were being used, the IP address would need to be enclosed in square brackets. For *Username* and *Password*, specify those stated above. Do not, for the current example, check the `Enable Secure Connection` checkbox. The complete dialog appears as follows: @@ -137,8 +141,7 @@ image::manage-xdcr/xdcr-replications-screen-with-reference.png[,800,align=left] + The *Remote Clusters* panel now contains the reference you have defined. A new panel, entitled *Outgoing Replications*, appears immediately below the *Remote Clusters* panel. -It is currently empty, except for a notification explaining that no replications are yet defined. -Note that at the upper right of the *XDCR Replications* screen, a new tab has appeared, which is *ADD REPLICATION*. +It is empty, except for a notification explaining that no replications are yet defined. This concludes reference-definition. @@ -150,7 +153,7 @@ By left-clicking on the row for a particular, defined reference, buttons for edi image::manage-xdcr/deleteAndEditReferenceButtons.png[,800,align=left] Now, by left-clicking on the *Edit* and *Delete* buttons themselves, you can respectively edit (by means of the *Edit Remote Cluster* dialog, which is identical to the *Add Remote Cluster* dialog) and delete defined references. -Note that if a reference is already associated with a replication, you cannot delete the reference; nor can you modify its target IP address. +If a reference is already associated with a replication, you cannot delete the reference; nor can you modify its target IP address. However, you _can_ change the registered name of the target cluster, and you can change the security settings for the replication. [#create-an-xdcr-reference-with-the-cli] @@ -174,7 +177,7 @@ If successful, this provides the following response: SUCCESS: Cluster reference created ---- -Note that a complete list of references established for a cluster can be retrieved with the `xdcr-setup` command, used with the `list` option: +A complete list of references established for a cluster can be retrieved with the `xdcr-setup` command, used with the `list` option: ---- couchbase-cli xdcr-setup -c 10.144.210.101 \ @@ -182,7 +185,7 @@ couchbase-cli xdcr-setup -c 10.144.210.101 \ ---- The following is returned. -Note the `uuid` associated with the reference, which will be used later in the current section. +The `uuid` associated with the reference, which will be used later in the current section. ---- cluster name: 10.144.210.102 @@ -200,7 +203,7 @@ includes details on how to edit an existing reference. == Create an XDCR Reference with the REST API Starting from the scenario defined above, in xref:manage:manage-xdcr/create-xdcr-reference.adoc#examples-on-this-page-create-reference[Examples on This Page], the REST API's `POST /pools/default/remoteClusters` HTTP method and URI can be used to create an XDCR reference. -(Note that optionally, prior to creating the reference, connectivity between source and target clusters can be checked, by means of the methods and URI described in xref:rest-api:rest-xdcr-connection-precheck.adoc[Checking Connections].) +Optionally, prior to creating the reference, connectivity between source and target clusters can be checked, by means of the methods and URI described in xref:rest-api:rest-xdcr-connection-precheck.adoc[Checking Connections]. The reference is created as follows: