From e58bbf0ba3bd905c6cc9e0d75c6e78346ae30817 Mon Sep 17 00:00:00 2001 From: supritha-kumar Date: Tue, 17 Mar 2026 11:58:12 +0530 Subject: [PATCH 01/17] DOC-14105-Update Compatibility matrix to include 8.0 --- modules/backup-restore/pages/enterprise-backup-restore.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index 5524c2462c..58bd17d65b 100644 --- a/modules/backup-restore/pages/enterprise-backup-restore.adoc +++ b/modules/backup-restore/pages/enterprise-backup-restore.adoc @@ -120,6 +120,7 @@ Unless otherwise specified, backup and restore apply both to _local_ and to _clo [cols="5,3,3,3,3,3,3,3,3"] |=== | *cbbackupmgr version* +| *8.0* | *7.6* | *7.2* | *7.1* From 21ced854b2f5a038092a9597261a38c5a0dfbb8a Mon Sep 17 00:00:00 2001 From: Supritha Date: Tue, 17 Mar 2026 16:40:18 +0530 Subject: [PATCH 02/17] updated compatibility matrix --- .../pages/enterprise-backup-restore.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/modules/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index 58bd17d65b..4985810cfa 100644 --- a/modules/backup-restore/pages/enterprise-backup-restore.adoc +++ b/modules/backup-restore/pages/enterprise-backup-restore.adoc @@ -130,6 +130,17 @@ Unless otherwise specified, backup and restore apply both to _local_ and to _clo | *6.0.x* | *5.5.x* +| 8.0 +| ✓ +| ✓ +| ✓ +| ✓ +| ✓ +| +| +| + + | 7.6 | ✓ | ✓ From fc650fd70d3720ea1841a30f577db3f5457a8a63 Mon Sep 17 00:00:00 2001 From: Supritha Date: Tue, 24 Mar 2026 21:09:02 +0530 Subject: [PATCH 03/17] Updated compatibility matrix to include 8.0 and remove versions prior to 7.2. --- .../pages/enterprise-backup-restore.adoc | 94 +------------------ 1 file changed, 2 insertions(+), 92 deletions(-) diff --git a/modules/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index 4985810cfa..a6022b93d1 100644 --- a/modules/backup-restore/pages/enterprise-backup-restore.adoc +++ b/modules/backup-restore/pages/enterprise-backup-restore.adoc @@ -117,120 +117,30 @@ The following table lists the compatible cluster-versions for each version of `c Unless otherwise specified, backup and restore apply both to _local_ and to _cloud_ data. .Compatibility Requirements for Backup and Restore -[cols="5,3,3,3,3,3,3,3,3"] +[cols="5,3,3,3,"] |=== | *cbbackupmgr version* | *8.0* | *7.6* | *7.2* -| *7.1* -| *7.0* -| *6.6* -| *6.5.x* -| *6.0.x* -| *5.5.x* | 8.0 | ✓ | ✓ | ✓ -| ✓ -| ✓ -| -| -| - | 7.6 +| | ✓ | ✓ -| ✓ -| ✓ -| ✓ -| -| -| | 7.2 | -| ✓ -| ✓ -| ✓ -| ✓ -| -| -| - -| 7.1 -| | | ✓ -| ✓ -| ✓ -| ✓* -| -| - - -| 7.0 -| -| -| -| ✓ -| ✓ -| ✓* -| ✓* -| - - -| 6.6.0 and above -| -| -| -| -| ✓ -| ✓* -| ✓* -| ✓* - - -| 6.5 -| -| -| -| -| -| ✓ -| ✓ -| ✓ - - -| 6.0.x -| -| -| -| -| -| -| ✓ -| - - -| 5.5.x -| -| -| -| -| -| -| -| ✓ - |=== -+*+ For local backup only — _not_ for cloud. - .Restoring metadata and users **** * When restoring metadata to a newer Server version, From 36594003a13f528be0414073b7a315adf98f24c3 Mon Sep 17 00:00:00 2001 From: Supritha Date: Tue, 24 Mar 2026 21:10:52 +0530 Subject: [PATCH 04/17] corrected syntax of columns --- modules/backup-restore/pages/enterprise-backup-restore.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index a6022b93d1..9d4a2c6108 100644 --- a/modules/backup-restore/pages/enterprise-backup-restore.adoc +++ b/modules/backup-restore/pages/enterprise-backup-restore.adoc @@ -117,7 +117,7 @@ The following table lists the compatible cluster-versions for each version of `c Unless otherwise specified, backup and restore apply both to _local_ and to _cloud_ data. .Compatibility Requirements for Backup and Restore -[cols="5,3,3,3,"] +[cols="5,3,3,3"] |=== | *cbbackupmgr version* | *8.0* From 6dd1d63481e7cd6cde9b4dd07980b8b384a9a8a6 Mon Sep 17 00:00:00 2001 From: Supritha Date: Tue, 24 Mar 2026 21:29:24 +0530 Subject: [PATCH 05/17] Updated the text above the version compatibility table and removed example of 6.x --- modules/backup-restore/pages/enterprise-backup-restore.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index 9d4a2c6108..18d3e1a666 100644 --- a/modules/backup-restore/pages/enterprise-backup-restore.adoc +++ b/modules/backup-restore/pages/enterprise-backup-restore.adoc @@ -109,9 +109,8 @@ To prevent such corruption instances, you may be required to create multiple bac [#version-compatibility] == Version Compatibility -For 6.5 and all later versions, `cbbackupmgr` can be used to back up data either from a cluster running its own version, or from a cluster running a prior, _compatible_ version. -For example, the 6.6.0 tool can back up data from a cluster running 6.6.0, 6.5.x, 6.0.x, or 5.5.x. -It can also be used to restore _to_ any of those versions data previously backed up _from_ any of those versions. +For 7.2 and all later versions, you can use `cbbackupmgr` to back up data either from a cluster running its own version, or from a cluster running a prior, `compatible` version. + You can also use it to restore data to any of these versions from backups created on any of them. The following table lists the compatible cluster-versions for each version of `cbbackupmgr`. Unless otherwise specified, backup and restore apply both to _local_ and to _cloud_ data. @@ -141,6 +140,7 @@ Unless otherwise specified, backup and restore apply both to _local_ and to _clo |=== + .Restoring metadata and users **** * When restoring metadata to a newer Server version, From c4e75921720d3d413f3c808a45d7f028177df83a Mon Sep 17 00:00:00 2001 From: Supritha Date: Tue, 24 Mar 2026 21:57:11 +0530 Subject: [PATCH 06/17] updated minor changes and some Vale suggestions --- .../pages/enterprise-backup-restore.adoc | 28 +++++++++---------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/modules/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index 18d3e1a666..7b6f2908f8 100644 --- a/modules/backup-restore/pages/enterprise-backup-restore.adoc +++ b/modules/backup-restore/pages/enterprise-backup-restore.adoc @@ -15,9 +15,9 @@ which is available for both Couchbase Server _Enterprise Edition_ and Couchbase [NOTE] ==== -`cbbackupmgr` is _not_ backward compatible with backups created by means of `cbbackup`. +`cbbackupmgr` is not backward compatible with backups created by means of `cbbackup`. -In Couchbase Enterprise Server 7.2 and after, `cbbackupmgr` is available in the `Tools` package that must be downloaded. +In Couchbase Enterprise Server 7.2 and later, `cbbackupmgr` is available in the `Tools` package that must be downloaded. See xref:cli:cli-intro.adoc#server-tools-packages[Server Tools Packages]. ==== @@ -30,10 +30,10 @@ Administrators are therefore recommended to define plans for both https://en.wik All backup is stored in and recovered from a [.term]_Backup Repository_. In turn, a [.term]_Backup Repository_ is stored in a Backup Archive on the filesystem. -Each backup job in the [.term]_Backup Repository_ stores its backup in two ways: +Each backup job in the [.term]_Backup Repository_ stores its backup in 2 ways: -* All bucket data is stored in a small, secondary database. -* All bucket creation scripts and configuration files are stored on the file system, as files. +* You can store all bucket data in a small, secondary database. +* You can store all bucket creation scripts and configuration files on the filesystem, as files. === What's Backed Up @@ -64,7 +64,7 @@ NOTE: Backups that include users contain the user's hashed passwords. Other flags let you exclude specific metadata, or select a subset of data to back up. See xref:backup-restore:cbbackupmgr-config.adoc[cbbackupmgr config] for a list of the arguments you can use to control what `cbbackupmgr` backs up. -You can also use command line flags to control how the `cbbackupmgr restore` command restores data. +You can also use command line flags to control how the `cbbackupmgr restore` command restores data. For example, use `--overwrite-users` to have `cbbackupmgr` overwrite existing users and groups in the database if the backup contains a matching user or group. By default, `cbbackupmgr` does not overwrite existing users in the database. Instead, it restores just the users in the backup that do not exist in database. @@ -72,7 +72,7 @@ See xref:backup-restore:cbbackupmgr-restore.adoc[cbbackupmgr restore] for a list === Tool Locations -When installed as part of the Couchbase Server install, `cbbackupmgr` tool is stored with all other tools in the following _per platform_ locations: +When installed as part of the Couchbase Server install, `cbbackupmgr` tool is stored with all other tools in the following per platform locations: .Backup Tool Locations [cols="1,5"] @@ -102,14 +102,14 @@ Each of the subsequent, incremental backups take a fraction of the time taken by The backup archive is a directory that contains a set of backup repositories as well as logs for the backup client. The backup directory should be modified only by the backup client, and any modifications that are not done by that client might result in a corruption of backup data. -Only one backup client can access the backup archive at one time. +Only 1 backup client can access the backup archive at 1 time. If multiple instances of the backup client are running on the same archive at the same time, this might result in corruption. To prevent such corruption instances, you may be required to create multiple backup archives depending on your use case. [#version-compatibility] == Version Compatibility -For 7.2 and all later versions, you can use `cbbackupmgr` to back up data either from a cluster running its own version, or from a cluster running a prior, `compatible` version. +For 7.2 and later versions, you can use `cbbackupmgr` to back up data either from a cluster running its own version, or from a cluster running a prior, `compatible` version. You can also use it to restore data to any of these versions from backups created on any of them. The following table lists the compatible cluster-versions for each version of `cbbackupmgr`. @@ -141,15 +141,13 @@ Unless otherwise specified, backup and restore apply both to _local_ and to _clo |=== -.Restoring metadata and users -**** +== Restoring metadata and users + * When restoring metadata to a newer Server version, if the feature that the metadata applies to no longer exists in the newer Server version, then the metadata may not be restorable. -* If the user roles no longer exist in the version that you wish to restore to, then an error will be logged for the target user. +* If the user roles no longer exist in the version that you want to restore to, then an error is logged for the target user. -* In general, if you can upgrade _directly_ to the new version, then you should be able to restore the users. +* In general, if you can upgrade to the new version, then you should be able to restore the users. If you cannot upgrade directly, then restoring users may cause errors. For example, if some of the user roles no longer exist in the newer Server version. - -**** From bae91e13a6fe3c4dbc7985bc1c60a39aeabc250c Mon Sep 17 00:00:00 2001 From: Supritha Date: Mon, 6 Apr 2026 13:58:50 +0530 Subject: [PATCH 07/17] corrected an empty space - line 113 --- modules/backup-restore/pages/enterprise-backup-restore.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index 7b6f2908f8..b8e0d5e90a 100644 --- a/modules/backup-restore/pages/enterprise-backup-restore.adoc +++ b/modules/backup-restore/pages/enterprise-backup-restore.adoc @@ -110,7 +110,7 @@ To prevent such corruption instances, you may be required to create multiple bac == Version Compatibility For 7.2 and later versions, you can use `cbbackupmgr` to back up data either from a cluster running its own version, or from a cluster running a prior, `compatible` version. - You can also use it to restore data to any of these versions from backups created on any of them. +You can also use it to restore data to any of these versions from backups created on any of them. The following table lists the compatible cluster-versions for each version of `cbbackupmgr`. Unless otherwise specified, backup and restore apply both to _local_ and to _cloud_ data. From 20f9e3425a7ae0f51e64d57d2b2a886e00c1d71d Mon Sep 17 00:00:00 2001 From: Shwetha Rao Date: Wed, 15 Apr 2026 16:39:30 +0530 Subject: [PATCH 08/17] 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 09/17] 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 10/17] 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 11/17] 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 12/17] 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 13/17] 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: From c5f0ead9bab3557efb0b59bf48a6041adfa9e52e Mon Sep 17 00:00:00 2001 From: supritha-kumar Date: Mon, 31 Aug 2026 11:36:41 +0530 Subject: [PATCH 14/17] Updated xdcr-support-for-cng.adoc updated xrefs from docs operator to docs cloud native gateway --- .../clusters-and-availability/xdcr-support-for-cng.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 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 08ed0c3233..6daed2cd24 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 @@ -38,7 +38,7 @@ In cloud environments, this requires exposing multiple ports on every node acros * OpenShift and Kubernetes environments: OpenShift Routes and Kubernetes Ingress objects only support HTTP/HTTPS traffic. 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. +For more information, see xref:docs-cloud-native-gateway:about-cng.adoc.adoc. * Private Link environments: 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: @@ -277,7 +277,7 @@ Typical requirements for this scenario: === OpenShift Environment 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. +For more information, see xref:docs-cloud-native-gateway:about-cng.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. @@ -288,7 +288,7 @@ When creating XDCR remote references in a CAO-managed cluster, the `couchbase2:/ === 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 network or private network using VPC Peering. +A Capella cluster running the next major release can replicate data to a self-managed cluster using Cloud Native Gateway 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. From 4ef6e958c062465afebe4b83f9f80e21c251a4a6 Mon Sep 17 00:00:00 2001 From: Supritha Date: Mon, 31 Aug 2026 12:30:14 +0530 Subject: [PATCH 15/17] Vale and style guide changes --- .../xdcr-support-for-cng.adoc | 41 +++++++++++-------- 1 file changed, 24 insertions(+), 17 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 6daed2cd24..d76ef9b397 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 @@ -38,11 +38,11 @@ In cloud environments, this requires exposing multiple ports on every node acros * OpenShift and Kubernetes environments: OpenShift Routes and Kubernetes Ingress objects only support HTTP/HTTPS traffic. 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-cloud-native-gateway:about-cng.adoc.adoc. +For more information, see xref:docs-cloud-native-gateway:about-cng.adoc. * Private Link environments: 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. +Any network interface or proxy that supports HTTPS or gRPC works naturally with CNG, whereas direct XDCR connections require custom solutions that are environment-specific and fragile. 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. @@ -51,7 +51,7 @@ CNG allows the XDCR connection to flow over a single gRPC interface, eliminating 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. -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. +NOTE: For bidirectional 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 @@ -75,7 +75,7 @@ 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 support the next major release or later 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 bidirectional CNG replication) |Target cluster |Cloud Native Gateway @@ -104,7 +104,7 @@ 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 an XDCR source and a target. +NOTE: In a bidirectional 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 version 1.2.1 or later installed. @@ -113,10 +113,11 @@ As a target, it must have CNG version 1.2.1 or later installed. 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. +Attempting to create a replication with an HLV-enabled bucket returns an error. +* *xdcrDiffer*: The `xdcrDiffer` tool does not support CNG in Phase 1. +Attempting to use `xdcrDiffer` with a CNG remote reference returns an error. * *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. +* *Sync Gateway Interop*: Mobile buckets (Sync Gateway / App Services) are only supported for one-way (uni-directional) XDCR replication with CNG since bidirectional support requires cross cluster versioning to be enabled on the bucket. == Working of XDCR Over CNG @@ -124,7 +125,8 @@ 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, XDCR 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. @@ -133,7 +135,7 @@ 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 cluster 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 2 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 XDCR topology, some replication legs can use CNG while others use direct node-to-node connections. @@ -153,7 +155,7 @@ 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. +You learn how to create remote cluster references, configure security settings, and use the available tools. === Creating a Remote Cluster Reference @@ -229,7 +231,8 @@ curl -u Administrator:password -X POST \ 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. +NOTE: The REST API output does not have the "couchbase2://" prefix in the hostname. +The UI shows 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 @@ -264,7 +267,7 @@ This section describes common deployment scenarios for XDCR over Cloud Native Ga === Self-Managed to Self-Managed 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. +This enables bidirectional replication without requiring direct node-to-node network access between the clusters. Typical requirements for this scenario: @@ -307,16 +310,19 @@ This section provides reference information for configuring and using XDCR over |`couchbase2://` |Specifies a CNG/gRPC connection to the target cluster. -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. +When using this prefix, the default CNG gRPC port is 18098. +If you're not using the default port, the port must be specified in the hostname. |`couchbase://` |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. +When using this prefix, the default port is 8091. +If you're 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. -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. +When using this prefix, the default port is 18091. +If you're not using this default port, the port must be specified in the hostname. No change to existing behavior. |=== @@ -329,7 +335,8 @@ No change to existing behavior. |`hostname` |Yes |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. +The default CNG gRPC port is 18098. +If you're not using the default port, then you must specify the port with the hostname. |`secureType` |Yes From 5bfd964df9fc78380298d74a5c7b8e9ad679a97f Mon Sep 17 00:00:00 2001 From: Supritha Date: Mon, 7 Sep 2026 10:07:57 +0530 Subject: [PATCH 16/17] Updated docs review comments --- .../xdcr-support-for-cng.adoc | 56 ++++++++++--------- 1 file changed, 29 insertions(+), 27 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 d76ef9b397..b658a9b103 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 @@ -9,11 +9,10 @@ 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. +For information about CNG deployment, see xref:cloud-native-gateway::intro/about-cng.adoc[About Cloud Native Gateway]. -NOTE: This document does not cover Cloud Native Gateway installation. - -IMPORTANT: This feature is available in Enterprise Edition only. -It's not available in Community Edition. +IMPORTANT: This feature is available in Couchbase Server Enterprise Edition only. +It's not available in Couchbase Server Community Edition. == Cloud Native Gateway in Couchbase @@ -37,10 +36,12 @@ In cloud environments, this requires exposing multiple ports on every node acros * OpenShift and Kubernetes environments: OpenShift Routes and Kubernetes Ingress objects only support HTTP/HTTPS traffic. -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-cloud-native-gateway:about-cng.adoc. +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. +For example, you can use OpenShift Routes and Kubernetes LoadBalancer to just expose CNG. +For more information, see xref:cloud-native-gateway::intro/about-cng.adoc[About Cloud Native Gateway]. * Private Link environments: -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. +Cloud Service Provider (CSP) private link services expect a single load-balanced resource. +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 works naturally with CNG, whereas direct XDCR connections require custom solutions that are environment-specific and fragile. @@ -67,7 +68,7 @@ The following version requirements apply to XDCR over CNG: |Source cluster |Couchbase Server -|the next major release or later +|8.5 |Source cluster |Cloud Native Gateway @@ -75,14 +76,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 support the next major release or later for bidirectional CNG replication) +|Any version that supports CNG (earlier versions are supported as target; however, both clusters must support Couchbase Server 8.5 or later for bidirectional CNG replication) |Target cluster |Cloud Native Gateway |CNG version 1.2.1 or later |=== -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. +IMPORTANT: The Couchbase Server on the source cluster must be running Couchbase Server 8.5 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 @@ -92,20 +93,20 @@ The target cluster must have Cloud Native Gateway version 1.2.1 or later, as 1.2 |Replication Type |Source Cluster Requirements |Target Cluster Requirements |One-way (unidirectional) -|The next major release. +|8.5 CNG not required. |CNG with XDCR support installed. Server version can be any version that works with CNG 1.2.1. |Two-way (bidirectional) -|The next major release. +|8.5 CNG with XDCR support installed (acting as a target). -|The next major release. +|8.5 CNG with XDCR support installed (acting as a target). |=== NOTE: In a bidirectional setup, each cluster is both an XDCR source and a target. -As a source, it must be running the next major release. +As a source, it must be running Couchbase Server version 8.5. As a target, it must have CNG version 1.2.1 or later installed. == Limitations @@ -119,14 +120,14 @@ Attempting to use `xdcrDiffer` with a CNG remote reference returns an error. * *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 bidirectional support requires cross cluster versioning to be enabled on the bucket. -== Working of XDCR Over CNG +== How XDCR over CNG Works 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 transmits data over HTTPS using the gRPC protocol. -By default, this traffic uses port *18098* on the Cloud Native Gateway. +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. @@ -137,6 +138,7 @@ The source cluster XDCR process does not need to track or update topology maps f 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 2 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. +For more information, see xref:manage:manage-xdcr/create-xdcr-reference.adoc#switching-protocols[Switching Protocols]. This means that in a multi-cluster XDCR topology, some replication legs can use CNG while others use direct node-to-node connections. @@ -161,9 +163,9 @@ You learn how to create remote cluster references, configure security settings, 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 +=== CNG URI -As shown below, use the couchbase2:// prefix with the target cluster CNG hostname or load balancer address. +When creating the CNG URI, use the couchbase2:// scheme 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. @@ -172,8 +174,8 @@ However, if the CNG is using a different port, then, you must add the port to th couchbase2:// ---- -IMPORTANT: Use the prefix `couchbase2://`, not `couchbases2://`. -The prefix does not contain an `s` after `couchbase`. +IMPORTANT: Use the scheme `couchbase2://`, not `couchbases2://`. +The scheme does not contain an `s` after `couchbase`. === Security and Encryption @@ -266,32 +268,32 @@ This section describes common deployment scenarios for XDCR over Cloud Native Ga === Self-Managed to Self-Managed -Two self-managed clusters, both running the next major release, can replicate data using XDCR over CNG. +Two self-managed clusters, both running Couchbase Server 8.5, can replicate data using XDCR over CNG. This enables bidirectional replication without requiring direct node-to-node network access between the clusters. Typical requirements for this scenario: -* Both clusters run the next major release or later. +* Both clusters run Couchbase Server 8.5 release or later. * 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 created using the `couchbase2://` scheme and the hostname of the target Cloud Native Gateway. * Remote references are configured with full TLS encryption (`secureType=full`). * The clusters do not require alternate addresses or direct node-to-node network connectivity. === OpenShift Environment 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-cloud-native-gateway:about-cng.adoc. +For more information, see xref:cloud-native-gateway::intro/about-cng.adoc[About Cloud Native Gateway]. 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. +XDCR from any Couchbase cluster can replicate into the OpenShift-hosted cluster by creating a remote reference with the `couchbase2://` scheme 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. +When creating XDCR remote references in a CAO-managed cluster, the `couchbase2://` scheme and CNG address should be allowed in the CAO XDCR configuration. === Capella to Self-Managed Over Public Network -A Capella cluster running the next major release can replicate data to a self-managed cluster using Cloud Native Gateway across the public network or private network using VPC Peering. +A Capella cluster running Couchbase Server 8.5 can replicate data to a self-managed cluster using Cloud Native Gateway 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. From ce2ac17f2265c9c15a860f71459bc09989df476e Mon Sep 17 00:00:00 2001 From: Supritha Date: Mon, 7 Sep 2026 12:16:25 +0530 Subject: [PATCH 17/17] docs comments --- .../xdcr-support-for-cng.adoc | 168 +----------------- .../manage-xdcr/configure-xdcr-over-cng.adoc | 75 ++++++++ .../manage-xdcr/create-xdcr-reference.adoc | 8 +- .../rest-api/pages/rest-xdcr-create-ref.adoc | 29 ++- .../pages/xdcr-security-and-networking.adoc | 64 ++++++- 5 files changed, 168 insertions(+), 176 deletions(-) create mode 100644 modules/manage/pages/manage-xdcr/configure-xdcr-over-cng.adoc 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 b658a9b103..3862ca581a 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 @@ -154,114 +154,6 @@ XDCR returns clear error messages in the following scenarios: 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 - -This section explains how to set up XDCR to replicate data through Cloud Native Gateway. -You 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. - -=== CNG URI - -When creating the CNG URI, use the couchbase2:// scheme 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] ----- -couchbase2:// ----- - -IMPORTANT: Use the scheme `couchbase2://`, not `couchbases2://`. -The scheme does not contain an `s` after `couchbase`. - -=== 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 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. - -=== 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 "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 does not have the "couchbase2://" prefix in the hostname. -The UI shows 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 - -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. - -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. @@ -298,62 +190,4 @@ To use this scenario: * The self-managed target cluster must have CNG installed and enabled. * 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. - -== 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"] -|=== -|Prefix |Usage - -|`couchbase2://` -|Specifies a CNG/gRPC connection to the target cluster. -When using this prefix, the default CNG gRPC port is 18098. -If you're not using the default port, the port must be specified in the hostname. - -|`couchbase://` -|Standard non-encrypted Couchbase Server connection string format. -When using this prefix, the default port is 8091. -If you're 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. -When using this prefix, the default port is 18091. -If you're not using this default port, the port must be specified in the hostname. -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://`. -The default CNG gRPC port is 18098. -If you're not using the default port, then you must specify the port with the hostname. - -|`secureType` -|Yes -|Must be set to `full`. -Half encryption is not supported for CNG. - -|`certificate` -|Yes -|Root TLS certificate for the CNG. - -|`username` -|Yes -|Target cluster Server username, same as for direct XDCR. - -|`password` -|Yes -|Target cluster Server password, same as for direct XDCR. -|=== +* On the Capella cluster, create a remote reference using the `couchbase2://` prefix and the self-managed cluster CNG hostname. \ No newline at end of file diff --git a/modules/manage/pages/manage-xdcr/configure-xdcr-over-cng.adoc b/modules/manage/pages/manage-xdcr/configure-xdcr-over-cng.adoc new file mode 100644 index 0000000000..348a89a42b --- /dev/null +++ b/modules/manage/pages/manage-xdcr/configure-xdcr-over-cng.adoc @@ -0,0 +1,75 @@ += Configure XDCR over Cloud Native Gateway +:description: pass:q[This section explains how to set up XDCR to replicate data through Cloud Native Gateway (CNG).] + +[abstract] +{description} + +You 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. + +=== CNG URI + +When creating the CNG URI, use the couchbase2:// scheme 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] +---- +couchbase2:// +---- + +IMPORTANT: Use the scheme `couchbase2://`, not `couchbases2://`. +The scheme does not contain an `s` after `couchbase`. + +=== 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. + +For more information, see xref:manage:manage-security/manage-certificates.adoc[Manage Certificates] and xref:manage:manage-security/manage-tls.adoc[Manage On-the-Wire Security]. + +=== Certificate + +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. + +=== 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. + +Make sure that the Encryption setting is set to Full (TLS) for CNG remote references. \ No newline at end of file diff --git a/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc b/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc index e98f83c112..731dab15c9 100644 --- a/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc +++ b/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc @@ -22,9 +22,9 @@ The possible roles are `Full`, and `XDCR Inbound` (either for the individual buc + 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. +* When creating a remote cluster reference for a target cluster fronted by Cloud Native Gateway (CNG), use the `couchbase2://` scheme in the hostname field. This instructs XDCR to use gRPC over HTTPS instead of direct node-to-node connections. -The default CNG gRPC port is *18098*. +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. @@ -34,8 +34,8 @@ Securing a connection is described in detail in xref:manage:manage-xdcr/secure-x 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. +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) is rejected. This ensures that XDCR traffic is encrypted over HTTPS as required by the CNG architecture. [#switching-protocols] diff --git a/modules/rest-api/pages/rest-xdcr-create-ref.adoc b/modules/rest-api/pages/rest-xdcr-create-ref.adoc index 85f6cb11dc..2147cfc433 100644 --- a/modules/rest-api/pages/rest-xdcr-create-ref.adoc +++ b/modules/rest-api/pages/rest-xdcr-create-ref.adoc @@ -75,6 +75,7 @@ If you set the `name` parameter to a different value, Couchbase Server renames t |`hostname` | The hostname or IP address of the reference's target cluster. This value can specify either the internal address or external address (if one has been configured) of the target cluster. +To create a reference to a Cloud Native Gateway (CNG) target cluster, prefix the hostname with `couchbase2://` (for example, `couchbase2://`). For information about using DNS SRV in this context, see xref:xdcr-reference:xdcr-security-and-networking.adoc[XDCR Security and Networking]. | String @@ -172,6 +173,14 @@ Authentication failure, such as incorrect username and password. The URI used in the REST API call was not correct. Couchbase Server respond with this error code if you attempt to edit a non-existent reference by adding its name to the REST API URI. +remoteType:: +The connection type for the remote reference. +Returns "cng" for Cloud Native Gateway references or "cbcluster" for direct, node-to-node cluster references. + +NOTE: The REST API response output does not retain the `couchbase2://` prefix in the `hostname` field. +The connection type is identified by `"remoteType": "cng"`. +The Couchbase Web Console UI retains the `couchbase2://` prefix in the hostname to indicate that the reference connects via CNG. + == Required Permissions You must have Full Admin, Cluster Admin, or XDCR Admin role to call this API. @@ -295,7 +304,7 @@ curl -X POST -u Administrator:password http://localhost:8091/pools/default/remot Because the example sets the `demandEncryption` flag to `1` and does not supply a `secureType` parameter, the connection to the target cluster is fully encrypted. The `network_type=external` parameter indicates that Couchbase Server should connect to the target's external network if it has been configured. If the target cluster does not have an external network defined, the source cluster attempts to connect to the target cluster's internal network. -The example supplies three URL-encoded values: the root certificate of the target cluster and a certificate and key for the client connection. +The example supplies 3 URL-encoded values: the root certificate of the target cluster and a certificate and key for the client connection. If successful, the command returns the following: @@ -328,10 +337,26 @@ If successful, the command returns the following: The `secureType` field specifies `full` which is the default value if you set `demandEncryption` to `1` and do not supply a `secureType` parameter in the REST API call. The output includes both the target cluster's root certificate and the source cluster's client certificate. +=== Create a Remote Reference to a Cloud Native Gateway (CNG) Target Cluster + +The following example creates a fully secure remote reference to a Cloud Native Gateway (CNG) target cluster using the `couchbase2://` prefix in the hostname. + +[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=$(cat ./cng-ca.pem)" +---- + == See Also * See xref:manage:manage-xdcr/enable-full-secure-replication.adoc[] for an overview of securing replications. * See xref:manage:manage-xdcr/secure-xdcr-replication.adoc[] for information about using the REST API to create secure connections. -* See xref:learn:security/certificates.adoc[] for an overview of using certificates with Couchbase Server. +* See xref:learn:security/certificates.adoc[] for an overview of using certificates with Couchbase Server. * See xref:xdcr-reference:xdcr-security-and-networking.adoc[] for some requirements when configuring XDCR. diff --git a/modules/xdcr-reference/pages/xdcr-security-and-networking.adoc b/modules/xdcr-reference/pages/xdcr-security-and-networking.adoc index 8027886422..95e4dde76b 100644 --- a/modules/xdcr-reference/pages/xdcr-security-and-networking.adoc +++ b/modules/xdcr-reference/pages/xdcr-security-and-networking.adoc @@ -199,7 +199,65 @@ See xref:manage:manage-xdcr/enable-full-secure-replication.adoc#specify-full-xdc === XDCR, Certificates, and Containers -If either a source or a target cluster for an XDCR replication resides within a container, such as a Kubernetes pod, the container's image must itself contain the trusted CA that is relied on for validating the cluster that is being connected to. +If a source or target XDCR cluster runs in a container, its image must include the trusted CA used to validate connections. -Note that Couchbase _Operator_ has a _Dynamic Admissions Controller_ (DAC), which performs TLS certificate-generation and assignment, including rotation. -Therefore, if DAC is being used, the Root Certificate referred to by the client when setting up a fully secure replication must be the one whose authority, on the server, is relied on for these DAC operations. +NOTE: Couchbase Operator has a Dynamic Admissions Controller (DAC), which performs TLS certificate-generation and assignment, including rotation. +When using DAC, the Root Certificate that the client uses for secure replication must be the same one the server trusts for DAC operations. + +== Cloud Native Gateway (CNG) Reference + +When replicating to a cluster fronted by Cloud Native Gateway (CNG), XDCR connects via gRPC over TLS rather than direct node-to-node KV connections. + +=== Connection Strings + +[cols="1,2",options="header"] +|=== +|Prefix |Usage + +|`couchbase2://` +|Specifies a CNG/gRPC connection to the target cluster. +When using this prefix, the default CNG gRPC port is 18098. +If you're not using the default port, the port must be specified in the hostname. + +|`couchbase://` +|Standard non-encrypted Couchbase Server connection string format. +When using this prefix, the default port is 8091. +If you're 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. +When using this prefix, the default port is 18091. +If you're not using this default port, the port must be specified in the hostname. +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://`. +The default CNG gRPC port is 18098. +If you're not using the default port, then you must specify the port with the hostname. + +|`secureType` +|Yes +|Must be set to `full`. +Half encryption is not supported for CNG. + +|`certificate` +|Yes +|Root TLS certificate for the CNG. + +|`username` +|Yes +|Target cluster Server username, same as for direct XDCR. + +|`password` +|Yes +|Target cluster Server password, same as for direct XDCR. +|=== \ No newline at end of file