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

      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

      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.