AWS CDK 自定义资源实战:在 aws-cdk-examples 中用 Provider + Lambda 封装可复用 Construct

原创2026-10-14 19:04:322,247 阅读

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 生命周期中回调你的代码。而在本示例中,这一步被抽象成了两层:

  1. customResources.Provider(来自 aws-cdk-lib/custom-resources):AWS CDK 官方提供的自定义资源 Provider 框架,替你处理与 CloudFormation 之间的响应回传、SNS 事件分发等底层机制;
  2. MyCustomResource Construct:把"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();

调用方只做了三件事:

  1. 传入 message: 'CustomResource says hello' 实例化构造;
  2. 通过 resource.response 拿到自定义资源返回的字符串;
  3. 用 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 查看变更。

实战要点与扩展建议

综合源码与运行机制,本示例可以提炼出以下可直接迁移到生产项目的经验:

  1. 把"资源"封装成构造,隐藏实现细节。 MyCustomResource 只暴露 message 输入与 response 输出,调用方无需了解 Provider、Lambda 或事件协议,天然契合"架构组件化"的目标。
  2. 善用 SingletonFunction + uuid。 多个构造共享同一段处理逻辑时,靠 uuid 去重可以避免重复创建 Lambda、降低部署成本。
  3. 注意物理资源 ID 的唯一性。 处理函数中 physical_id 的注释提醒:同一 Stack 内若存在多个自定义资源实例,必须为各实例返回不同的 PhysicalResourceId,避免 CloudFormation 判定资源冲突。
  4. 失败路径要显式设计。 当前 handler 的宽泛 except 会把异常吞掉并返回空 Data,导致 CloudFormation 无法感知失败;生产代码应让关键异常穿透处理函数,交由框架执行失败响应与重试。
  5. 属性读取与输出。 用 resource.getAttString('Response') 提取自定义资源返回的属性,再通过 CfnOutput 或下游构造消费,是自定义资源"产出可复用值"的标准姿势。
  6. 测试基建已就绪。 示例自带的 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 与属性行为。
  7. 超时与运行时随版本演进。 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 项目中遇到"官方构造覆盖不到、又必须由代码驱动"的资源操作时,本文展示的模式就是可以直接落地的答案。

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