AWS CDK(Python)实战:用客户管理密钥(CMK)加密创建 DynamoDB 全局表

原创2026-10-14 20:34:151,963 阅读

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-cdk CLI 固定在 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,是入口栈,完成两件事:

  1. 创建子栈并传递参数(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 导出名。也就是说,全局表横跨"主区域 + 所有副本区域",数量与密钥创建范围完全一致。

  1. 建立部署依赖: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 中的默认参数进行实际部署验证。

登录后查看全文
aws-cdk-examples