Back to Details

enabling-cmek-encryption

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Enabling CMEK Encryption

启用CMEK加密

Enables Customer-Managed Encryption Keys (CMEK) on CockroachDB Cloud clusters so that data-at-rest encryption is controlled by keys in the organization's own cloud provider KMS (AWS KMS, GCP Cloud KMS, or Azure Key Vault). CMEK gives organizations full control over key lifecycle, rotation, and revocation.
为CockroachDB Cloud集群启用客户管理加密密钥（CMEK），以便静态数据加密由组织自身云提供商KMS（AWS KMS、GCP Cloud KMS或Azure Key Vault）中的密钥控制。CMEK让组织能够完全控制密钥的生命周期、轮换和撤销。

When to Use This Skill

何时使用此技能

  • Enabling CMEK for regulatory or compliance requirements (SOC 2, HIPAA, PCI DSS)
  • Verifying CMEK is properly configured after initial setup
  • Rotating CMEK keys per organization key rotation policy
  • Responding to a security audit finding about encryption at rest
  • Understanding CMEK requirements and plan prerequisites
  • 为满足监管或合规要求（SOC 2、HIPAA、PCI DSS）启用CMEK
  • 初始设置后验证CMEK配置是否正确
  • 根据组织密钥轮换策略轮换CMEK密钥
  • 响应关于静态数据加密的安全审计发现
  • 了解CMEK的要求和计划前提条件

Prerequisites

前提条件

  • CockroachDB Cloud Advanced plan — CMEK is not available on Basic or Standard plans
  • Advanced Security Add-on — Must be enabled on the Advanced plan cluster
  • Cloud provider KMS:
    • AWS: KMS key in the same region as the cluster, with appropriate IAM policy
    • GCP: Cloud KMS key ring and key in the same region, with appropriate IAM bindings
    • Azure: Key Vault with key in the same region, with appropriate access policies
  • ccloud CLI authenticated with Cluster Admin role
  • Cross-account access: The CockroachDB Cloud service account must have permission to use the KMS key
Check plan eligibility:
bash
undefined
  • CockroachDB Cloud高级计划 —— CMEK不适用于基础版或标准版计划
  • 高级安全附加组件 —— 必须在高级计划集群上启用
  • 云提供商KMS：
    • AWS： 与集群同区域的KMS密钥，并配置适当的IAM策略
    • GCP： 与集群同区域的Cloud KMS密钥环和密钥，并配置适当的IAM绑定
    • Azure： 包含同区域密钥的Key Vault，并配置适当的访问策略
  • 已通过Cluster Admin角色认证的ccloud CLI
  • 跨账户访问： CockroachDB Cloud服务账户必须拥有使用KMS密钥的权限
检查计划资格：
bash
undefined

Verify cluster plan type

验证集群计划类型

ccloud cluster info <cluster-name> -o json
ccloud cluster info <cluster-name> -o json

Look for "plan": "ADVANCED" and Advanced Security Add-on status

查找 "plan": "ADVANCED" 和高级安全附加组件状态

undefined
undefined

Configuration Decisions

配置决策

Before proceeding, determine which cloud provider KMS the user will use. Ask which option applies to their environment, then follow only the corresponding subsection in Step 2.
Decision 1 — Cloud provider KMS:
  • AWS KMS: Use when the CockroachDB Cloud cluster runs on AWS. Requires a symmetric encryption key in the same region as the cluster.
  • GCP Cloud KMS: Use when the cluster runs on GCP. Requires a key ring and key in the same region.
  • Azure Key Vault: Use when the cluster runs on Azure. Requires a Key Vault with a key in the same region.
在开始之前，确定用户将使用哪个云提供商的KMS。询问用户的环境适用哪个选项，然后仅遵循步骤2中对应的小节。
决策1 —— 云提供商KMS：
  • AWS KMS： 当CockroachDB Cloud集群运行在AWS上时使用。需要与集群同区域的对称加密密钥。
  • GCP Cloud KMS： 当集群运行在GCP上时使用。需要与集群同区域的密钥环和密钥。
  • Azure Key Vault： 当集群运行在Azure上时使用。需要包含同区域密钥的Key Vault。

Steps

步骤

1. Verify Plan and Add-on Eligibility

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

bash
ccloud cluster info <cluster-name> -o json
If Standard plan: CMEK is not available. The upgrade path is:
  1. Upgrade to Advanced plan (contact CockroachDB sales or upgrade in Cloud Console)
  2. Enable the Advanced Security Add-on
If Advanced plan without Advanced Security Add-on: Enable the add-on in the Cloud Console before proceeding.
bash
ccloud cluster info <cluster-name> -o json
如果是标准版计划： CMEK不可用。升级路径为：
  1. 升级到高级计划（联系CockroachDB销售团队或在云控制台中升级）
  2. 启用高级安全附加组件
如果是高级计划但未启用高级安全附加组件： 在继续之前先在云控制台中启用该附加组件。

2. Create a KMS Key in Your Cloud Provider

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

Follow only the subsection for the user's cloud provider (selected in Configuration Decisions above).
仅遵循用户云提供商对应的小节（在上述配置决策中选择的）。

AWS KMS

AWS KMS

bash
undefined
bash
undefined

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>

Grant the CockroachDB Cloud service account access to the key:
```json
{
  "Effect": "Allow",
  "Principal": {
    "AWS": "<cockroachdb-cloud-service-account-arn>"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:GenerateDataKey",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}
aws kms create-key
--description "CockroachDB CMEK - <cluster-name>"
--key-usage ENCRYPT_DECRYPT
--origin AWS_KMS
--region <aws-region>

为CockroachDB Cloud服务账户授予密钥访问权限：
```json
{
  "Effect": "Allow",
  "Principal": {
    "AWS": "<cockroachdb-cloud-service-account-arn>"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:GenerateDataKey",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}

GCP Cloud KMS

GCP Cloud KMS

bash
undefined
bash
undefined

Create a key ring

创建密钥环

gcloud kms keyrings create cockroachdb-cmek
--location <gcp-region>
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

Grant the CockroachDB Cloud service account access:
```bash
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"
gcloud kms keys create cmek-key
--keyring cockroachdb-cmek
--location <gcp-region>
--purpose encryption

为CockroachDB Cloud服务账户授予访问权限：
```bash
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

Azure Key Vault

bash
undefined
bash
undefined

Create a key in the existing Key Vault

在现有Key Vault中创建密钥

az keyvault key create
--vault-name <vault-name>
--name cockroachdb-cmek
--kty RSA
--size 2048

Grant the CockroachDB Cloud managed identity access via Key Vault access policies.
az keyvault key create
--vault-name <vault-name>
--name cockroachdb-cmek
--kty RSA
--size 2048

通过Key Vault访问策略为CockroachDB Cloud托管身份授予访问权限。

3. Configure CMEK on the Cluster

3. 在集群上配置CMEK

bash
undefined
bash
undefined

Enable CMEK with the KMS key URI

使用KMS密钥URI启用CMEK

ccloud cluster update <cluster-id>
--cmek-key-spec '<key-spec-json>'

The key spec format varies by cloud provider. Refer to the CockroachDB Cloud documentation for the exact JSON structure for your provider.

See [ccloud commands reference](references/ccloud-commands.md) for detailed command syntax.
ccloud cluster update <cluster-id>
--cmek-key-spec '<key-spec-json>'

密钥规格格式因云提供商而异。请参考CockroachDB Cloud文档获取适用于您提供商的确切JSON结构。

有关详细命令语法，请参阅[ccloud命令参考](references/ccloud-commands.md)。

4. Verify CMEK Configuration

4. 验证CMEK配置

bash
undefined
bash
undefined

Check CMEK status

检查CMEK状态

ccloud cluster info <cluster-name> -o json
ccloud cluster info <cluster-name> -o json

Verify cmek_config shows enabled status and correct key URI

验证cmek_config显示已启用状态和正确的密钥URI


```sql
-- Verify encryption via SQL
SHOW CLUSTER SETTING enterprise.encryption.type;

```sql
-- 通过SQL验证加密状态
SHOW CLUSTER SETTING enterprise.encryption.type;

5. Test Key Accessibility

5. 测试密钥可访问性

After enabling CMEK, verify the cluster is operating normally:
sql
-- 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后，验证集群是否正常运行：
sql
-- 创建并查询测试表以验证读写功能正常
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;

Safety Considerations

安全注意事项

CMEK misconfiguration can make data inaccessible. If the KMS key is deleted, disabled, or access is revoked, the cluster will not be able to read or write data.
Before enabling CMEK:
  • Ensure the KMS key has appropriate deletion protection enabled
  • Verify the IAM/access policy grants are correct
  • Confirm the KMS key region matches the cluster region
  • Document the key URI and access policies
Key management risks:
  • Key deletion: Deleting the KMS key makes all cluster data permanently inaccessible
  • Access revocation: Revoking CockroachDB's access to the key will cause the cluster to stop serving reads and writes
  • Key rotation: Plan key rotation per your organization's policy; CockroachDB supports automatic re-encryption with rotated keys
CMEK配置错误会导致数据无法访问。 如果KMS密钥被删除、禁用或访问权限被撤销，集群将无法读取或写入数据。
启用CMEK之前：
  • 确保KMS密钥已启用适当的删除保护
  • 验证IAM/访问策略授予是否正确
  • 确认KMS密钥区域与集群区域匹配
  • 记录密钥URI和访问策略
密钥管理风险：
  • 密钥删除： 删除KMS密钥会导致所有集群数据永久无法访问
  • 访问权限撤销： 撤销CockroachDB对密钥的访问权限会导致集群停止提供读写服务
  • 密钥轮换： 根据组织的策略规划密钥轮换；CockroachDB支持使用轮换后的密钥自动重新加密数据

Rollback

回滚

CMEK cannot be disabled once enabled on a cluster. However:
  1. Key rotation: You can rotate to a new key at any time
  2. Access restoration: If access was accidentally revoked, restore the IAM/access policy to resume operations
  3. New cluster: If CMEK configuration is fundamentally wrong, create a new cluster and migrate data
Emergency — Key access lost:
  1. Restore KMS key access immediately (IAM policy, key re-enable)
  2. The cluster will resume operations once key access is restored
  3. If the key was permanently deleted, data recovery is not possible
CMEK一旦在集群上启用就无法禁用。不过：
  1. 密钥轮换： 您可以随时轮换到新密钥
  2. 访问权限恢复： 如果访问权限被意外撤销，恢复IAM/访问策略即可恢复操作
  3. 新建集群： 如果CMEK配置存在根本性错误，可创建新集群并迁移数据
紧急情况 —— 密钥访问丢失：
  1. 立即恢复KMS密钥访问权限（IAM策略、重新启用密钥）
  2. 恢复密钥访问权限后，集群将恢复正常运行
  3. 如果密钥被永久删除，数据将无法恢复

References

参考资料

Related skills:
  • auditing-cloud-cluster-security — Run a full security posture audit
Official CockroachDB Documentation:
Cloud Provider KMS Documentation:
相关技能：
  • auditing-cloud-cluster-security —— 运行完整的安全态势审计
官方CockroachDB文档：
云提供商KMS文档：