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

Creating TLS Certificates

      +
      This section shows a simple way to create and manage a TLS certificate hierarchy.

      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.

      Creating X.509 certificates is beyond the scope of this documentation and is given only for illustrative purposes only. Please consult the Couchbase Server documentation for additional details on certificate and TLS configuration.

      EasyRSA

      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

      Creating a Couchbase Cluster Server Certificate

      You need to create a server wildcard certificate and key to be used on Couchbase Server pods. The Operator will access pods using Kubernetes endpoint records e.g. https://cb-example-0000.cb-example.default.svc. Clients will access the cluster using Kubernetes service discovery records e.g. couchbases://cb-example.default. UI access will be with port-forwarding using localhost.

      In general, the required set of DNS subject alternative names (SANs) is:

      • DNS:*.${cluster}

      • DNS:*.${cluster}.${namespace}

      • DNS:*.${cluster}.${namespace}.svc

      • DNS:*.${cluster}.${namespace}.svc.cluster.local

      • DNS:${cluster}-srv

      • DNS:${cluster}-srv.${namespace}

      • DNS:${cluster}-srv.${namespace}.svc

      • DNS:*.${cluster}-srv.${namespace}.svc.cluster.local

      • DNS:localhost

      This set of SANs depends on search domains configured for your stub resolver. By default Kubernetes will do this for you.

      If you use the inter-Kubernetes networking with forwarded DNS networking model for connecting your clients, then you will need to configure this yourself.

      For example, the FQDN for a Couchbase pod would be similar to cb-0000.cb.default.svc.cluster.local, however a client will communicate with cb-0000.cb.default.svc. In order for a client to match the *.cb.default.svc SAN, and resolve the pod address, a search domain would need to be configured for cluster.local. Likewise, if your clients used the short form hostname cb-0000.cb, a search domain would need to configured for default.svc.cluster.local.

      The Operator dynamic admission controller enforces the presence of all of these SANs, and they must be present.

      To generate a certificate for the cluster cb-example in the default namespace:

      $ ./easyrsa --subject-alt-name='DNS:*.cb-example,DNS:*.cb-example.default,DNS:*.cb-example.default.svc,DNS:*.cb-example.default.svc.cluster.local,DNS:cb-example-srv,DNS:cb-example-srv.default,DNS:cb-example-srv.default.svc,DNS:*.cb-example-srv.default.svc.cluster.local,DNS:localhost' build-server-full couchbase-server nopass

      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 spec.networking.tls.static.serverSecret cluster parameter.

      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

      Creating a Dynamic Admission Controller Server Certificate

      To create a server certificate that can be used by the dynamic admission controller, simply specify the service name that the Kubernetes API webhooks will connect to. This is in the form ${service}.${namespace}.svc, so if our service is called couchbase-operator-admission and we were deploying it in the operator-admission namespace, run the following:

      $ ./easyrsa --subject-alt-name=couchbase-operator-admission.operator-admission.svc build-server-full couchbase-admission-controller nopass`

      Creating a Client Certificate

      This process is very similar to creating a server certificate. Assuming the administrative user defined for Couchbase Server is Administrator you can create a client certificate for the Operator to use with the following command:

      $ ./easyrsa build-client-full Administrator nopass

      The created files pki/private/Administrator.key and pki/issued/Administrator.crt can be used as couchbase-operator.key and couchbase-operator.crt respectively when specifying the CouchbaseCluster spec.networking.tls.static.operatorSecret.

      Further reading