enabling-cmek-encryption

启用 CMEK 加密

在 CockroachDB Cloud 集群上启用客户管理的加密密钥（CMEK），使静态数据加密由组织自己的云提供商 KMS（AWS KMS、GCP Cloud KMS 或 Azure Key Vault）中的密钥控制。CMEK 让组织能够全面控制密钥生命周期、轮换和撤销。

何时使用此技能

• 为满足法规或合规要求（SOC 2、HIPAA、PCI DSS）启用 CMEK
• 初始设置后验证 CMEK 是否正确配置
• 根据组织的密钥轮换策略轮换 CMEK 密钥
• 响应有关静态数据加密的安全审计发现
• 了解 CMEK 要求和计划前提条件

前提条件

• CockroachDB Cloud Advanced 计划 — Basic 或 Standard 计划不提供 CMEK
• Advanced Security 附加组件 — 必须在 Advanced 计划集群上启用
• 云提供商 KMS：
  • AWS： 与集群位于同一区域的 KMS 密钥，并配置适当的 IAM 策略
  • GCP： 与集群位于同一区域的 Cloud KMS 密钥环和密钥，并配置适当的 IAM 绑定
  • Azure： 与集群位于同一区域的 Key Vault 密钥，并配置适当的访问策略
• ccloud CLI 已通过 Cluster Admin 角色进行身份验证
• 跨账户访问： CockroachDB Cloud 服务账户必须拥有使用 KMS 密钥的权限

检查计划资格：

# Verify cluster plan type
ccloud cluster info <cluster-name> -o json
# Look for "plan": "ADVANCED" and Advanced Security Add-on status

配置决策

继续之前，确定用户将使用哪个云提供商 KMS。询问哪种选项适用于其环境，然后在步骤 2 中仅按照对应的小节操作。

决策 1 — 云提供商 KMS：

• AWS KMS： CockroachDB Cloud 集群运行在 AWS 上时使用。需要与集群位于同一区域的对称加密密钥。
• GCP Cloud KMS： 集群运行在 GCP 上时使用。需要位于同一区域的密钥环和密钥。
• Azure Key Vault： 集群运行在 Azure 上时使用。需要包含位于同一区域密钥的 Key Vault。

步骤

1. 验证计划和附加组件资格

ccloud cluster info <cluster-name> -o json

如果是 Standard 计划： 不提供 CMEK。升级步骤如下：

1. 升级到 Advanced 计划（联系 CockroachDB 销售团队或在 Cloud Console 中升级）
2. 启用 Advanced Security 附加组件

如果是未启用 Advanced Security 附加组件的 Advanced 计划： 请在继续之前通过 Cloud Console 启用该附加组件。

2. 在云提供商中创建 KMS 密钥

仅按照与用户云提供商对应的小节操作（在上方的“配置决策”中选择）。

AWS KMS

# Create a symmetric encryption key in the same region as the cluster
aws kms create-key \
  --description "CockroachDB CMEK - <cluster-name>" \
  --key-usage ENCRYPT_DECRYPT \
  --origin AWS_KMS \
  --region <aws-region>

授予 CockroachDB Cloud 服务账户访问密钥的权限：

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "<cockroachdb-cloud-service-account-arn>"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:GenerateDataKey",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}

GCP Cloud KMS

# Create a key ring
gcloud kms keyrings create cockroachdb-cmek \
  --location <gcp-region>

# Create a symmetric encryption key
gcloud kms keys create cmek-key \
  --keyring cockroachdb-cmek \
  --location <gcp-region> \
  --purpose encryption

授予 CockroachDB Cloud 服务账户访问权限：

gcloud kms keys add-iam-policy-binding cmek-key \
  --keyring cockroachdb-cmek \
  --location <gcp-region> \
  --member "serviceAccount:<cockroachdb-cloud-service-account>" \
  --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

Azure Key Vault

# Create a key in the existing Key Vault
az keyvault key create \
  --vault-name <vault-name> \
  --name cockroachdb-cmek \
  --kty RSA \
  --size 2048

通过 Key Vault 访问策略授予 CockroachDB Cloud 托管标识访问权限。

3. 在集群上配置 CMEK

# Enable CMEK with the KMS key URI
ccloud cluster update <cluster-id> \
  --cmek-key-spec '<key-spec-json>'

密钥规范的格式因云提供商而异。有关适用于您提供商的确切 JSON 结构，请参阅 CockroachDB Cloud 文档。

详细的命令语法请参阅 ccloud commands reference。

4. 验证 CMEK 配置

# Check CMEK status
ccloud cluster info <cluster-name> -o json
# Verify cmek_config shows enabled status and correct key URI

CMEK 状态不会作为 SQL 集群设置公开；对于托管集群，Cloud Console 中的 Cluster → Settings → Encryption 页面是权威信息来源。

5. 测试密钥可访问性

启用 CMEK 后，请验证集群运行正常：

-- Create and query a test table to verify read/write works
CREATE TABLE cmek_test (id INT PRIMARY KEY, data STRING);
INSERT INTO cmek_test VALUES (1, 'encryption test');
SELECT * FROM cmek_test;
DROP TABLE cmek_test;

安全注意事项

CMEK 配置错误可能导致数据无法访问。 如果 KMS 密钥被删除、禁用或撤销访问权限，集群将无法读取或写入数据。

启用 CMEK 前：

• 确保已为 KMS 密钥启用适当的删除保护
• 验证 IAM/访问策略授权是否正确
• 确认 KMS 密钥所在区域与集群所在区域一致
• 记录密钥 URI 和访问策略

密钥管理风险：

• 密钥删除： 删除 KMS 密钥会导致所有集群数据永久无法访问
• 撤销访问权限： 撤销 CockroachDB 对密钥的访问权限会导致集群停止提供读取和写入服务
• 密钥轮换： 按照组织的策略规划密钥轮换；CockroachDB 支持使用轮换后的密钥自动重新加密

回滚

在集群上启用 CMEK 后，无法将其禁用。不过：

1. 密钥轮换： 你可以随时轮换为新密钥
2. 恢复访问权限： 如果意外撤销了访问权限，请恢复 IAM/访问策略以恢复运行
3. 新建集群： 如果 CMEK 配置存在根本性错误，请创建新集群并迁移数据

紧急情况 — 丢失密钥访问权限：

1. 立即恢复 KMS 密钥访问权限（IAM 策略、重新启用密钥）
2. 恢复密钥访问权限后，集群将恢复运行
3. 如果密钥已被永久删除，则无法恢复数据

参考资料

相关技能：

• auditing-cloud-cluster-security — 执行完整的安全状况审计

CockroachDB 官方文档：

• CMEK 概述
• 管理 Dedicated 集群的 CMEK
• CockroachDB Cloud 安全概述

云服务提供商 KMS 文档：

• AWS KMS
• GCP Cloud KMS
• Azure Key Vault