Last updated: 2026-02-11

CockroachDB TLS/SSL Configuration Guide

This guide provides recommended TLS/SSL settings for CockroachDB, a distributed SQL database. CockroachDB uses TLS for all inter-node and client-to-node communication in secure mode. Unlike most databases, CockroachDB requires TLS for production deployments and provides built-in tooling for certificate management.

Prerequisites

CockroachDB 22.1 or later
The cockroach CLI tool (includes certificate generation utilities)

CockroachDB is built with Go's crypto/tls library, which provides strong TLS defaults including TLS 1.2 and TLS 1.3 with secure cipher suites out of the box.

Certificate Architecture

CockroachDB uses a directory-based certificate layout. All certificates are stored in a single --certs-dir directory:

ca.crt -- Certificate authority certificate
node.crt / node.key -- Node certificate and key (for inter-node and client-to-node communication)
client.root.crt / client.root.key -- Root user client certificate

Each node and client user has their own certificate signed by the same CA.

Certificate Generation

Create the CA

cockroach cert create-ca \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

Create Node Certificates

Generate a certificate for each node. Include all hostnames and IP addresses the node will be accessed by:

cockroach cert create-node \
    localhost \
    node1.example.com \
    10.0.0.1 \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

For additional nodes, generate certificates on each machine or copy the ca.crt and ca.key and generate locally:

cockroach cert create-node \
    localhost \
    node2.example.com \
    10.0.0.2 \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

Create Client Certificates

Generate a client certificate for the root user (required for administration):

cockroach cert create-client root \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

For application users:

cockroach cert create-client appuser \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

File Permissions

chmod 700 /etc/cockroachdb/certs
chmod 600 /etc/cockroachdb/certs/*.key
chmod 644 /etc/cockroachdb/certs/*.crt
chown -R cockroach:cockroach /etc/cockroachdb/certs

Starting a Secure Cluster

Start each node with the --certs-dir flag to enable TLS:

cockroach start \
    --certs-dir=/etc/cockroachdb/certs \
    --advertise-addr=node1.example.com \
    --join=node1.example.com,node2.example.com,node3.example.com \
    --store=/var/lib/cockroachdb

Omitting --certs-dir and using --insecure instead disables all TLS. Never use --insecure in production.

Initialize the cluster (first time only):

cockroach init --certs-dir=/etc/cockroachdb/certs --host=node1.example.com

Using External Certificates

If you prefer to use certificates from an external CA (Let's Encrypt, internal PKI, etc.) instead of CockroachDB's built-in tool:

Place the CA certificate at certs/ca.crt
Place the node certificate and key at certs/node.crt and certs/node.key
Place client certificates at certs/client.<username>.crt and certs/client.<username>.key

The node certificate must include the node's hostname and IP in the SAN (Subject Alternative Name) field.

TLS Defaults

CockroachDB is built with Go's crypto/tls library, which enforces TLS 1.2 as the minimum version by default. Go's default cipher suites are secure and include only AEAD ciphers with forward secrecy (AES-GCM, ChaCha20-Poly1305) using ECDHE key exchange.

CockroachDB does not expose cluster settings to change the minimum TLS version or cipher suites. The TLS configuration is determined by the Go runtime version used to build CockroachDB. Upgrading CockroachDB automatically picks up any TLS improvements in newer Go releases.

Client Connections

cockroach sql

Connect using the CockroachDB SQL shell:

cockroach sql \
    --certs-dir=/etc/cockroachdb/certs \
    --host=node1.example.com

Connection String

Use a PostgreSQL-compatible connection string with sslmode and certificate paths:

postgresql://appuser@node1.example.com:26257/mydb?sslmode=verify-full&sslrootcert=/path/to/ca.crt&sslcert=/path/to/client.appuser.crt&sslkey=/path/to/client.appuser.key

Available sslmode values:

require -- Encrypt the connection, don't verify the server certificate
verify-ca -- Encrypt and verify the server certificate against the CA
verify-full -- Encrypt, verify the CA, and verify the server hostname (recommended)

DB Console (Web UI)

The DB Console is served over HTTPS automatically when the cluster is started in secure mode. Access it at:

https://node1.example.com:8080

Certificate Rotation

CockroachDB supports online certificate rotation without downtime. To rotate certificates:

Generate new certificates with the same CA (or a new CA added to ca.crt)
Replace the certificate files in the --certs-dir
CockroachDB detects the change and reloads certificates automatically

To manually trigger a reload:

cockroach sql --certs-dir=/etc/cockroachdb/certs -e "SELECT crdb_internal.reload_tls_certificate();"

Verification

List all certificates and their expiration dates:

cockroach cert list --certs-dir=/etc/cockroachdb/certs

Check the cluster status:

cockroach node status --certs-dir=/etc/cockroachdb/certs --host=node1.example.com

Test the TLS connection with OpenSSL:

openssl s_client -connect node1.example.com:26257

Verify from the SQL shell:

cockroach sql --certs-dir=/etc/cockroachdb/certs --host=node1.example.com \
    -e "SELECT * FROM crdb_internal.node_build_info;"