Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Configure Client SDKs

      +
      Connecting a Couchbase SDK to an Operator managed Couchbase cluster.

      Couchbase Server requires clients in order to do productive work. The operator is only concerned with cluster life cycle and high availability.

      Configuration and use of a client SDK is available in language specific documentation. All client SDKs share a common connection string format; used by the SDK to connect to the Couchbase cluster and discover nodes. This how-to documents how to calculate the required connection string based on your chosen network architecture.

      While we discuss client SDKs, these configurations also apply to Couchbase Connectors and Couchbase Mobile.
      Client Explicit Network Selection

      Various Couchbase clients behave differently from one another in the way they perform automatic network selection when using alternate addressing, with some clients selecting the wrong network in certain circumstances. This inconsistent behavior is avoided by specifying a network selection flag in the connection string that is used by the client to connect to the Couchbase cluster. This is known as explicit network selection.

      The connection string examples throughout the Autonomous Operator documentation use explicit network selection to help avoid undesirable client behavior. Connection strings for internally-networked clients use network=default, while externally-networked clients use network=external.

      One important caveat is that explicit network selection is not supported by older Couchbase clients. If you happen to be using a client that doesn’t support explicit network selection, make sure to remove the network query from any example connection string you copy from the documentation.

      Table 1. Clients Without Explicit Network Support
      Client Version

      Couchbase Server (XDCR)

      < 6.6.0

      Couchbase Sync Gateway

      < 2.8.2

      Couchbase SDKs

      < 3.x (Java, .NET, C, Node.js, PHP, Python, Ruby)

      < 2.x (Go)

      DNS Based Addressing

      DNS based addressing is the simplest form of connecting a client to a Couchbase cluster. All supported DNS based solutions support dynamic, DNS based service discovery that provides fault-tolerance.

      When using inter-Kubernetes networking with forwarded DNS, the local client must forward DNS requests to the remote cluster in order to resolve DNS names of the target Couchbase instances. Refer to the Inter-Kubernetes Networking with Forwarded DNS tutorial to understand how to configure forwarding DNS servers. The XDCR configuration guide has some pointers on how to configure client Pod DNS resolvers, and search domains, in order to correctly forward DNS requests to the remote cluster.

      All that is required to calculate the connection string is the cluster name and — optionally — the namespace it is running in. For the following examples we will use my-cluster and my-namespace respectively.

      Due to the fact that service discovery occurs only though the data service, we need to use a separate service to identify only these nodes. The service name is in the form <cluster-name>-srv.

      The complete connection string — for clients running in Kubernetes — is in the form <scheme>://<cluster-name>-srv.<namespace>. Due to domain search rules within Kubernetes you may use <scheme>://<cluster-name>-srv if the client resides in the same namespace. Clients running outside of Kubernetes will have to use the fully-qualified domain name. Given our example cluster and namespace names:

      • To connect to the cluster using plain text, in the same namespace, use the connection string couchbase://my-cluster-srv?network=default.

      • To connect to the cluster using plain text, in the same or a different namespace, use the connection string couchbase://my-cluster-srv.my-namespace?network=default`.

      • To connect to the cluster using plain text, from anywhere, use the connection string couchbase://my-cluster-srv.my-namespace.svc.cluster.local?network=default`.

      • To connect to the cluster using TLS, in the same namespace, use the connection string couchbases://my-cluster-srv?network=default`.

      • To connect to the cluster using TLS, in the same or a different namespace, use the connection string couchbases://my-cluster-srv.my-namespace?network=default`.

      • To connect to the cluster using TLS, from anywhere, use the connection string couchbases://my-cluster-srv.my-namespace.svc.cluster.local?network=default`.

      DNS Based Addressing with External DNS

      XDCR in Couchbase Server 6.5.1 and 6.5.2 does not support load balancing, please see Special Considerations for XDCR in Couchbase Server 6.5.1 and 6.5.2 for additional instructions.

      DNS based addressing with External DNS is slightly different to plain DNS. The External DNS controller does not support SRV records, instead we use HTTPS. Fault-tolerance is provided by a load balancer service.

      The connection string is determined by the couchbaseclusters.spec.networking.dns.domain cluster parameter. The connection string is in the form couchbases://console.<dns-domain>?network=external. Given the DNS domain my-cluster.acme.org, to connect to the cluster using TLS use the connection string couchbases://console.my-cluster.acme.org?network=external.

      Use of client SDKs with this network configuration relies on support for DNAT, which in turn requires that the SDK support exposed features.

      Using SRV based connection strings is the recommended method of connecting client SDKs. Defects exist due to performance issues when using HTTP transport for cluster discovery. To mitigate the potential for errors, ensure your clients are not continually connecting and disconnecting from your Couchbase clusters.

      IP Based Addressing

      XDCR in Couchbase Server 6.5.1 and 6.5.2 does not support load balancing, please see Special Considerations for XDCR in Couchbase Server 6.5.1 and 6.5.2 for additional instructions.

      IP based addressing is only used when connecting a client SDK with a node-port service. As this is IP based TLS is not supported. It is also HTTP based so suffers from the same issues as DNS Based Addressing with External DNS. This addressing method is highly discouraged.

      To calculate the connection string, first get the admin console service for your cluster, assuming it is called cb-example:

      $ kubectl get svc cb-example-ui
NAME            TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)                          AGE
cb-example-ui   NodePort   10.110.92.187   <none>        8091:31410/TCP,18091:31972/TCP   114s

      Get all nodes in the cluster:

      $ kubectl get nodes -o wide
NAME       STATUS   ROLES    AGE   VERSION    INTERNAL-IP   EXTERNAL-IP   OS-IMAGE              KERNEL-VERSION   CONTAINER-RUNTIME
minikube   Ready    master   49d   v1.13.11   10.0.2.15     <none>        Buildroot 2018.05.3   4.15.0           docker://18.9.9

      You may use any node IP address, however be aware these could change or be deprovisioned and break clients. The port must be the node port mapped to Couchbase port 8091. The address to connect to is http://10.0.2.15:31410?network=external.

      Use of client SDKs with this network configuration relies on support for DNAT, which in turn requires that the SDK support exposed features.

      Special Considerations for XDCR in Couchbase Server 6.5.1 and 6.5.2

      The Operator allows Couchbase Server to advertise alternate addresses—​for cluster service discovery—​that are visible outside of the Kubernetes cluster. Such addresses may be public DNS names—​referencing external load balancers—​or node ports—​referencing Kubernetes node IP addresses. Couchbase Server 6.5.1 introduced a feature whereby it can infer whether to use the internal or alternate addresses based on the supplied connection string.

      In order for XDCR to use alternate addresses, it expects an exact match between the connection string and one of the alternate addresses advertised by the remote cluster. Likewise, when configuring XDCR with Couchbase Server 6.5.1 and 6.5.2 you must supply an individual pod’s alternate address.

      As a result the connection string is not stable. You cannot remove a remote cluster reference and restore it, as the cluster topology and pod names may have changed in the intervening period. Therefore the configuration processes outlined in this section must be followed each time a connection is established.

      DNS Based Addressing with External DNS

      On your target cluster, first list pods associated with your Couchbase cluster, in this example named foo:

      $ kubectl get pods -l couchbase_cluster=foo

      Select any pod that is returned e.g. foo-0000. The DNS domain is the same as specified by the couchbaseclusters.spec.networking.dns.domain attribute. If the DNS domain is set to my-cluster.acme.org, then the connection string to use will be https://foo-0000.my-cluster.acme.org:18091.

      IP Based Addressing

      On your target cluster, first list pods associated with your Couchbase cluster, in this example named foo:

      $ kubectl get pods -l couchbase_cluster=foo

      Select any pod that is returned e.g. foo-0000. Get the Kubernetes node IP address that the pod is running on:

      $ kubectl get pod foo-0000 --template={{.status.hostIP}}
10.0.2.15

      Next get the node port service associated with the pod:

      $ kubectl get service foo-0000
t svc cb-example-0000
NAME       TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                                         AGE
foo-0000   NodePort   10.111.214.55   <none>        11210:30295/TCP,11207:31890/TCP,8091:30816/TCP,18091:30597/TCP,8092:30804/TCP,18092:30523/TCP   21s

      Select the node port associated with port 8091, in this instance 30816. The connection string to use is https://10.0.2.15:30816.