Agent Skill · Cockroach Labs

managing-tls-certificates

Manages TLS certificates for CockroachDB clusters including CA certificate configuration, client certificate authentication, certificate rotation, and troubleshooting SSL/TLS connection errors. Use when setting up client certificate auth, resolving SSL connection failures, rotating certificates, or configuring mTLS for CDC changefeeds.

View SKILL.md on GitHub → Source repository Provider profile
Provider: Cockroach Labs Path in repo: skills/cockroachdb-security-and-governance/managing-tls-certificates/SKILL.md

Skill body

Managing TLS Certificates

Manages TLS certificates for CockroachDB clusters, covering CA certificate downloads, client certificate authentication setup, certificate rotation, and troubleshooting common SSL/TLS connection errors. Addresses both CockroachDB Cloud (always-on TLS) and self-hosted certificate lifecycle management.

When to Use This Skill

Prerequisites

CockroachDB Cloud:

Self-hosted:

Verify access:

# Cloud
ccloud auth whoami
ccloud cluster list

# Self-hosted — check existing certificates
cockroach cert list --certs-dir=<certs-directory>

Configuration Decisions

Before proceeding, determine the user’s deployment model. Ask which option applies, then follow only the relevant sections below.

Decision 1 — Deployment model:

Parts 3 (Troubleshooting) and 4 (mTLS for CDC) apply to both deployment models.

Steps

Part 1: CockroachDB Cloud TLS

Follow this part if the user selected CockroachDB Cloud in Decision 1.

CockroachDB Cloud enforces TLS on all connections. The cluster CA certificate is managed by Cockroach Labs.

1.1 Download the CA Certificate

The CA certificate is required by clients to verify the cluster’s identity.

# Download via ccloud CLI
ccloud cluster cert <cluster-id>

# Or download from the Cloud Console:
# Cluster > Connect > Download CA Cert

The CA certificate is also available at: https://cockroachlabs.cloud/clusters/<cluster-id>/cert

Common CA cert locations after download:

1.2 Configure Client Certificate Authentication

Client certificate auth provides mutual TLS (mTLS) — the client proves its identity via certificate instead of a password.

Step 1: Upload a Client CA to the cluster

The Client CA signs your client certificates. This is separate from the cluster’s CA.

# Upload a Client CA certificate via ccloud CLI
ccloud cluster cert set-client-ca <cluster-id> --cert-file <client-ca.crt>

Step 2: Create a client certificate signed by your Client CA

# Generate a client key and certificate signing request
openssl genrsa -out client.<username>.key 2048
openssl req -new -key client.<username>.key \
  -out client.<username>.csr \
  -subj "/CN=<username>"

# Sign the CSR with your Client CA
openssl x509 -req -in client.<username>.csr \
  -CA client-ca.crt -CAkey client-ca.key \
  -CAcreateserial \
  -out client.<username>.crt \
  -days 365

Step 3: Connect using the client certificate

cockroach sql \
  --url "postgresql://<username>@<cluster-host>:26257/defaultdb?sslmode=verify-full&sslrootcert=<ca.crt>&sslcert=client.<username>.crt&sslkey=client.<username>.key"

See connection examples reference for client-specific connection strings.

1.3 Certificate Rotation (Cloud)

Client certificates should be rotated before expiry. The cluster CA certificate is managed by Cockroach Labs and rotated automatically.

Client certificate rotation:

  1. Generate a new client certificate signed by the same Client CA (or a new Client CA)
  2. Deploy the new certificate to application clients
  3. Verify connections work with the new certificate
  4. Remove the old certificate from application clients

Client CA rotation:

  1. Generate a new Client CA
  2. Upload the new Client CA to the cluster (supports multiple CAs during transition)
  3. Issue new client certificates signed by the new CA
  4. Deploy new client certificates to all applications
  5. Remove the old Client CA after all clients have migrated

Part 2: Self-Hosted Certificate Management

Follow this part if the user selected Self-hosted in Decision 1.

Self-hosted CockroachDB requires manual certificate lifecycle management for the CA, node, and client certificates.

2.1 Initialize the Certificate Authority

# Create the CA certificate and key
cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.2 Create Node Certificates

# Create a node certificate for each node
cockroach cert create-node \
  <node-hostname> \
  <node-ip> \
  localhost \
  127.0.0.1 \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.3 Create Client Certificates

# Create a client certificate for root user
cockroach cert create-client root \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

# Create a client certificate for an application user
cockroach cert create-client <username> \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

2.4 Certificate Rotation (Self-Hosted)

# Check certificate expiry
cockroach cert list --certs-dir=certs

# Or with OpenSSL
openssl x509 -in certs/node.crt -noout -enddate

Rotation process:

  1. Generate new certificates using the existing CA (or rotate the CA first)
  2. Copy new certificates to each node
  3. Reload certificates (SIGHUP — no downtime required): 
    kill -SIGHUP $(pgrep cockroach)
  4. Verify nodes are serving the new certificates

Part 3: Troubleshooting SSL/TLS Errors

See troubleshooting reference for a comprehensive error guide.

Common Errors and Quick Fixes

“x509: certificate signed by unknown authority”

“SSL SYSCALL error: EOF detected”

“tls: bad certificate”

“certificate has expired”

Diagnostic Commands

# Inspect a certificate
openssl x509 -in cert.crt -text -noout

# Verify certificate chain
openssl verify -CAfile ca.crt client.crt

# Test TLS connection to cluster
openssl s_client -connect <host>:26257 -CAfile ca.crt

# Check certificate expiry date
openssl x509 -in cert.crt -noout -enddate

Part 4: mTLS for CDC Changefeeds to Kafka

CockroachDB CDC changefeeds can use mTLS to authenticate to Kafka brokers.

-- Create a changefeed with mTLS authentication to Kafka
CREATE CHANGEFEED FOR TABLE orders
  INTO 'kafka://<kafka-broker>:9093?tls_enabled=true&ca_cert=<base64-ca>&client_cert=<base64-cert>&client_key=<base64-key>'
  WITH updated, resolved;

Preparing certificates for changefeed URI:

# Base64 encode certificates for use in changefeed URI
cat ca.crt | base64 -w 0    # Linux
cat ca.crt | base64          # macOS

cat client.crt | base64 -w 0
cat client.key | base64 -w 0

Safety Considerations

Impact Type Severity Recommendation
Client CA upload Low Does not affect existing connections; only adds a new trust root
Client CA removal High Invalidates all client certificates signed by that CA
Certificate expiry High Monitor expiry dates; rotate before expiration
Wrong CA certificate Medium Clients will fail to connect; correctable by updating the CA cert

Do not:

Rollback

Cloud — Client CA issues:

  1. If a new Client CA was uploaded incorrectly, upload the correct CA
  2. If client certificates are rejected, revert to password authentication temporarily
  3. Contact CockroachDB support if the cluster CA needs intervention

Self-hosted — Certificate issues:

  1. Restore previous certificates from backup
  2. Reload certificates: kill -SIGHUP $(pgrep cockroach)
  3. If CA was rotated, ensure all nodes and clients have the new CA

References

Skill references:

Related skills:

Official CockroachDB Documentation:

Skill frontmatter

compatibility: Requires ccloud CLI for Cloud clusters. Requires admin access and cockroach cert CLI for self-hosted clusters. metadata: {"author" => "cockroachdb", "version" => "1.0"}