managing-certificates-and-encryption

用途

本技能用于管理 CockroachDB 在所有部署层级上的 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。

使用方式：先收集上下文

必需上下文：

部署层级：Self-Hosted、Advanced、BYOC、Standard、Basic。决定加密管理责任归属。
原因：例行监控、计划轮换、密钥泄露、合规审计、添加 SAN 条目。决定紧急程度与流程。

Self-Hosted 的附加上下文：

证书类型：CA、Node、Client、UI。不同类型轮换流程不同。
部署平台：裸机/虚拟机、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 视图可暴露证书到期信息。可使用以下方式之一：

# 在每个节点本地检查证书
cockroach cert list --certs-dir=<certs-dir>

# 或读取特定证书文件
openssl x509 -in <certs-dir>/node.crt -noout -enddate

# 或抓取每节点 Prometheus 端点（ca、node、client_ca、ui_ca 的 UNIX 秒）
curl -ks https://<node>:8080/_status/vars | grep '^security_certificate_expiration_'

告警阈值：CA < 1 年 = 计划轮换。Node < 90 天 = 安排轮换。Node < 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 参考。

轮换 CA 证书

CA 轮换需要合并证书（新 + 旧）以实现无缝信任过渡：

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

完整 CA 轮换流程见 rotation-procedures 参考。

Kubernetes 证书管理

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

详细 Kubernetes 流程见 kubernetes-certs 参考。

CMEK 密钥管理

适用于：层级 = 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 参考。

紧急情况：撤销 CMEK 密钥

撤销 CMEK 密钥会使集群数据永久不可访问，除非在 KMS 服务商的宽限期内恢复密钥。

仅作为紧急终止开关使用。此操作可能不可逆。

云 TLS（托管）

适用于：层级 = Advanced 或 BYOC，且问题涉及 TLS（非 CMEK）。

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

配置、轮换与续期均自动完成
无需客户操作
证书健康由 CRL 监控
客户端证书：应用连接所需的客户端证书由你自行管理。这些是标准 PostgreSQL 客户端证书。

全托管加密

适用于：层级 = Standard 或 Basic。

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

无证书可见性或轮换责任
传输中加密始终启用
静态加密始终启用
这些层级不提供 CMEK

如需 CMEK：升级到 Advanced。

安全注意事项

只读监控查询在所有层级都是安全的。

Self-Hosted 证书操作：

轮换前始终备份现有证书
使用合并 CA 方式——切勿突然替换 CA
验证 SAN 条目包含所有主机名、IP 和负载均衡器地址
CA 密钥必须与节点证书分开存储
文件权限：密钥文件必须为 0600 模式，属主为 cockroach 进程用户

CMEK 操作（Advanced/BYOC）：

CMEK 密钥撤销会使数据永久不可访问
在 KMS 密钥轮换前后验证 IAM 权限
先在暂存集群中测试 CMEK 轮换

详细风险矩阵见 safety-guide 参考。

故障排查

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

参考

技能参考：

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