A newer version of this documentation is available.

View Latest

Couchbase TLS

    Transport layer security (TLS) is responsible for securing data over networks. This section documents what security protections are available.

    Basic TLS Configuration

    Couchbase Server supports TLS out of the box. Couchbase Server generates a self-signed CA certificate for the whole cluster. Each pod that is added to the cluster gets a certificate valid for its hostname.

    The cluster CA certificate is available from the Couchbase UI and may be given to any client in order to authenticate that a Couchbase Server connection is to a trusted pod. The cluster CA may also be used to secure cross data center replications (XDCR).

    Managed TLS Configuration

    When using basic configuration the end user has no control over how the certificates are generated.

    When using the public connectivity feature for example — the Couchbase Cluster is accessed from outside of the Kubernetes cluster — the internal DNS names that would be automatically generated by Couchbase Server are no longer valid. The certificate needs to be valid for an alternative public DNS name. Likewise the Prometheus exporter when operating over TLS needs to access the local pod on localhost. It may also be desirable to integrate Couchbase Server into an existing corporate TLS hierarchy.

    Managed TLS gives the ability for you to use any TLS certificates you like with Couchbase Server. A certificate may be a single certificate or an entire certificate chain.

    The only basic constraint imposed by the Operator is that the certificate contain at least a wildcard DNS subject alternative name (SAN) that is valid for any pod name the may be generated during the cluster life cycle. The Operator does not act as a certificate authority (CA) that could be used to sign arbitrary certificates.

    For configuration details please see the TLS configuration how-to.

    When using managed TLS, the Operator and any sidecar containers will also communicate with Couchbase Server over TLS. Use of managed TLS is highly recommended in order to encrypt passwords and other sensitive information that may be exchanged between Couchbase Server and the Operator.

    TLS Client Authentication

    Couchbase Server supports mutual TLS (mTLS). With this mode of operation not only do clients verify they are talking to a trusted entity, but the Couchbase Server instance can also establish trust in the client. Client authentication may be mandatory or optional.

    When using mTLS then the certificate must also contain identity information in the form of a username that maps to a Couchbase Server user. With optional authentication if the client does not supply a certificate to Couchbase Server on request then it will fall back to basic (username & password) authentication.

    mTLS is fully supported by the Operator. When enabled the user must supply the Operator with a client certificate valid for the cluster administrator.

    For configuration details please see the TLS client certificate how-to.

    TLS Certificate Rotation

    Certificates go out of date and cause clients to stop working. Private keys corresponding to certificates can be compromised thus allowing communications to be decrypted. With this in mind, the Operator allows certificates to be rotated and replaced with new versions.

    The Operator supports all possible rotation types:

    • Replacing a server certificate/key

    • Replacing a client certificate/key

    • Replacing the entire PKI

    Couchbase Server does not support CA pools. When a CA is about to go out of date you cannot add a new CA and gracefully update clients. They must all be updated in a single operation causing service disruption and downtime.

    It is therefore recommended that CA certificates have a lifetime longer than that of the database. The CA should be physically secured to guarantee security. Client certificates can be signed by an intermediate CA with a shorter lifetime as defined by your security policy. Client certificates can then be rotated gracefully, minimizing downtime.

    Couchbase Server certificates must be rotated in a single operation. While disruptive, the Operator can update an entire Couchbase cluster in seconds.