cdk-bootstrap-configuration

用途

CDK Bootstrap Configuration 是一个针对 AWS CDK 基础设施代码的参考模式，适用于处理 CDK 基础设施代码或新增配置参数的场景。它要解决的问题是：使用 CDK 的 valueFromLookup() 读取引导配置会引发上下文缓存（context caching）问题，导致需要手动干预，并在部署脚本与基础设施代码之间形成循环依赖。

资料将其定位为参考模式：「从中学习思路，结合自身场景调整，不要逐字复制」。其目标读者是 CDK 基础设施开发者；如果读者构建的是读取配置的服务，资料建议参考另一模式 SSM Runtime Configuration。

核心思路

将引导配置（部署输入）与运行时配置（基础设施输出）分离：

引导（Bootstrap）：基础设施创建之前就已存在的外部常量，例如域名、证书 ARN、账户 ID。通过 .env.{stage} 文件（本地）或 CI 变量提供，由 CDK 在 synth 时读取。
运行时（Runtime）：基础设施创建之后产生的结果。由基础设施写入 SSM Parameter Store，供服务、Lambda、前端在运行时消费。

核心原则为：SSM 应存储部署的结果（RESULT），而不是部署的输入（INPUT）。

架构流程分为四层：引导层（Pre-Infrastructure，存在于 .env.{stage} 文件或 CI 变量中，由 CDK 在 synth 时读取）→ CDK Synthesis（直接读取环境变量、synth 时不做 SSM 查询、生成 CloudFormation 模板）→ CDK Deployment（创建基础设施资源、将输出写入 SSM 供运行时消费）→ SSM Parameter Store（Post-Infrastructure，存放 Stack 输出，供服务在运行时读取）。

主要能力与关键组件

引导配置：创建基础设施所需的外部常量（域名、证书 ARN、账户 ID）。
环境管理器（Environment Manager）：从文件（本地）或环境变量（CI/CD）加载引导配置。
Stack Props：通过 props 传递引导值，使各 Stack 保持解耦。
SSM 输出：将基础设施结果写入 Parameter Store，供服务消费。

该模式声称的收益包括：消除 cdk.context.json 与手动干预；输入与输出在架构上清晰分离；同时适配本地与 CI 环境；synth 时进行类型安全校验，及早发现缺失配置；无循环依赖（部署脚本无需预填充 CDK 读取的内容）；不产生需纳入版本管理的环境相关上下文文件，对 Git 友好。

使用方式（实现要点）

资料给出的实现包含五个部分：

环境管理器：loadEnv(stage) 先尝试读取 infraRootPath 下的 .env.{stage} 文件，将其与过滤掉 undefined 的 process.env 合并，且 CI 变量覆盖文件值；若既无文件也无环境变量则抛出错误。getStackEnv(stackType) 调用 validateBootstrap 校验必需项后返回 IStackEnv。
CDK App 入口（bin/app.ts）：创建 EnvironmentManager，通过 getStackEnv 获取 stackEnv，将其传入 Stack 的 props（资料指出用 props 可让 Stack 与 EnvironmentManager 解耦、更易测试）。
Stack 实现：从 props.stackEnv 读取引导值（而非 SSM lookup），创建基础设施后，将输出通过 ssm.StringParameter 写入 SSM。资料在此处特别强调：移除所有针对引导值的 ssm.StringParameter.valueFromLookup() 调用。
Stack Props 接口（IStackEnv、WebStackProps）。
引导配置：本地使用被 gitignore 的 .env.{stage}，CI/CD 配置为仓库变量（如 GitHub Actions Variables、CodeBuild 环境变量等）。

校验细节：CDK_DEFAULT_ACCOUNT、CDK_DEFAULT_REGION 为必需项；生产环境额外要求 PROD_DOMAIN_NAME、CERTIFICATE_ARN；缺失时抛出包含缺失键名与检查位置的错误信息。合并策略为文件值 + process.env，CI 覆盖文件。

适用场景

带生产域名与证书的 CDK 项目
多环境部署（dev、staging、prod）
使用 CI/CD 流水线的项目
正在遭遇 CDK 上下文缓存问题的团队

限制与不适用情况

简单单环境项目：如果只有一个环境且没有生产域名，这种分离可能过度。
非 CDK 项目：该模式针对 AWS CDK 的上下文缓存问题。
无外部依赖的项目：如果所有配置都由 CDK 自身生成，更简单的方式可能已足够。
资料给出的备选方案：CDK Context Values（用于真正静态、永不变化的值，不推荐用于环境相关配置）；CloudFormation Parameters（用于每次部署都会变化的值，会增加部署复杂度）。

关于官方来源与收费

资料未提供官方文档链接、许可证、版本号、维护状态、收费或价格信息，这些内容暂未提供。

技能介绍

用途