A newer version of this documentation is available.

View Latest

Configuring TLS


      Couchbase supports transport layer security [TLS] in order to encrypt communications on the wire and provide mutual authentication between peers.

      The basic requirements are:

      • A certificate authority (CA) certificate which will be used by all actors to validate that peer certificates have been digitally signed by a trusted CA.

      • A server certificate/key pair for all nodes in the Couchbase cluster. If you are using a hierarchy of intermediate CAs, these must be appended to the client certificate, ending in the intermediate CA that is signed by the top-level CA. Server certificates must have a subject alternative name (SAN) set so that a client can assert that the host name that it’s connecting to is the same as that in the certificate.

        Couchbase currently supports using wildcard entries only. For example, *.cluster.domain.svc where cluster is the name of the CouchbaseCluster resource, and domain is the namespace that the cluster is running in (typically default).


      • TLS certificates are installed as part of the pod creation process, and cannot be enabled on an existing cluster.

      • TLS certificate rotation is not supported.


      An example configuration is as follows:

              serverSecret: couchbase-server-tls
            operatorSecret: couchbase-operator-tls

      For a static TLS configuration, serverSecret and operatorSecret need to be specified. These refer to named Kubernetes secrets which are described below.

      Creating Secrets

      Secrets are specified in the CouchbaseCluster resource, therefore they may have any name you choose. The format of individual secrets is discussed below.


      Server secrets need to be mounted as a volume within the Couchbase Server pod with specific names. The certificate chain must be named chain.pem and the private key pkey.pem.

      kubectl create secret generic couchbase-server-tls \
        --from-file example/tls/certs/chain.pem \
        --from-file example/tls/certs/pkey.key


      The Couchbase Autonomous Operator client secrets are read directly from the API. It expects only a single value to be present; ca.crt is the top-level CA which is used to authenticate all TLS server certificate chains.

      kubectl create secret generic couchbase-operator-tls \
        --from-file example/tls/certs/ca.crt

      Creating Certificates

      Creating X.509 certificates is beyond the scope of this documentation and is given only for illustrative purposes only.


      EasyRSA by OpenVPN makes operating a public key infrastructure (PKI) relatively simple, and is the recommended method to get up and running quickly.

      First clone the repository:

      git clone https://github.com/OpenVPN/easy-rsa

      Initialize and create the CA certificate/key. You will be prompted for a private key password and the CA common name (CN), something like Couchbase CA is sufficient. The CA certificate will be available as pki/ca.crt.

      cd easy-rsa/easyrsa3
      ./easyrsa init-pki
      ./easyrsa build-ca

      Create a server wildcard certificate and key to be used on Couchbase Server pods. The Operator/clients will access the pods via Kubernetes services (cb-example-0000.cb-example.default.svc, for example) so this needs to be in the SAN list in order for a client to verify the certificate belongs to the host that is being connected to. To this end, we add in a --subject-alt-name, this can be specified multiple times in case your client uses a different method of addressing. The key/certificate pair can be found in pki/private/couchbase-server.key and pki/issued/couchbase-server.crt and used as pkey.pem and chain.pem, respectively, in the serverSecret.

      ./easyrsa --subject-alt-name=DNS:*.cb-example.default.svc build-server-full couchbase-server nopass

      Note, password protected keys are not supported by Couchbase Server or the Operator.

      Private Key Formatting

      Due to an issue with Couchbase Server’s private key handling, server keys need to be PKCS#1 formatted. This can be achieved with the following commands:

      openssl rsa -in pkey.key -out pkey.key.der -outform DER
      openssl rsa -in pkey.key.der -inform DER -out pkey.key -outform PEM