Back to Details

managing-tls-certificates

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Managing TLS Certificates

管理TLS证书

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集群的TLS证书，涵盖CA证书下载、客户端证书认证设置、证书轮换以及常见SSL/TLS连接错误排查。同时支持CockroachDB Cloud（始终启用TLS）和自托管集群的证书生命周期管理。

When to Use This Skill

适用场景

  • Troubleshooting SSL/TLS connection errors from application clients (DBeaver, TypeORM, psql, Go, Python, Java)
  • Setting up client certificate authentication on CockroachDB Cloud
  • Uploading a custom Client CA to a Cloud cluster
  • Rotating or renewing certificates (Cloud or self-hosted)
  • Configuring mTLS for CDC changefeeds to Kafka
  • Downloading or locating the CA certificate for a Cloud cluster
  • 排查应用客户端（DBeaver、TypeORM、psql、Go、Python、Java）的SSL/TLS连接错误
  • 在CockroachDB Cloud上设置客户端证书认证
  • 向Cloud集群上传自定义Client CA
  • 轮换或续订证书（Cloud或自托管集群）
  • 为CDC changefeeds配置面向Kafka的mTLS
  • 下载或查找Cloud集群的CA证书

Prerequisites

前提条件

CockroachDB Cloud:
  • ccloud CLI authenticated (
    ccloud auth login
    )
  • Cloud Console access for CA certificate download
  • Cluster Admin role for client CA configuration
Self-hosted:
  • cockroach cert CLI available
  • Admin access to cluster nodes
  • OpenSSL for certificate inspection and generation
Verify access:
bash
undefined
CockroachDB Cloud：
  • ccloud CLI已完成认证（
    ccloud auth login
    ）
  • 拥有Cloud控制台访问权限用于下载CA证书
  • 拥有集群管理员角色用于配置Client CA
自托管集群：
  • 已安装cockroach cert CLI工具
  • 拥有集群节点的管理员访问权限
  • 已安装OpenSSL用于证书检查和生成
验证访问权限：
bash
undefined

Cloud

Cloud集群

ccloud auth whoami ccloud cluster list
ccloud auth whoami ccloud cluster list

Self-hosted — check existing certificates

自托管集群 — 检查现有证书

cockroach cert list --certs-dir=<certs-directory>
undefined
cockroach cert list --certs-dir=<certs-directory>
undefined

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:
  • CockroachDB Cloud: TLS is always on and the cluster CA is managed by Cockroach Labs. Follow Part 1 for CA download, client certificate auth, and Cloud certificate rotation.
  • Self-hosted: Full manual certificate lifecycle management (CA, node, and client certificates). Follow Part 2 for certificate creation, rotation, and management.
Parts 3 (Troubleshooting) and 4 (mTLS for CDC) apply to both deployment models.
开始操作前，请确定用户的部署模式。询问用户适用的选项，然后仅遵循对应章节的步骤。
决策1 — 部署模式：
  • CockroachDB Cloud： 始终启用TLS，集群CA证书由Cockroach Labs管理。请遵循第1部分进行CA证书下载、客户端证书认证和Cloud证书轮换。
  • 自托管集群： 需要手动管理CA、节点和客户端证书的完整生命周期。请遵循第2部分进行证书创建、轮换和管理。
第3部分（故障排查）和第4部分（CDC的mTLS配置）适用于两种部署模式。

Steps

操作步骤

Part 1: CockroachDB Cloud TLS

第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中选择CockroachDB Cloud，请遵循此部分。
CockroachDB Cloud强制所有连接使用TLS。集群CA证书由Cockroach Labs管理。

1.1 Download the CA Certificate

1.1 下载CA证书

The CA certificate is required by clients to verify the cluster's identity.
bash
undefined
客户端需要CA证书来验证集群身份。
bash
undefined

Download via ccloud CLI

通过ccloud CLI下载

ccloud cluster cert <cluster-id>
ccloud cluster cert <cluster-id>

Or download from the Cloud Console:

或从Cloud控制台下载：

Cluster > Connect > Download CA Cert

集群 > 连接 > 下载CA证书


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

**Common CA cert locations after download:**
- macOS: `~/.postgresql/root.crt`
- Linux: `~/.postgresql/root.crt` or `/etc/cockroach-certs/ca.crt`
- Windows: `%APPDATA%\postgresql\root.crt`

CA证书也可通过以下链接获取：`https://cockroachlabs.cloud/clusters/<cluster-id>/cert`

**下载后CA证书的常见存储位置：**
- macOS：`~/.postgresql/root.crt`
- Linux：`~/.postgresql/root.crt` 或 `/etc/cockroach-certs/ca.crt`
- Windows：`%APPDATA%\postgresql\root.crt`

1.2 Configure Client Certificate Authentication

1.2 配置客户端证书认证

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.
bash
undefined
客户端证书认证提供双向TLS（mTLS）——客户端通过证书而非密码证明身份。
步骤1：向集群上传Client CA
Client CA用于签署客户端证书，与集群CA相互独立。
bash
undefined

Upload a Client CA certificate via ccloud CLI

通过ccloud CLI上传Client CA证书

ccloud cluster cert set-client-ca <cluster-id> --cert-file <client-ca.crt>

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

```bash
ccloud cluster cert set-client-ca <cluster-id> --cert-file <client-ca.crt>

**步骤2：创建由Client CA签署的客户端证书**

```bash

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>"
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

使用Client CA签署CSR

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**

```bash
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.
openssl x509 -req -in client.<username>.csr
-CA client-ca.crt -CAkey client-ca.key
-CAcreateserial
-out client.<username>.crt
-days 365

**步骤3：使用客户端证书连接**

```bash
cockroach sql \
  --url "postgresql://<username>@<cluster-host>:26257/defaultdb?sslmode=verify-full&sslrootcert=<ca.crt>&sslcert=client.<username>.crt&sslkey=client.<username>.key"
查看连接示例参考文档获取客户端专属连接字符串。

1.3 Certificate Rotation (Cloud)

1.3 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
客户端证书应在过期前轮换。集群CA证书由Cockroach Labs管理并自动轮换。
客户端证书轮换：
  1. 使用相同Client CA（或新的Client CA）生成新客户端证书
  2. 将新证书部署到应用客户端
  3. 验证使用新证书可正常连接
  4. 从应用客户端移除旧证书
Client CA轮换：
  1. 生成新的Client CA
  2. 将新Client CA上传到集群（过渡期间支持多个CA）
  3. 签发由新CA签署的客户端证书
  4. 将新客户端证书部署到所有应用
  5. 待所有客户端完成迁移后移除旧Client CA

Part 2: Self-Hosted Certificate Management

第2部分：自托管集群证书管理

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.
如果用户在决策1中选择自托管集群，请遵循此部分。
自托管CockroachDB需要手动管理CA、节点和客户端证书的完整生命周期。

2.1 Initialize the Certificate Authority

2.1 初始化证书颁发机构（CA）

bash
undefined
bash
undefined

Create the CA certificate and key

创建CA证书和密钥

cockroach cert create-ca
--certs-dir=certs
--ca-key=my-safe-directory/ca.key
undefined
cockroach cert create-ca
--certs-dir=certs
--ca-key=my-safe-directory/ca.key
undefined

2.2 Create Node Certificates

2.2 创建节点证书

bash
undefined
bash
undefined

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
undefined
cockroach cert create-node
<node-hostname>
<node-ip>
localhost
127.0.0.1
--certs-dir=certs
--ca-key=my-safe-directory/ca.key
undefined

2.3 Create Client Certificates

2.3 创建客户端证书

bash
undefined
bash
undefined

Create a client certificate for root user

为root用户创建客户端证书

cockroach cert create-client root
--certs-dir=certs
--ca-key=my-safe-directory/ca.key
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
undefined
cockroach cert create-client <username>
--certs-dir=certs
--ca-key=my-safe-directory/ca.key
undefined

2.4 Certificate Rotation (Self-Hosted)

2.4 自托管集群证书轮换

bash
undefined
bash
undefined

Check certificate expiry

检查证书过期时间

cockroach cert list --certs-dir=certs
cockroach cert list --certs-dir=certs

Or with OpenSSL

或使用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):
   ```bash
   kill -SIGHUP $(pgrep cockroach)
  1. Verify nodes are serving the new certificates
openssl x509 -in certs/node.crt -noout -enddate

**轮换流程：**
1. 使用现有CA（或先轮换CA）生成新证书
2. 将新证书复制到每个节点
3. 重新加载证书（发送SIGHUP信号 — 无需停机）：
   ```bash
   kill -SIGHUP $(pgrep cockroach)
  1. 验证节点已使用新证书提供服务

Part 3: Troubleshooting SSL/TLS Errors

第3部分：SSL/TLS错误排查

See troubleshooting reference for a comprehensive error guide.
查看故障排查参考文档获取完整的错误指南。

Common Errors and Quick Fixes

常见错误与快速修复

"x509: certificate signed by unknown authority"
  • Client does not trust the cluster's CA certificate
  • Fix: Download the correct CA certificate and set 
    sslrootcert
    in the connection string
"SSL SYSCALL error: EOF detected"
  • Connection terminated unexpectedly during TLS handshake
  • Fix: Check network connectivity, firewall rules, and that the correct port (26257) is used
"tls: bad certificate"
  • Client certificate rejected by the server
  • Fix: Verify the client certificate is signed by a CA the cluster trusts (Client CA must be uploaded)
"certificate has expired"
  • Client or server certificate has passed its expiry date
  • Fix: Rotate the expired certificate (see rotation steps above)
"x509: certificate signed by unknown authority"
  • 客户端不信任集群的CA证书
  • 修复方法：下载正确的CA证书并在连接字符串中设置
    sslrootcert
"SSL SYSCALL error: EOF detected"
  • TLS握手期间连接意外终止
  • 修复方法：检查网络连通性、防火墙规则，确认使用正确端口（26257）
"tls: bad certificate"
  • 客户端证书被服务器拒绝
  • 修复方法：验证客户端证书由集群信任的CA签署（需已上传Client CA）
"certificate has expired"
  • 客户端或服务器证书已过期
  • 修复方法：轮换过期证书（参考上述轮换步骤）

Diagnostic Commands

诊断命令

bash
undefined
bash
undefined

Inspect a certificate

检查证书详情

openssl x509 -in cert.crt -text -noout
openssl x509 -in cert.crt -text -noout

Verify certificate chain

验证证书链

openssl verify -CAfile ca.crt client.crt
openssl verify -CAfile ca.crt client.crt

Test TLS connection to cluster

测试与集群的TLS连接

openssl s_client -connect <host>:26257 -CAfile ca.crt
openssl s_client -connect <host>:26257 -CAfile ca.crt

Check certificate expiry date

检查证书过期日期

openssl x509 -in cert.crt -noout -enddate
undefined
openssl x509 -in cert.crt -noout -enddate
undefined

Part 4: mTLS for CDC Changefeeds to Kafka

第4部分：面向Kafka的CDC Changefeeds mTLS配置

CockroachDB CDC changefeeds can use mTLS to authenticate to Kafka brokers.
sql
-- 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:
bash
undefined
CockroachDB CDC changefeeds可使用mTLS向Kafka代理认证。
sql
-- 创建面向Kafka的mTLS认证changefeed
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;
为changefeed URI准备证书：
bash
undefined

Base64 encode certificates for use in changefeed URI

对证书进行Base64编码以用于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
undefined
cat ca.crt | base64 -w 0 # Linux cat ca.crt | base64 # macOS
cat client.crt | base64 -w 0 cat client.key | base64 -w 0
undefined

Safety Considerations

安全注意事项

Impact TypeSeverityRecommendation
Client CA uploadLowDoes not affect existing connections; only adds a new trust root
Client CA removalHighInvalidates all client certificates signed by that CA
Certificate expiryHighMonitor expiry dates; rotate before expiration
Wrong CA certificateMediumClients will fail to connect; correctable by updating the CA cert
Do not:
  • Delete the CA private key — it is required for signing new certificates
  • Upload an expired CA certificate
  • Remove a Client CA while clients still depend on it
  • Disable TLS on production clusters (CockroachDB Cloud does not allow this)
影响类型严重程度建议
Client CA上传低不影响现有连接；仅添加新信任根
Client CA移除高会使所有由该CA签署的客户端证书失效
证书过期高监控过期日期；在过期前完成轮换
错误的CA证书中客户端将无法连接；可通过更新CA证书修复
禁止操作：
  • 删除CA私钥 — 签署新证书需要该密钥
  • 上传过期的CA证书
  • 在客户端仍依赖旧CA时移除Client CA
  • 在生产集群上禁用TLS（CockroachDB Cloud不允许此操作）

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
Cloud集群 — Client CA问题：
  1. 如果新Client CA上传错误，重新上传正确的CA
  2. 如果客户端证书被拒绝，暂时恢复为密码认证
  3. 若集群CA需要干预，请联系CockroachDB支持团队
自托管集群 — 证书问题：
  1. 从备份恢复之前的证书
  2. 重新加载证书：
    kill -SIGHUP $(pgrep cockroach)
  3. 若已轮换CA，确保所有节点和客户端都已部署新CA

References

参考资料

Skill references:
  • Client connection examples — Connection strings for common clients
  • TLS troubleshooting guide — Common SSL/TLS errors and fixes
Related skills:
  • auditing-cloud-cluster-security — Run a full security posture audit
  • configuring-sso-and-scim — SSO as an alternative to certificate-based auth
Official CockroachDB Documentation:
技能参考文档：
  • 客户端连接示例 — 常见客户端的连接字符串
  • TLS故障排查指南 — 常见SSL/TLS错误与修复方法
相关技能：
  • auditing-cloud-cluster-security — 执行完整安全态势审计
  • configuring-sso-and-scim — 作为证书认证替代方案的SSO配置
官方CockroachDB文档：