cockroach cert

Overview

The cockroach cert command creates and manages TLS certificates and keys for secure CockroachDB deployments. Proper certificate management is essential for production clusters.

For production deployments, always use secure mode with TLS certificates. Insecure mode should only be used for local development and testing.

Commands

create-ca

Create a Certificate Authority (CA) certificate and key.

cockroach cert create-ca \
  --certs-dir=<path to certs directory> \
  --ca-key=<path to CA key>

--certs-dir

string

required

Directory where certificates will be stored. Created if it doesn’t exist.

--ca-key

string

required

Path to the CA private key file (e.g., my-safe-directory/ca.key).

--lifetime

duration

default:"10y"

Certificate lifetime. Default is 10 years (87,600 hours).

--key-size

integer

default:"2048"

RSA key size in bits. Common values: 2048, 4096.

--allow-ca-key-reuse

boolean

default:"false"

Reuse existing CA key if it exists.

--overwrite

boolean

default:"false"

Overwrite existing certificates.

Example:

mkdir -p certs my-safe-directory
cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

Generates:

certs/ca.crt - CA certificate (distribute to all nodes)
my-safe-directory/ca.key - CA private key (keep secure, needed to sign other certs)

create-node

Create a node certificate for server-to-server and client-to-server TLS.

cockroach cert create-node \
  --certs-dir=<path to certs> \
  --ca-key=<path to CA key> \
  <host1> <host2> ... <hostN>

hosts

string[]

required

List of hostnames and IP addresses the node certificate will be valid for.

Include all addresses that clients and other nodes will use to connect: hostnames, IP addresses, and localhost.

Example:

cockroach cert create-node \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key \
  node1.example.com \
  192.168.1.10 \
  localhost \
  127.0.0.1

Generates:

certs/node.crt - Node certificate
certs/node.key - Node private key

create-client

Create a client certificate for SQL user authentication.

cockroach cert create-client \
  --certs-dir=<path to certs> \
  --ca-key=<path to CA key> \
  <username>

username

string

required

SQL username for the certificate (e.g., root, app_user).

Example - Root user:

cockroach cert create-client \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key \
  root

Generates:

certs/client.root.crt - Client certificate for user root
certs/client.root.key - Client private key for user root

Example - Application user:

cockroach cert create-client \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key \
  app_user

Generates:

certs/client.app_user.crt
certs/client.app_user.key

list

List all certificates in the certs directory.

cockroach cert list --certs-dir=<path to certs>

Example output:

Certificate directory: certs
  ca.crt
  node.crt
  client.root.crt
  client.app_user.crt

Private keys:
  node.key
  client.root.key
  client.app_user.key

Complete Setup Guide

Create CA certificate

mkdir -p certs my-safe-directory
cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

Keep my-safe-directory/ca.key in a secure location. You’ll need it to create additional certificates.

Create node certificate for each server

For each CockroachDB node, create a certificate with all its addresses:

# Node 1
cockroach cert create-node \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key \
  node1.example.com \
  192.168.1.10 \
  localhost \
  127.0.0.1

# Node 2
cockroach cert create-node \
  --certs-dir=certs2 \
  --ca-key=my-safe-directory/ca.key \
  node2.example.com \
  192.168.1.11 \
  localhost \
  127.0.0.1

Create client certificate for root user

cockroach cert create-client \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key \
  root

Distribute certificates to nodes

Each node needs:

ca.crt (CA certificate)
node.crt (node certificate)
node.key (node private key)

Client machines need:

ca.crt
client.<username>.crt
client.<username>.key

Set proper permissions

chmod 600 certs/*.key
chmod 644 certs/*.crt

Start nodes with certificates

cockroach start \
  --certs-dir=certs \
  --store=/mnt/data \
  --listen-addr=node1.example.com:26257 \
  --join=node1:26257,node2:26257,node3:26257

Certificate Files Reference

File	Description	Distribution
`ca.crt`	Certificate Authority certificate	All nodes and clients
`ca.key`	CA private key (for signing)	Secure storage only, not on nodes
`node.crt`	Node server certificate	Node servers
`node.key`	Node private key	Node servers (same node as node.crt)
`client.root.crt`	Client certificate for `root` user	Admin clients
`client.root.key`	Client private key for `root`	Admin clients
`client.<user>.crt`	Client certificate for SQL user	Application clients
`client.<user>.key`	Client private key	Application clients

Certificate Rotation

Certificates expire based on the --lifetime parameter (default 5 years for node/client certs). To rotate:

Create new certificates

cockroach cert create-node \
  --certs-dir=new-certs \
  --ca-key=my-safe-directory/ca.key \
  node1.example.com 192.168.1.10

Rolling replacement

Replace certificates on nodes one at a time:

Stop node
Replace cert files
Restart node
Wait for node to rejoin cluster
Move to next node

Troubleshooting

Error: x509: certificate signed by unknown authority

The node or client can’t verify the certificate chain.Solutions:

Ensure ca.crt is present in --certs-dir
Verify all certificates were signed by the same CA
Check that the CA certificate hasn’t expired

Error: x509: certificate is valid for X, not Y

Connecting to a hostname not listed in the node certificate.Solution: Recreate the node certificate including all hostnames and IPs:

cockroach cert create-node \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key \
  --overwrite \
  hostname1 hostname2 ip-address localhost

Permission denied errors

Incorrect file permissions on certificate or key files.Solution:

chmod 600 certs/*.key
chmod 644 certs/*.crt

Security Best Practices

Protect CA private key: The ca.key file can generate certificates for your cluster. Store it securely, preferably offline or in a hardware security module (HSM).

Use strong key sizes (minimum 2048 bits, prefer 4096 for CA)
Set appropriate certificate lifetimes (shorter for higher security)
Rotate certificates before expiration
Use separate client certificates for different applications
Never commit private keys (.key files) to version control
Implement certificate expiration monitoring
Consider using separate CAs for client and node certificates

Security Overview - Cluster security configuration
Cluster Management - Certificate usage in clusters
cockroach start - Starting secure nodes

Contributing

CLI Reference

Overview

Commands

create-ca

create-node

create-client

list

Complete Setup Guide

Certificate Files Reference

Certificate Rotation

Troubleshooting

Security Best Practices

Build docs developers (and LLMs) love

Contributing

CLI Reference

​Overview

​Commands

​create-ca

​create-node

​create-client

​list

​Complete Setup Guide

​Certificate Files Reference

​Certificate Rotation

​Troubleshooting

​Security Best Practices

​Related Documentation

Build docs developers (and LLMs) love

Overview

Commands

create-ca

create-node

create-client

list

Complete Setup Guide

Certificate Files Reference

Certificate Rotation

Troubleshooting

Security Best Practices

Related Documentation