AWS CDK(Python)实战:用客户管理密钥(CMK)加密创建 DynamoDB 全局表
AWS CDK(Python)实战:用客户管理密钥(CMK)加密创建 DynamoDB 全局表
本篇文章围绕 aws-cdk-examples 仓库中的 global-table-with-cmk 示例 展开,讲解如何在 AWS CDK 中搭建"多区域 DynamoDB 全局表 + KMS 客户管理密钥(CMK)加密"的完整方案。由于截至示例编写时 CDK 尚无覆盖全局表与 CMK 组合的原生高层构造,该示例围绕 L1 构造 dynamodb.CfnGlobalTable 与 kms.CfnKey 自行编排了预置方案。读完本文,你将掌握:如何用 CDK 在主区域创建多区域 CMK、如何通过自定义资源在副本区域复制密钥、如何在全局表的每个副本上绑定各自的 KMS 主密钥,以及整套方案的环境准备与部署流程。
为什么需要这套自定义方案
DynamoDB 全局表(Global Table)可以将同一张表的数据自动复制到多个 AWS 区域,实现低延迟读取与跨区域容灾;而 KMS 客户管理密钥(Customer Managed Key,CMK)则允许企业对静态加密(SSE-KMS)密钥拥有完全控制权,包括自主管理密钥策略、启用轮换等。
示例 README 明确指出,当时 CDK 没有提供支持"全局表 + CMK"组合的原生构造(native construct),因此该仓库给出了一套基于 L1 构造的预置解决方案:
- 用
kms.CfnKey(L1 构造)在主区域创建 CMK; - 通过自定义资源(Custom Resource)在每个副本区域创建密钥副本(key replica);
- 用
dynamodb.CfnGlobalTable(L1 构造)创建全局表,并为每个区域的副本显式指定对应的 KMS 主密钥。
关于"当时"的判断依据:示例 requirements.txt 锁定
aws-cdk-lib>=2.262.0,<3.0.0,仓库根目录 python/package.json 将aws-cdkCLI 固定在2.1133.0。本文的代码与参数说明均以仓库内实际源码为准。
整体架构与目录结构
整套方案由三个层级组成:一个顶层 Stack 负责编排,两个 NestedStack 分别承担"密钥"与"表"的职责:
lib/global_ddb_cmk.py # 顶层 Stack:编排 CMK 与 DDB 两个子栈,建立依赖
lib/stacks/cmk_stack.py # CMKStack:主区域 CMK + 副本区域密钥复制 + ARN 导出
lib/stacks/dynamo_db_stack.py# DynamoDBStack:CfnGlobalTable + 每副本 SSE-KMS 绑定
app.py # CDK 入口:定义表名、主区域、副本区域、密钥别名
创建全局表之前,主区域与每一个副本区域都必须各自拥有一个 CMK,这是整个方案的核心前提。主区域的 CMK 由 cmk_stack.py 中的 kms.CfnKey 创建;副本区域的密钥则通过调用 KMS 的 replicateKey API 生成密钥副本。各区域的密钥 ARN 通过 CfnOutput 以"导出名(export name)"形式对外发布,DynamoDB 全局表栈再通过 Fn.import_value 跨栈引用这些 ARN,最终在 dynamo_db_stack.py 中完成全局表与加密的绑定。
一、主区域 CMK 的创建
cmk_stack.py 中的 CMKStack 继承 cdk.NestedStack,接收 table_name、key_replica_regions(副本区域列表)和可选的 key_alias 三个参数。
主区域的密钥使用 kms.CfnKey 创建(cmk_stack.py):
key_id = kms.CfnKey(
self,
"multi-region-cmk",
key_policy={
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": f"arn:aws:iam::{self.account}:root",
},
"Action": "kms:*",
"Resource": "*",
},
],
},
description=f"CMK for {table_name} in {self.region}",
enable_key_rotation=True,
enabled=True,
multi_region=True,
).attr_key_id
几个关键配置点的含义:
| 参数 | 配置值 | 说明 |
|---|---|---|
multi_region |
True |
创建多区域密钥(multi-Region key),这是副本区域能复制该密钥的前提。它的 attr_key_id 会被各区域的副本共享。 |
enable_key_rotation |
True |
启用密钥轮换,符合安全最佳实践(每年自动轮换密钥材料)。 |
enabled |
True |
密钥处于启用状态。 |
key_policy |
授权当前账户 root 执行 kms:* |
默认策略将账户 root 设为唯一管理员,后续可在此基础上为 Lambda、DynamoDB 等角色补充授权。 |
description |
CMK for {table_name} in {region} |
描述中注入表名与区域,便于在控制台辨识。 |
随后为密钥创建别名(cmk_stack.py):
kms.CfnAlias(
self,
"multi-region-cmk-alias",
alias_name=key_alias
or f"alias/multi-region-cmk-for-ddb-table-{table_name}",
target_key_id=key_id,
)
若上层未传入 key_alias,将自动生成 alias/multi-region-cmk-for-ddb-table-{table_name} 作为默认别名;示例 app.py 中则显式传入 alias/CMK-for-global-DDB-table-global-ddb-cmk-demo。
二、在副本区域创建密钥副本:自定义资源 + replicateKey
创建主密钥后,CMKStack 遍历 key_replica_regions,为每个副本区域调用 _create_key_replica(cmk_stack.py)。由于 CDK 没有直接封装"复制多区域密钥"的高层构造,示例使用 AWS 自定义资源(AwsCustomResource)在部署时调用 KMS 的 replicateKey API:
aws_sdk_call = cr.AwsSdkCall(
service="KMS",
action="replicateKey",
physical_resource_id=cr.PhysicalResourceId.of(
"CustomResource::KeyReplicaCreation"
),
parameters={"KeyId": key_id, "ReplicaRegion": replica_region},
)
cr.AwsCustomResource(
self,
f"{replica_region}-custom-resource",
on_create=aws_sdk_call,
on_update=aws_sdk_call,
policy=cr.AwsCustomResourcePolicy.from_statements(
[
iam.PolicyStatement(
effect=iam.Effect.ALLOW,
actions=["kms:*"],
resources=["*"],
)
]
),
)
要点说明:
AwsSdkCall指定调用 KMS 服务的replicateKey动作,参数为源密钥KeyId与目标副本区域ReplicaRegion;on_create与on_update都绑定同一调用,保证密钥复制操作在资源创建与更新时都会执行;- 自定义资源需要 IAM 权限,这里通过
AwsCustomResourcePolicy.from_statements授予kms:*通配权限,以便在任意区域完成密钥复制; physical_resource_id固定为CustomResource::KeyReplicaCreation,保证该自定义资源在多次更新时保持稳定、不会重复创建。
从源码结构看,该自定义资源只负责"复制密钥"这一动作,副本密钥的 ARN 并未从 API 返回值中解析,而是通过下述输出方式统一发布。
三、跨栈传递密钥 ARN:CfnOutput 导出 + Fn.import_value
CMKStack 为主区域和每个副本区域各发布一个 CfnOutput(cmk_stack.py):
def _create_cfn_output_key_arn(self, key_region: str, key_id: str):
cdk.CfnOutput(
self,
f"{key_region}-key-arn",
value=f"arn:aws:kms:{key_region}:{self.account}:key/{key_id}",
export_name=f"{self._key_arn_export_prefix}{key_region}",
)
- 导出名(export name)为
cmk-key-arn{region},例如主区域us-east-1对应cmk-key-arnus-east-1; - 由于多区域密钥的副本与主密钥共享同一个密钥 ID,
attr_key_id可直接用于拼接各区域 ARN,格式为arn:aws:kms:{region}:{account}:key/{key_id}; _key_arn_export_prefix = "cmk-key-arn"定义在 cmk_stack.py,get_key_replica_export_names(region)方法(cmk_stack.py)则对外暴露拼接规则,供编排层生成"区域 → 导出名"映射。
在 dynamo_db_stack.py 中,全局表为每个副本读取对应导出值:
replicas=[
ddb.CfnGlobalTable.ReplicaSpecificationProperty(
region=replica_config["region"],
sse_specification=ddb.CfnGlobalTable.ReplicaSSESpecificationProperty(
kms_master_key_id=cdk.Fn.import_value(
replica_config["key_export_name"]
)
),
)
for replica_config in table_replica_regions
],
即:每个副本区域都使用自己区域的 CMK 副本进行 SSE-KMS 加密,这正是文档所述"主区域与每个副本区域都需要各自的 CMK"的落地实现。
四、DynamoDB 全局表的定义与加密配置
dynamo_db_stack.py 中的 DynamoDBStack 同样继承 cdk.NestedStack,核心资源是 ddb.CfnGlobalTable(dynamo_db_stack.py):
ddb.CfnGlobalTable(
self,
"global-table",
table_name=table_name,
billing_mode="PAY_PER_REQUEST",
attribute_definitions=[
ddb.CfnGlobalTable.AttributeDefinitionProperty(
attribute_name="id", attribute_type="S"
)
],
key_schema=[
ddb.CfnGlobalTable.KeySchemaProperty(
attribute_name="id", key_type="HASH"
)
],
replicas=[...], # 见上文:每个副本绑定各自区域的 CMK
sse_specification=ddb.CfnGlobalTable.SSESpecificationProperty(
sse_enabled=True, sse_type="KMS"
),
stream_specification=ddb.CfnGlobalTable.StreamSpecificationProperty(
stream_view_type="KEYS_ONLY"
),
)
参数解读:
| 参数 | 取值 | 说明 |
|---|---|---|
billing_mode |
PAY_PER_REQUEST |
按量计费模式,全局表无需预先规划读写容量。 |
attribute_definitions |
id,类型 S(字符串) |
定义表的主键属性。 |
key_schema |
id 为 HASH 键 |
以 id 作为分区键。示例仅用单个属性演示,实际可按需扩展。 |
replicas |
每区域一个 ReplicaSpecificationProperty |
每个副本通过 ReplicaSSESpecificationProperty.kms_master_key_id 绑定该区域的 CMK ARN。 |
sse_specification |
sse_enabled=True, sse_type="KMS" |
全局开启 SSE-KMS 加密。 |
stream_specification |
stream_view_type="KEYS_ONLY" |
启用 DynamoDB Streams,仅捕获键属性变更,便于下游(Lambda、Kinesis 等)消费。 |
注意 replicas 列表来自 table_replica_regions: List<a href="https://link.gitcode.com/i/2398756c32fc453b06336550f04cfa42" target="_blank">ReplicaConfig],其中 ReplicaConfig 是 TypedDict([dynamo_db_stack.py),键为 region 与 key_export_name,由编排层统一组装。
五、编排层:把密钥栈与表栈串起来
global_ddb_cmk.py 中的 GlobalDDBTableCMK 继承 cdk.Stack,是入口栈,完成两件事:
- 创建子栈并传递参数(global_ddb_cmk.py):
cmk_stack = CMKStack(
self, "cmk-stack",
table_name=table_name,
key_replica_regions=replication_regions,
key_alias=key_alias,
)
ddb_stack = DynamoDBStack(
self, "ddb-stack",
table_name=table_name,
table_replica_regions=[
{
"region": region,
"key_export_name": cmk_stack.get_key_replica_export_names(region),
}
for region in [self.region, *replication_regions]
],
)
ddb_stack.add_dependency(cmk_stack)
这里有一个容易忽略的关键细节:table_replica_regions 的列表是 [self.region, *replication_regions]——主区域也会作为全局表的一个副本参与,并且同样绑定主区域的 CMK 导出名。也就是说,全局表横跨"主区域 + 所有副本区域",数量与密钥创建范围完全一致。
- 建立部署依赖:
ddb_stack.add_dependency(cmk_stack)保证全局表在密钥(及其副本)创建完成后才部署,避免出现表存在但副本密钥缺失的中间状态。
六、配置变量与运行入口
文档给出了四个需要按需修改的 CDK 变量,示例在 app.py 中提供了默认值:
TABLE_NAME: str = "global-ddb-cmk-demo"
PRIMARY_REGION: str = "us-east-1"
REPLICATIONS_REGIONS: List[str] = ["us-west-2", "us-east-2"]
KEY_ALIAS: Optional[str] = f"alias/CMK-for-global-DDB-table-{TABLE_NAME}"
| 变量 | 类型 | 默认值(示例) | 作用 |
|---|---|---|---|
TABLE_NAME |
str |
global-ddb-cmk-demo |
DynamoDB 全局表名称,同时用于生成密钥描述与默认别名。 |
PRIMARY_REGION |
str |
us-east-1 |
全局表的主部署区域,通过 env=cdk.Environment(region=PRIMARY_REGION) 传给顶层 Stack。 |
REPLICATIONS_REGIONS |
List[str] |
["us-west-2", "us-east-2"] |
副本区域列表;每个区域都会创建密钥副本并成为全局表副本。 |
KEY_ALIAS |
Optional[str] |
alias/CMK-for-global-DDB-table-global-ddb-cmk-demo |
主 CMK 的别名;留空时自动生成 alias/multi-region-cmk-for-ddb-table-{TABLE_NAME}。 |
app.py 随后实例化 GlobalDDBTableCMK 并调用 app.synth() 完成模板合成;cdk.json 中 "app": "python3 app.py" 指定了 CDK 的应用启动命令。
七、环境准备与部署步骤
1. 安装 CDK 与依赖
参照 python 示例运行指南,先全局安装 CDK CLI:
npm install -g aws-cdk
然后创建并激活 Python 虚拟环境(Windows 下可直接执行仓库自带的 source.bat 激活 .venv\Scripts\activate.bat):
python3 -m venv .venv
source .venv/bin/activate # Linux / macOS
# Windows: .venv\Scripts\activate.bat
安装依赖(requirements.txt 声明了 aws-cdk-lib>=2.262.0,<3.0.0 与 constructs>=10.5.0,<11.0.0;开发依赖 requirements-dev.txt 为 pytest==9.0.3,如需跑测试可一并安装):
pip install -r requirements.txt
2. Bootstrap 引导账户
首次部署前,必须先对涉及的区域执行引导,以创建 CDK 部署所需的资源(如 S3 上传桶):
cdk bootstrap
示例部署涉及多个区域,实际生产环境通常需要为每个区域分别执行 cdk bootstrap aws://ACCOUNT-ID/REGION;引导所需凭据以当前环境配置为准。
3. 部署方案
文档中的部署命令为 npm deploy,这应是笔误——本示例是纯 Python CDK 应用(入口由 cdk.json 的 python3 app.py 指定),且与 python 示例运行指南 及仓库内其他示例一致的正确命令是:
cdk deploy
执行后,CloudFormation 会按依赖顺序先创建主区域 CMK 与各副本密钥,再创建跨区域的 DynamoDB 全局表,并完成每个副本的 SSE-KMS 绑定。
4. 销毁资源
验证完成后,可清理整套栈(注意销毁前先处理密钥与表上的关联资源,避免残留):
cdk destroy
总结与注意事项
- 无原生构造,L1 组合是可行路径:当 CDK 高层构造未覆盖"全局表 + CMK"组合时,
kms.CfnKey+dynamodb.CfnGlobalTable+ 自定义资源这三件套即可完成完整闭环,本示例即为可直接参考的模板。 - 区域一致性是关键:密钥副本区域集合与全局表副本区域集合必须一一对应(编排层用
[self.region, *replication_regions]强制保证),每个副本的kms_master_key_id引用各自区域的密钥 ARN。 - 依赖顺序不可省略:
ddb_stack.add_dependency(cmk_stack)确保密钥先于表创建;跨栈引用通过CfnOutput导出 +Fn.import_value导入实现,注意导出名(cmk-key-arn{region})的拼接规则保持一致。 - 部署前务必 bootstrap:首次部署若不执行
cdk bootstrap,CDK 无法上传资产与执行自定义资源,replicateKey的调用将无法完成。
如需深入研读实现细节,建议对照阅读 cmk_stack.py、dynamo_db_stack.py 与 global_ddb_cmk.py,并配合 app.py 中的默认参数进行实际部署验证。