managing-certificates-and-encryption

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing Certificates and Encryption

证书与加密管理

Manages TLS certificate and encryption key lifecycle across all deployment tiers. Before providing procedures, this skill gathers context to determine whether the operator manages certificates directly (Self-Hosted), manages CMEK encryption keys (Advanced/BYOC), or has fully managed encryption (Standard/Basic).

管理所有部署层级的TLS证书和加密密钥生命周期。在提供操作流程前，本Skill会收集上下文信息，以确定操作人员是直接管理证书（Self-Hosted）、管理CMEK加密密钥（Advanced/BYOC），还是使用完全托管的加密服务（Standard/Basic）。

When to Use This Skill

何时使用本Skill

Monitoring certificate expiration (Self-Hosted)
Performing scheduled certificate rotation (Self-Hosted)
Managing CMEK encryption keys (Advanced/BYOC)
Responding to key compromise (Self-Hosted, CMEK)
Auditing encryption posture for compliance (all tiers)
Adding DNS names or IPs to node certificates (Self-Hosted)

For daily health checks: Use reviewing-cluster-health.

监控证书过期（Self-Hosted）
执行定期证书轮换（Self-Hosted）
管理CMEK加密密钥（Advanced/BYOC）
响应密钥泄露事件（Self-Hosted、CMEK场景）
审计加密状态以符合合规要求（所有层级）
为节点证书添加DNS名称或IP地址（Self-Hosted）

日常健康检查： 使用 reviewing-cluster-health。

Step 1: Gather Context

步骤1：收集上下文信息

Required Context

必填上下文

Question	Options	Why It Matters
Deployment tier?	Self-Hosted, Advanced, BYOC, Standard, Basic	Determines encryption management responsibility
Reason?	Routine monitoring, Scheduled rotation, Key compromise, Compliance audit, Add SAN entries	Determines urgency and procedure

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

Additional Context (by tier)

各层级补充上下文

If Self-Hosted:

Question	Options	Why It Matters
Certificate type?	CA, Node, Client, UI	Different rotation procedures per type
Deployment platform?	Bare metal/VMs, Kubernetes (Operator/Helm/manual)	Changes rotation tooling
Certificate tooling?	cockroach cert, openssl, HashiCorp Vault, cert-manager	Determines generation commands
Is the CA being rotated?	Yes, No	CA rotation requires combined CA approach

If Advanced or BYOC:

Question	Options	Why It Matters
Is this about CMEK?	Yes, No	CMEK is the customer's encryption responsibility; TLS is managed by CRL
Cloud provider?	AWS, GCP, Azure	Determines KMS service and CLI commands
CMEK currently enabled?	Yes, No	CMEK must be enabled at cluster creation

If Standard or Basic: No context needed — TLS and encryption are fully managed. CMEK is not available on these tiers.

若为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。

Context-Driven Routing

基于上下文的流程路由

Tier + Scenario	Go To
Self-Hosted	Self-Hosted Certificate Management
Advanced/BYOC + CMEK	CMEK Key Management
Advanced/BYOC + TLS question	Cloud TLS (Managed)
Standard	Fully Managed Encryption
Basic	Fully Managed Encryption

层级+场景	跳转至
Self-Hosted	自托管证书管理
Advanced/BYOC + CMEK	CMEK密钥管理
Advanced/BYOC + TLS相关问题	云端TLS（托管）
Standard	完全托管加密
Basic	完全托管加密

Self-Hosted Certificate Management

自托管证书管理

Applies when: Tier = Self-Hosted

适用场景： 层级 = Self-Hosted

Monitor Certificate Expiry

监控证书过期

sql

SELECT node_id,
  to_timestamp((metrics->>'security.certificate.expiration.ca')::FLOAT)::TIMESTAMPTZ AS ca_expires,
  to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ AS node_cert_expires,
  CASE WHEN to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ
            < now() + INTERVAL '90 days' THEN 'EXPIRING_SOON' ELSE 'OK' END AS status
FROM crdb_internal.kv_node_status ORDER BY node_cert_expires;

Alert thresholds: CA < 1 year = plan rotation. Node < 90 days = schedule rotation. Node < 30 days = rotate immediately.

sql

SELECT node_id,
  to_timestamp((metrics->>'security.certificate.expiration.ca')::FLOAT)::TIMESTAMPTZ AS ca_expires,
  to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ AS node_cert_expires,
  CASE WHEN to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ
            < now() + INTERVAL '90 days' THEN 'EXPIRING_SOON' ELSE 'OK' END AS status
FROM crdb_internal.kv_node_status ORDER BY node_cert_expires;

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

Rotate Node Certificates (Same CA)

轮换节点证书（使用原CA）

bash

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

Deploy to node, set

chmod 0600

on key file. CockroachDB auto-detects new certs — no restart required.

See rotation-procedures reference for detailed steps and verification.

bash

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。

Rotate CA Certificate

轮换CA证书

CA rotation requires a combined certificate (new + old) for seamless trust transition:

Generate new CA key and certificate
Create combined CA file:
```
cat new-ca.crt old-ca.crt > ca.crt
```
Deploy combined CA to all nodes
Re-issue node and client certificates signed by the new CA
After all entities use new-CA-signed certs, remove old CA from combined file

See rotation-procedures reference for the full CA rotation procedure.

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

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

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

Kubernetes Certificate Management

Kubernetes证书管理

CockroachDB Operator: Self-signer rotates automatically. Configure via
```
tls.certs.selfSigner.rotateCerts
```
.
cert-manager: Auto-renews. Pods may need restart to pick up new certs.

See kubernetes-certs reference for detailed Kubernetes procedures.

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

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

CMEK Key Management

CMEK密钥管理

Applies when: Tier = Advanced or BYOC, CMEK enabled

适用场景： 层级 = Advanced或BYOC，已启用CMEK

What Is CMEK

什么是CMEK

Customer-Managed Encryption Keys wrap CockroachDB's data-at-rest encryption with a key stored in your cloud provider's KMS. CockroachDB Cloud never has access to the CMEK itself.

CMEK requires an Advanced cluster with advanced security features enabled at cluster creation. It cannot be enabled retroactively. CMEK is not available on Standard or Basic.

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

CMEK需要在创建集群时启用高级安全功能的Advanced集群，无法事后启用。Standard和Basic层级不支持CMEK。

Check CMEK Status

检查CMEK状态

bash

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

Or: Cloud Console → Cluster → Security → Encryption.

bash

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

或通过：云控制台 → 集群 → 安全 → 加密。

Rotate CMEK Key

轮换CMEK密钥

Rotate the key in your cloud provider's KMS. CockroachDB Cloud automatically uses the new key version. No cluster downtime.

See cmek-procedures reference for provider-specific KMS rotation commands (AWS KMS, GCP Cloud KMS, Azure Key Vault) and IAM audit procedures.

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

各云服务商的KMS轮换命令（AWS KMS、GCP Cloud KMS、Azure Key Vault）和IAM审计流程请参阅 cmek-procedures reference。

Emergency: Revoke CMEK Key

紧急操作：撤销CMEK密钥

Revoking the CMEK key makes cluster data permanently inaccessible unless the key is restored within your KMS provider's grace period.

Only use as an emergency kill switch. This may be irreversible.

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

仅作为紧急终止开关使用，此操作可能无法逆转。

Cloud TLS (Managed)

云端TLS（托管）

Applies when: Tier = Advanced or BYOC, question is about TLS (not CMEK)

TLS certificates are fully managed by Cockroach Labs on Advanced and BYOC:

Provisioning, rotation, and renewal are automatic
No customer action needed
Certificate health is monitored by CRL

Client certificates: You manage your own client-side certificates for application connections. These are standard PostgreSQL client certificates.

适用场景： 层级 = Advanced或BYOC，问题涉及TLS（非CMEK）

Advanced和BYOC层级的TLS证书由Cockroach Labs完全托管：

自动配置、轮换和续期
无需客户操作
证书健康状态由CRL监控

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

Fully Managed Encryption

完全托管加密

Applies when: Tier = Standard or Basic

TLS certificates and data-at-rest encryption are fully managed by Cockroach Labs.

No certificate visibility or rotation responsibility
Encryption in transit is always enabled
Encryption at rest is always enabled
CMEK is not available on these tiers

If CMEK is required: Upgrade to Advanced.

适用场景： 层级 = Standard或Basic

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

无需关注证书可见性或承担轮换责任
始终启用传输加密
始终启用静态加密
这些层级不支持CMEK

若需要CMEK： 升级至Advanced版本。

Safety Considerations

安全注意事项

Read-only monitoring queries are safe on all tiers.

Self-Hosted certificate operations:

Always backup existing certificates before rotation
Use combined CA approach — never abruptly replace the CA
Verify SAN entries include ALL hostnames, IPs, and load balancer addresses
CA key must be stored separately from node certificates
File permissions: key files must be mode 0600, owned by cockroach process user

CMEK operations (Advanced/BYOC):

CMEK key revocation renders data permanently inaccessible
Verify IAM permissions before and after KMS key rotation
Test CMEK rotation in a staging cluster first

See safety-guide reference for detailed risk matrix.

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

自托管证书操作：

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

CMEK操作（Advanced/BYOC）：

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

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

Troubleshooting

故障排查

Issue	Tier	Fix
Cert metric NULL	SH	Verify cluster is in secure mode
New cert not detected	SH	Check file permissions (0600, correct owner)
"unknown authority" error	SH	Deploy combined CA (new + old)
Connection failures after rotation	SH	Check SAN entries cover all hostnames/IPs
CMEK access denied	ADV/BYOC	Verify KMS key policy and IAM permissions
Cannot enable CMEK	ADV/BYOC	CMEK must be enabled at cluster creation

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

References

参考资料

Skill references:

Certificate rotation procedures
Kubernetes certificate management
CMEK procedures by cloud provider
Safety guide

Related skills:

reviewing-cluster-health
managing-cluster-settings

Official CockroachDB Documentation:

Skill参考：

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

相关Skill：

reviewing-cluster-health
managing-cluster-settings

CockroachDB官方文档：