A newer version of this documentation is available.

View Latest

Public Networking with External DNS

      +
      How to configure a Couchbase cluster so that is available via the public internet.

      Tutorials are accurate at the time of writing but rely heavily on third party software. Tutorials are provided to demonstrate how a particular problem may be solved. Use of third party software is not supported by Couchbase. For further help in the event of a problem, contact the relevant software maintainer.

      There are numerous reasons why you would want to expose a Couchbase database on the public internet. Some examples could be:

      • Cross data center replication (XDCR)

      • Client access for a 3rd-party function-as-a-service (FaaS) platform

      • Database-as-a-service (DBaaS) platforms

      All of these use cases share a common goal; they allow clients to access the database instance without having to establish a VPN to a Kubernetes instance. They also all require secure — TLS protected — communication that are sometimes difficult to achieve with typical Kubernetes architectures.

      A publicly addressable cluster uses the public networking with External DNS strategy for its network architecture. Couchbase cluster nodes are exposed using load-balancer services that have public IP addresses allocated to them. The External DNS controller is responsible for managing dynamic DNS (DDNS) in a cloud based provider to provide stable addressing and a basis for TLS.

      networking basic external dns
      Figure 1. Basic Public Networking

      This tutorial will guide you through fully configuring your Couchbase cluster to use this feature and also configure the External DNS controller.

      DDNS

      Before continuing you will need a public DNS domain. These can be purchased from a registrar such as Gandi, GoDaddy, Namecheap, etc. For this tutorial we will use rockstar-wizard.com.

      The next step is to delegate the service of that domain to a DDNS provider. During the life cycle of a Couchbase cluster, nodes may be added and removed for cluster scaling, upgrades or fault recovery. In each instance, new DNS names need to be created for any new Couchbase pods that are created, or DNS names removed from pods that are deleted. The DDNS provider exposes a REST API that allows the External DNS controller in Kubernetes to synchronize what the Couchbase cluster looks like with public DNS. For this tutorial we will use Cloudflare. You will need to create an API key in order for External DNS to authenticate against the Cloudflare API.

      All supported DDNS providers are documented on the External DNS home page.

      TLS

      The Operator ensures you configure your Couchbase clusters securely. If the Operator detects a cluster is being exposed on the public internet, it will enforce TLS encryption. This ensures eavesdroppers cannot intercept any passwords or sensitive data while in transit.

      Before we generate TLS certificates we need to determine what DNS domain the cluster will be in. We could use our rockstar-wizard.com domain directly, but then it could only ever be used by a single Couchbase cluster. Therefore we shall use a subdomain called gandalf.rockstar-wizard.com as a unique namespace for our Cluster. For example, the UI will be allocated the DNS name console.gandalf.rockstar-wizard.com within this subdomain. In general, a wildcard DNS name (*.gandalf.rockstar-wizard.com) will handle all public DNS names generated by the Operator. This needs to be added to the Couchbase cluster certificate.

      To create TLS certificates for the Couchbase cluster follow the TLS tutorial.

      External DNS

      Assuming you have already configured the Operator in the couchbase namespace, the next thing you need to install is the External DNS controller. This must be installed before the Couchbase cluster as the Operator will wait for DNS propagation before balancing in Couchbase Server pods. This is because clients must be able to reach the Couchbase server pods in order to serve traffic and prevent application errors.

      Create a service account for the External DNS controller to run as:

      $ kubectl --namespace gandalf create serviceaccount external-dns

      The External DNS controller requires a role in order for it to be able to poll for resources and look for DNS records to replicate into the DDNS provider:

      $ kubectl --namespace couchbase create -f - <<EOF
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: external-dns
      rules:
      - apiGroups:
        - ""
        resources:
        - services
        - pods
        - nodes
        verbs:
        - get
        - watch
        - list
      EOF

      I used a cluster role so it can be shared between service accounts in different namespaces. This does require administrative permissions to install, however when bound to the service account it will not grant cluster-wide privileges.

      To link the role to the service account:

      $ kubectl --namespace couchbase create rolebinding --clusterrole external-dns --serviceaccount couchbase:external-dns external-dns

      Finally install the External DNS deployment:

      $ kubectl --namespace couchbase create -f - <<EOF
      apiVersion: extensions/v1beta1
      kind: Deployment
      metadata:
        name: external-dns
      spec:
        selector:
          matchLabels:
            app: external-dns
        template:
          metadata:
            labels:
              app: external-dns
          spec:
            serviceAccountName: external-dns (1)
            containers:
             - name: external-dns
               image: registry.opensource.zalan.do/teapot/external-dns:latest
               args:
               - --source=service (2)
               - --domain-filter=rockstar-wizard.com (3)
               - --provider=cloudflare (4)
               - --txt-owner-id=couchbase.my-kubernetes-cluster (5)
               env:
               - name: CF_API_KEY (6)
                 value: REDACTED
               - name: CF_API_EMAIL (7)
                 value: REDACTED
      EOF

      Let’s look at this deployment in a little more detail:

      1 The spec.template.spec.serviceAccountName attribute ensures External DNS pods are running as the service account we set up. This grants the controller permission to poll resources and look for DDNS requests.
      2 The --source argument tells External DNS to only look at services within the namespace. The Operator generates hostnames for services that need to be exposed on the internet using the Couchbase cluster DNS configuration. These services are annotated with the hostnames. The External DNS controller creates DNS records for these hostnames when public IP addresses are allocated for the service.
      3 The --domain-filter argument tells External DNS to only consider DDNS entries that are associated with DNS entries related to our rockstar-wizard.com domain. With this configuration you can define multiple clusters in the couchbase namespace. For example a second cluster with the DNS configuration merlin.rockstar-wizard.com within the same namespace would also be matched by this controller.
      4 The --provider argument tells External DNS to replicate DDNS entries into Cloudflare.
      5 The --txt-owner-id argument tells External DNS to label TXT management records with a string unique to the External DNS instance. External DNS uses TXT records to record metadata — especially ownership information — associated with the DNS records it is managing. If the rockstar-wizard.com domain is used by multiple instances of External DNS without specifying any ownership, then they would conflict with one another.
      6 The CF_API_KEY environment variable is used by the Cloudflare provider to authenticate against the Cloudflare API.
      7 The CF_API_EMAIL environment variable is used by the Cloudflare provider to identify what account to use against the Cloudflare API.

      Couchbase Cluster

      The final Couchbase cluster definition will look similar to the following:

      apiVersion: couchbase.com/v2
      kind: CouchbaseCluster
      metadata:
        name: couchbase
      spec:
        image: couchbase/server:7.1.3
        security:
          adminSecret: my-admin-secret
        networking:
          exposeAdminConsole: true
          adminConsoleServiceTemplate:
            spec:
              type: LoadBalancer
          exposedFeatures:
          - xdcr
          - client
          exposedFeatureServiceTemplate:
            spec:
              type: LoadBalancer
          dns:
            domain: gandalf.rockstar-wizard.com
          tls:
            secretSource:
              serverSecretName: couchbase-cert
        servers:
        - name: default
          services:
          - data
          - index
          - query
          size: 3

      Configuration options are fully documented in the public networking how-to.

      Next Steps

      Now you have a publicly addressable cluster you can start using it. Consult the following guides for details on client operations: