AWS CDK 自定义资源实战:在 aws-cdk-examples 中用 Provider + Lambda 封装可复用 Construct
AWS CDK 自定义资源实战:在 aws-cdk-examples 中用 Provider + Lambda 封装可复用 Construct
本文以 aws-cdk-examples 仓库中的 typescript/custom-resource 示例 为主体,系统讲解如何通过 aws-cdk-lib/custom-resources 的 Provider 框架与一个 Python Lambda 处理函数,实现 CDK 自定义资源(Custom Resource)的完整闭环。读完本文,你将掌握自定义资源在"构造设计(design of constructs)"与"架构组件化(separating architecture into components)"中的典型用法,能够独立编写、构建、部署并验证一个自定义资源,也理解其背后的事件协议与底层机制。
示例概览:仅依赖核心 CDK 库的 Stable 示例
typescript/custom-resource 是仓库中标注为 Stable 的示例:README 的稳定性徽标明确说明它"开箱即可成功构建(should successfully build out of the box)",并且只依赖 CDK 核心库,没有任何额外的基础设施前置条件——不需要预先准备 VPC、密钥、已有资源等,cdk deploy 即可完成端到端部署。
整个示例的目录结构非常精简,共 7 个文件:
| 文件 | 作用 |
|---|---|
| index.ts | CDK 应用入口,定义 Stack 并消费自定义资源的返回值 |
| my-custom-resource.ts | 核心:把"自定义资源"封装成一个可复用的 Construct |
| custom-resource-handler.py | 自定义资源的事件处理函数(Python),实现业务逻辑 |
| cdk.json | CDK 应用配置,定义 app 启动命令与上下文开关 |
| package.json | 依赖与构建脚本(build、watch、cdk) |
| tsconfig.json | TypeScript 编译配置(严格模式,noEmit) |
| jest.config.js | 基于 @swc/jest 的 TypeScript 测试环境配置 |
这个示例的核心价值正如 README 所述:它展示了如何向 CDK 应用添加一个自定义资源,而自定义资源正是设计构造(design of constructs)、或将架构拆分为组件(separating your architecture into components)时的有力工具。
为什么需要自定义资源:Construct 设计与架构组件化
CDK 内置的 L2 构造(如 s3.Bucket、lambda.Function)覆盖面很广,但真实业务中总会有 CDK 尚未封装、或必须调用 AWS 底层 API 才能完成的"最后一公里"操作,例如:
- 在资源创建后执行一次性的初始化动作(写入种子数据、预热缓存、触发外部系统);
- 调用 CDK 尚无官方构造的服务 API(如某些较新的 AWS 服务);
- 编排无法用纯 CloudFormation 表达的资源依赖关系。
CloudFormation 原生提供的答案是 AWS::CloudFormation::CustomResource:它允许你提供一个"服务令牌(ServiceToken)",让 CloudFormation 在资源的 Create / Update / Delete 生命周期中回调你的代码。而在本示例中,这一步被抽象成了两层:
customResources.Provider(来自aws-cdk-lib/custom-resources):AWS CDK 官方提供的自定义资源 Provider 框架,替你处理与 CloudFormation 之间的响应回传、SNS 事件分发等底层机制;MyCustomResourceConstruct:把"Provider + 处理函数 + 资源声明 + 属性提取"整体封装成一个对外只暴露message输入与response输出的构造。
这样封装之后,使用方(这里是 index.ts 中的 Stack)完全不需要关心"自定义资源怎么和 CloudFormation 通信",只需像使用普通 L2 构造一样 new MyCustomResource(...) 并读取属性即可——这正是 README 强调的"将架构拆分为组件"的落地方式。
源码剖析:三层结构
1. 对外暴露的 Construct:MyCustomResource
my-custom-resource.ts 是整篇示例的灵魂。它首先定义了构造的输入属性接口:
export interface MyCustomResourceProps {
/**
* Message to echo
*/
message: string;
}
随后在构造内部依次创建四个关键对象(my-custom-resource.ts#L20-L35):
const fn = new lambda.SingletonFunction(this, 'Singleton', {
uuid: 'f7d4f730-4ee1-11e8-9c2d-fa7ae01bbebc',
code: new lambda.InlineCode(fs.readFileSync('custom-resource-handler.py', { encoding: 'utf-8' })),
handler: 'index.main',
timeout: cdk.Duration.seconds(300),
runtime: lambda.Runtime.PYTHON_3_14,
});
const provider = new customResources.Provider(this, 'Provider', {
onEventHandler: fn,
});
const resource = new cdk.CustomResource(this, 'Resource', {
serviceToken: provider.serviceToken,
properties: props,
});
this.response = resource.getAttString('Response');
逐个拆解:
lambda.SingletonFunction:以uuid(f7d4f730-4ee1-11e8-9c2d-fa7ae01bbebc)为唯一标识,保证整个 CDK 应用中该函数只存在一份实例。多个构造、多个 Stack 共享同一处理函数时不会重复创建 Lambda。lambda.InlineCode:把仓库中的 custom-resource-handler.py 内容以内联代码方式注入 Lambda,无需额外的打包目录或外部构建步骤。handler: 'index.main':Lambda 的入口是打包后模块index中的main函数,对应 Python 文件中的def main(event, context)。timeout: cdk.Duration.seconds(300):处理函数超时设为 300 秒(5 分钟)。自定义资源处理通常涉及 API 调用,300 秒在 Lambda 15 分钟(900 秒)上限内是稳健的取值。runtime: lambda.Runtime.PYTHON_3_14:当前示例使用 Python 3.14 运行时(对应本仓库锁定的aws-cdk-lib版本)。customResources.Provider:以fn作为onEventHandler构建 Provider 框架。Provider 内部会创建 SNS 主题与框架 Lambda,负责把 CloudFormation 的生命周期事件转发给onEventHandler,并把处理结果回传给 CloudFormation。provider.serviceToken即框架对外暴露的服务令牌 ARN。cdk.CustomResource:CDK 核心库对AWS::CloudFormation::CustomResource的 L1 封装,把serviceToken与构造属性props(即message)一并下发给 CloudFormation。getAttString('Response'):读取自定义资源返回属性Response,并以public readonly response: string暴露给外部。这样"读取属性"的细节也被封装进了构造内部,外部只需访问resource.response。
2. 应用入口与属性消费:index.ts
index.ts 演示了如何使用这个构造,并展示如何从自定义资源中取出属性(README 原话:shows how to get an attribute from it):
class MyStack extends cdk.Stack {
constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const resource = new MyCustomResource(this, 'DemoResource', {
message: 'CustomResource says hello',
});
// Publish the custom resource output
new cdk.CfnOutput(this, 'ResponseMessage', {
description: 'The message that came back from the Custom Resource',
value: resource.response
});
}
}
const app = new cdk.App();
new MyStack(app, 'CustomResourceDemoStack');
app.synth();
调用方只做了三件事:
- 传入
message: 'CustomResource says hello'实例化构造; - 通过
resource.response拿到自定义资源返回的字符串; - 用
CfnOutput把它发布为 Stack 输出ResponseMessage。
Stack 名为 CustomResourceDemoStack,app.synth() 完成模板合成。这也是本示例与 README 中"部署后可见 API 的 URL"那句描述的差异点:结合当前源码看,该示例不涉及 API 网关,实际产出的是 ResponseMessage 栈输出,部署时请以 cdk deploy 打印的栈输出为准。
3. 事件处理函数:custom-resource-handler.py
自定义资源处理函数 是业务逻辑的落点,完整代码如下:
def main(event, context):
import logging as log
log.getLogger().setLevel(log.INFO)
# This needs to change if there are to be multiple resources in the same stack
physical_id = 'TheOnlyCustomResource'
try:
log.info('Input event: %s', event)
# Check if this is a Create and we're failing Creates
if event['RequestType'] == 'Create' and event['ResourceProperties'].get('FailCreate', False):
raise RuntimeError('Create failure requested')
# Do the thing
message = event['ResourceProperties']['message']
attributes = {
'Response': 'You said "%s"' % message
}
return { 'Data': attributes }
except Exception as e:
log.exception(e)
return { 'Data': {} }
它演示了自定义资源事件协议的核心约定:
event['RequestType']:CloudFormation 会在Create/Update/Delete三种生命周期事件中调用处理函数。event['ResourceProperties']:即 CDK 侧通过properties: props传入的构造属性,这里读取message。- 返回值
{ 'Data': attributes }:Data中的键值对会成为自定义资源的属性,供Fn::GetAtt(对应 CDK 的getAttString('Response'))读取。本示例把'You said "CustomResource says hello"'写入Response键。 physical_id常量:代码注释明确提示"如果同一栈中要存在多个该资源,这里需要修改"。它代表资源的物理 ID(PhysicalResourceId),是 CloudFormation 识别"同一个"资源实例的关键标识;当多个实例共用同一处理函数时,必须为不同实例生成不同的物理 ID,否则 CloudFormation 会认为物理资源冲突。可以注意到,当前版本的 handler 虽定义了physical_id,但并未在返回结果中使用它,其存在与注释更多是编写规范提示。FailCreate失败注入钩子:当属性中传入FailCreate: true且请求类型为Create时,主动抛出RuntimeError('Create failure requested'),用于模拟创建失败、验证异常路径。
值得深入指出的一点(可从源码推断):由于 raise 语句位于 try 块之内,FailCreate 抛出的异常会被 except 捕获并记录日志,最终仍返回空 Data,并不会真正让 CloudFormation 感知到失败。若希望真实触发创建失败与回滚,需要让异常向上抛出(交由 Provider 框架的失败处理逻辑),或在响应中显式返回失败状态。这种"宽泛 except + 空 Data"的写法在当前示例中是可接受的演示风格,但在生产代码中需谨慎权衡。
理解 Provider 框架的服务令牌与事件协议
要真正读懂这个示例,有必要区分两条实现路线:
路线 A:裸写 cdk.CustomResource + 自研处理函数。 处理函数必须自行实现完整的 CloudFormation 自定义资源协议:解析 RequestType,在 Create/Update/Delete 中做对应处理,并把结果 POST 回事件里的 ResponseURL(一个预签名的 S3 URL),同时正确处理失败重试。协议细节多、易出错。
路线 B:使用 customResources.Provider 框架(本示例采用)。 Provider 把协议层完全接管——内部由 SNS 主题与框架 Lambda 构成,你只需实现 onEventHandler 并返回约定格式的结果,框架负责把结果回传给 CloudFormation、处理响应 URL 与重试等细节。CDK 侧再通过 serviceToken 把框架暴露给 AWS::CloudFormation::CustomResource。
两类事件请求中,处理函数最常读取的字段包括:
| 字段 | 含义 |
|---|---|
RequestType |
Create / Update / Delete,当前生命周期阶段 |
ResourceProperties |
创建/更新时传入的资源属性(即 CDK 的 properties) |
OldResourceProperties |
Update 时携带的旧属性(用于比对变更) |
PhysicalResourceId |
Update / Delete 时标识既有资源实例 |
ResponseURL |
需要回传结果的预签名 URL(使用框架时由框架代为处理) |
而处理函数的响应约定中,Data 字段就是 CDK 侧 getAttString 能够读到的属性来源——这正是本示例 'Response' 键从 Python 一路传回 TypeScript resource.response 的完整链路。
构建、部署与模板合成
安装依赖
README 给出了三步构建流程(需在该示例根目录 typescript/custom-resource 下执行):
npm install -g aws-cdk
npm install
npm run build
- 第一条全局安装 CDK CLI(本示例 package.json 的
devDependencies中同样锁定了aws-cdk版本,未全局安装时可用npx cdk替代); - 第二条安装示例依赖,核心是
aws-cdk-lib与constructs; - 第三条执行
npm run build,即tsc。
需要说明的一点:本示例 tsconfig.json 开启了 "noEmit": true,因此 tsc 实际承担的是严格模式类型检查(strict、noImplicitAny、strictNullChecks 等全部开启)。真正的模板合成发生在 CDK 应用运行时——cdk.json 中配置的启动命令为:
"app": "npx tsc && npx tsx index.ts"
即先做一次类型检查,再用 tsx 直接执行 TypeScript 入口 index.ts。所以 npm run build 保证代码类型正确,而 cdk synth / cdk deploy 才会触发模板生成。
部署
cdk deploy
该命令会把 CustomResourceDemoStack 部署(或重新部署)到你的 AWS 账号。部署过程中 CloudFormation 会创建:Provider 框架相关资源(SNS 主题、框架 Lambda)、事件处理 Lambda(SingletonFunction)、以及最终的 AWS::CloudFormation::CustomResource——后者会在创建时回调处理函数,并把返回值回传给 CloudFormation。部署完成后,终端会显示 Stack 输出,其中 ResponseMessage 即处理函数返回的 You said "CustomResource says hello"。
合成 CloudFormation 模板
cdk synth
执行后,生成的 CloudFormation 模板会输出到 cdk.out 目录。建议在部署前先运行一次 cdk synth,检查模板中 CustomResourceDemoStack 下的 AWS::CloudFormation::CustomResource 资源定义、ServiceToken 指向、以及 Lambda 的运行时与处理函数配置,确认无误后再 cdk deploy。若想对比本地代码与线上栈的差异,还可使用 cdk diff 查看变更。
实战要点与扩展建议
综合源码与运行机制,本示例可以提炼出以下可直接迁移到生产项目的经验:
- 把"资源"封装成构造,隐藏实现细节。
MyCustomResource只暴露message输入与response输出,调用方无需了解 Provider、Lambda 或事件协议,天然契合"架构组件化"的目标。 - 善用
SingletonFunction+uuid。 多个构造共享同一段处理逻辑时,靠uuid去重可以避免重复创建 Lambda、降低部署成本。 - 注意物理资源 ID 的唯一性。 处理函数中
physical_id的注释提醒:同一 Stack 内若存在多个自定义资源实例,必须为各实例返回不同的PhysicalResourceId,避免 CloudFormation 判定资源冲突。 - 失败路径要显式设计。 当前 handler 的宽泛
except会把异常吞掉并返回空Data,导致 CloudFormation 无法感知失败;生产代码应让关键异常穿透处理函数,交由框架执行失败响应与重试。 - 属性读取与输出。 用
resource.getAttString('Response')提取自定义资源返回的属性,再通过CfnOutput或下游构造消费,是自定义资源"产出可复用值"的标准姿势。 - 测试基建已就绪。 示例自带的 jest.config.js 配置了
@swc/jest转换与testMatch: <a href="https://link.gitcode.com/i/324cde4841d656299fc27710fd5da682" target="_blank">'**/*.test.ts'],并启用了aws-cdk-lib/testhelpers/jest-autoclean。虽然本示例未附带测试用例,但你可以参照仓库根目录的 [SNAPSHOT_TESTING.md 的规范,为模板合成结果补充快照测试,锁定CustomResource的ServiceToken与属性行为。 - 超时与运行时随版本演进。
timeout: 300s与PYTHON_3_14均以本仓库锁定的aws-cdk-lib版本为准,升级 CDK 时建议同步核对运行时支持情况与 Provider 框架行为变化。
小结
typescript/custom-resource 虽然只有 7 个文件,却完整覆盖了 CDK 自定义资源的全部关键链路:Construct 封装(my-custom-resource.ts)→ customResources.Provider 服务框架 → AWS::CloudFormation::CustomResource → Python 事件处理函数(custom-resource-handler.py)→ 属性回传与栈输出(index.ts)。它既是一个可以直接 npm install && cdk deploy 的稳定示例,也是一份理解"构造设计"与"架构组件化"的最佳入门教材——当你在 CDK 项目中遇到"官方构造覆盖不到、又必须由代码驱动"的资源操作时,本文展示的模式就是可以直接落地的答案。