From cockroachdb
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.
npx claudepluginhub cockroachdb/claude-plugin --plugin cockroachdbThis skill uses the workspace's default tool permissions.
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.
Guides provisioning Google AlloyDB clusters, read pools, columnar engine, Private Service Access, PostgreSQL tuning on GCP, and Cloud SQL migrations.
Secures ClickHouse deployments with SQL-based RBAC, restricted users, roles, row-level security, network restrictions, TLS, and audit logging. For hardening access controls.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
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.
CockroachDB Cloud:
ccloud auth login)Self-hosted:
Verify access:
# Cloud
ccloud auth whoami
ccloud cluster list
# Self-hosted — check existing certificates
cockroach cert list --certs-dir=<certs-directory>
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.
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.
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:
~/.postgresql/root.crt~/.postgresql/root.crt or /etc/cockroach-certs/ca.crt%APPDATA%\postgresql\root.crtClient 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.
Client certificates should be rotated before expiry. The cluster CA certificate is managed by Cockroach Labs and rotated automatically.
Client certificate rotation:
Client CA rotation:
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.
# Create the CA certificate and key
cockroach cert create-ca \
--certs-dir=certs \
--ca-key=my-safe-directory/ca.key
# 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
# 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
# Check certificate expiry
cockroach cert list --certs-dir=certs
# Or with OpenSSL
openssl x509 -in certs/node.crt -noout -enddate
Rotation process:
kill -SIGHUP $(pgrep cockroach)
See troubleshooting reference for a comprehensive error guide.
"x509: certificate signed by unknown authority"
sslrootcert in the connection string"SSL SYSCALL error: EOF detected"
"tls: bad certificate"
"certificate has expired"
# 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
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
| 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:
Cloud — Client CA issues:
Self-hosted — Certificate issues:
kill -SIGHUP $(pgrep cockroach)Skill references:
Related skills:
Official CockroachDB Documentation: