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.

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.

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.

  • 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.

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

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

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

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

DNS Based Addressing with External DNS

XDCR in Couchbase Server 6.5.1 does not support load balancing, please see Special Considerations for XDCR in Couchbase Server 6.5.1 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 spec.networking.dns.domain cluster parameter. The connection string is in the form https://console.${dns-domain}. Given the DNS domain my-cluster.acme.org, to connect to the cluster using TLS use the connection string https://console.my-cluster.acme.org:18091.

Use of client SDKs with this network configuration relies on support for DNAT. Consult the networking concepts page for compatibility information.

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 does not support load balancing, please see Special Considerations for XDCR in Couchbase Server 6.5.1 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.

Use of client SDKs with this network configuration relies on support for DNAT. Consult the networking concepts page for compatibility information.

Special Considerations for XDCR in Couchbase Server 6.5.1

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 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 list 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 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 list 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.