managing-certificates-and-encryption

证书和加密管理

管理所有部署层级中的 TLS 证书和加密密钥生命周期。在提供操作步骤之前，此技能会收集上下文，以确定操作员是直接管理证书（Self-Hosted）、管理 CMEK 加密密钥（Advanced/BYOC），还是使用完全托管的加密（Standard/Basic）。

何时使用此技能

• 监控证书过期时间（Self-Hosted）
• 执行计划的证书轮换（Self-Hosted）
• 管理 CMEK 加密密钥（Advanced/BYOC）
• 应对密钥泄露（Self-Hosted、CMEK）
• 审计加密状况以满足合规要求（所有层级）
• 向节点证书添加 DNS 名称或 IP（Self-Hosted）

**日常运行状况检查：**使用 reviewing-cluster-health。

---

第 1 步：收集上下文

必需的上下文

问题	选项	重要性
部署层级？	Self-Hosted、Advanced、BYOC、Standard、Basic	确定加密管理责任归属
原因？	常规监控、计划轮换、密钥泄露、合规审计、添加 SAN 条目	确定紧急程度和操作步骤

其他上下文（按层级）

如果是 Self-Hosted：

问题	选项	重要性
证书类型？	CA、节点、客户端、UI	不同类型的轮换操作步骤不同
部署平台？	裸机/VM、Kubernetes（Operator/Helm/手动）	影响轮换工具
证书工具？	cockroach cert、openssl、HashiCorp Vault、cert-manager	确定证书生成命令
是否要轮换 CA？	是、否	CA 轮换需要采用组合 CA 方式

如果是 Advanced 或 BYOC：

问题	选项	重要性
是否涉及 CMEK？	是、否	CMEK 的加密责任由客户承担；TLS 由 CRL 管理
云服务提供商？	AWS、GCP、Azure	确定 KMS 服务和 CLI 命令
当前是否已启用 CMEK？	是、否	必须在创建集群时启用 CMEK

**如果是 Standard 或 Basic：**无需收集上下文 — TLS 和加密均由平台完全托管。这些层级不支持 CMEK。

根据上下文选择操作路径

层级 + 场景	前往
Self-Hosted	Self-Hosted 证书管理
Advanced/BYOC + CMEK	CMEK 密钥管理
Advanced/BYOC + TLS 问题	云端 TLS（托管）
Standard	完全托管的加密
Basic	完全托管的加密

---

Self-Hosted 证书管理

**适用条件：**层级 = Self-Hosted

监控证书过期时间

没有生产环境安全的 SQL 视图可以显示证书过期时间。请使用以下方法之一：

# Inspect certs locally on each node
cockroach cert list --certs-dir=<certs-dir>

# Or read a specific cert file
openssl x509 -in <certs-dir>/node.crt -noout -enddate

# Or scrape the per-node Prometheus endpoint (UNIX seconds for ca, node, client_ca, ui_ca)
curl -ks https://<node>:8080/_status/vars | grep '^security_certificate_expiration_'

告警阈值：CA 剩余有效期 < 1 年 = 计划轮换。节点证书剩余有效期 < 90 天 = 安排轮换。节点证书剩余有效期 < 30 天 = 立即轮换。

轮换节点证书（使用相同的 CA）

cockroach cert create-node <hostname> <ip> <lb-hostname> <lb-ip> localhost 127.0.0.1 \
  --certs-dir=<certs-dir> --ca-key=<ca-key-path> --overwrite

将证书部署到节点，并对密钥文件设置 chmod 0600。CockroachDB 会自动检测新证书 — 无需重启。

详细步骤和验证方法请参阅 rotation-procedures reference。

轮换 CA 证书

为实现无缝信任过渡，CA 轮换需要使用组合证书（新 CA + 旧 CA）：

1. 生成新的 CA 密钥和证书
2. 创建组合 CA 文件：cat new-ca.crt old-ca.crt > ca.crt
3. 将组合 CA 部署到所有节点
4. 重新签发由新 CA 签名的节点和客户端证书
5. 所有实体都使用由新 CA 签名的证书后，从组合文件中移除旧 CA

完整的 CA 轮换流程请参阅 rotation-procedures reference。

Kubernetes 证书管理

• **CockroachDB Operator：**自动轮换自签名证书。通过 tls.certs.selfSigner.rotateCerts 配置。
• **cert-manager：**自动续期。Pod 可能需要重启才能使用新证书。

详细的 Kubernetes 操作流程请参阅 kubernetes-certs reference。

---

CMEK 密钥管理

**适用情况：**Tier = Advanced 或 BYOC，且已启用 CMEK

什么是 CMEK

客户管理的加密密钥（CMEK）使用存储在云服务提供商 KMS 中的密钥，对 CockroachDB 静态数据加密所用的密钥进行封装。CockroachDB Cloud 无法访问 CMEK 本身。

CMEK 要求在创建集群时启用了高级安全功能的 Advanced 集群。集群创建后无法追溯启用。Standard 或 Basic 不支持 CMEK。

检查 CMEK 状态

curl -s -H "Authorization: Bearer $COCKROACH_API_KEY" \
  "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>/cmek" | jq '.'

或者：Cloud Console → Cluster → Security → Encryption。

轮换 CMEK 密钥

在云服务提供商的 KMS 中轮换密钥。CockroachDB Cloud 会自动使用新版本的密钥。集群无需停机。

有关特定提供商的 KMS 轮换命令（AWS KMS、GCP Cloud KMS、Azure Key Vault）和 IAM 审计流程，请参阅 cmek-procedures reference。

紧急情况：撤销 CMEK 密钥

撤销 CMEK 密钥会使集群数据永久无法访问，除非在 KMS 提供商的宽限期内恢复密钥。

**仅可用作紧急终止开关。**此操作可能无法撤销。

---

云端 TLS（托管）

**适用情况：**Tier = Advanced 或 BYOC，问题与 TLS 有关（而非 CMEK）

在 Advanced 和 BYOC 上，TLS 证书由 Cockroach Labs 完全托管：

• 自动配置、轮换和续期
• 无需客户采取任何操作
• CRL 会监控证书运行状况

**客户端证书：**你需要自行管理应用连接使用的客户端证书。这些是标准 PostgreSQL 客户端证书。

---

完全托管的加密

**适用情况：**Tier = Standard 或 Basic

TLS 证书和静态数据加密均由 Cockroach Labs 完全托管。

• 无需查看证书或负责轮换
• 始终启用传输中加密
• 始终启用静态数据加密
• 这些层级不支持 CMEK

**如果需要 CMEK：**升级到 Advanced。

---

安全注意事项

只读监控查询在所有层级上均安全。

自托管证书操作：

• 轮换前务必备份现有证书
• 使用组合 CA 方案，切勿突然替换 CA
• 确认 SAN 条目包含所有主机名、IP 和负载均衡器地址
• CA 密钥必须与节点证书分开存储
• 文件权限：密钥文件必须设置为 0600 模式，并归 Cockroach 进程用户所有

CMEK 操作（Advanced/BYOC）：

• 撤销 CMEK 密钥会导致数据永久无法访问
• KMS 密钥轮换前后均需验证 IAM 权限
• 先在暂存集群中测试 CMEK 轮换

详细的风险矩阵请参阅 safety-guide reference。

故障排除

问题	Tier	解决方法
证书指标为 NULL	SH	确认集群处于安全模式
未检测到新证书	SH	检查文件权限（0600，所有者正确）
“unknown authority” 错误	SH	部署组合 CA（新证书 + 旧证书）
轮换后连接失败	SH	检查 SAN 条目是否涵盖所有主机名/IP
CMEK 访问被拒绝	ADV/BYOC	验证 KMS 密钥策略和 IAM 权限
无法启用 CMEK	ADV/BYOC	必须在创建集群时启用 CMEK

参考资料

技能参考资料：

• 证书轮换流程
• Kubernetes 证书管理
• 各云服务提供商的 CMEK 流程
• 安全指南

相关技能：

• 检查集群运行状况
• 管理集群设置

CockroachDB 官方文档：

• 轮换安全证书
• cockroach cert
• TLS 和 PKI 参考
• 管理 CMEK