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/backup-restore/pages/enterprise-backup-restore.adoc b/modules/backup-restore/pages/enterprise-backup-restore.adoc index 5524c2462c..b8e0d5e90a 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,132 +102,52 @@ 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 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 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. .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* -| 7.6 -| ✓ +| 8.0 | ✓ | ✓ | ✓ -| ✓ -| -| -| -| 7.2 +| 7.6 | | ✓ | ✓ -| ✓ -| ✓ -| -| -| -| 7.1 -| +| 7.2 +| | | ✓ -| ✓ -| ✓ -| ✓* -| -| - - -| 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 -**** +== 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. - -**** 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..3862ca581a --- /dev/null +++ b/modules/learn/pages/clusters-and-availability/xdcr-support-for-cng.adoc @@ -0,0 +1,193 @@ += 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 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 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]. + +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 + +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. + +== 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 friction in the following scenarios: + +* 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. +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. +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. + +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. + +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 + +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: + +[cols="1,1,2",options="header"] +|=== +|Replication Role |Component |Requirement + +|Source cluster +|Couchbase Server +|8.5 + +|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 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 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 + +[cols="1,2,2",options="header"] +|=== +|Replication Type |Source Cluster Requirements |Target Cluster Requirements + +|One-way (unidirectional) +|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) +|8.5 +CNG with XDCR support installed (acting as a target). +|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 Couchbase Server version 8.5. +As a target, it must have CNG version 1.2.1 or later installed. + +== Limitations + +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 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 bidirectional support requires cross cluster versioning to be enabled on the bucket. + +== 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. + +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 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. + +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. + +== 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.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 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://` 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: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://` 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://` scheme and CNG address should be allowed in the CAO XDCR configuration. + +=== Capella to Self-Managed Over Public Network + +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. +* 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. \ 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 eee8667a3e..731dab15c9 100644 --- a/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc +++ b/modules/manage/pages/manage-xdcr/create-xdcr-reference.adoc @@ -7,34 +7,51 @@ [#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. -* Whether the the connection between source and target clusters will be managed securely, and if so, by what secure methodology. +* 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. +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 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) is 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:// 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 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. @@ -88,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: @@ -124,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. @@ -137,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] @@ -161,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 \ @@ -169,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 @@ -187,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: 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