面向中文开发者的 AWS 实战知识库 代维服务
上云咨询

AWS CDK(AWS CDK)服务指南:入门 · 配置 · 排错 · 代运维 · 部署

快速信息

它是什么

AWS CDK(AWS Cloud Development Kit)是一个开源的基础设施即代码框架:你用 TypeScript、Python、Java、C#/.NET 等通用编程语言描述云资源,CDK 把这些代码合成为标准的 CloudFormation 模板,再由 CloudFormation 完成资源的创建、更新与删除。它在架构中的位置是“定义层”,真正调用各服务 API 的是 CloudFormation——CDK 自己不保存部署状态,也不直接操作资源。

与相邻服务的边界值得说清:CloudFormation 是最底层的编排引擎,输入是 JSON/YAML 模板;CDK 是它的高层封装,最终产物仍是模板,可以用 cdk synth 导出后交给 CloudFormation 单独部署。Terraform 是另一套独立工具链,有自己的 provider 和 state 文件,与 CDK 不共享机制。SAM 关注 Serverless 应用的本地调试,CDK 可以把合成出的模板交给 SAM CLI 做本地测试,但 CDK 本身不做运行时模拟。AWS Copilot、AWS Amplify 这类更高层的工具,内部也是用 CDK 构建的。

一次 cdk deploy 大致经过:读取 cdk.json 与 App 定义 → 构造 Construct 树 → 在内存中合成模板与 assets → 写入 cdk.out → 上传 assets 到 bootstrap 阶段创建的 S3 桶或 ECR 仓库 → 调用 CloudFormation 执行部署。理解这条链路,是排查大多数 CDK 问题的起点。

核心概念

  • App:CDK 程序的根对象,代表一次部署的完整应用,一个 App 里可以包含多个 Stack。
  • Stack:对应一个 CloudFormation 栈,是部署与生命周期管理的最小单位;跨栈引用需要显式传值或使用导出。
  • Construct:可复用的资源组合单元,分为 L1(CfnXxx,与 CloudFormation 资源一一对应)、L2(带合理默认值和便捷方法,如 Bucket、Function)、L3(跨多个资源的完整模式)。
  • 合成(synth):把 Construct 树转换为 CloudFormation 模板与 assets 的过程,产物落在 cdk.out,可以离线检查而无需部署。
  • Bootstrap:在目标账号与区域部署 CDKToolkit 栈,提供存放 assets 的 S3 桶、ECR 仓库以及部署所需的 IAM 角色。

典型场景

  • 多环境同构部署:同一套代码通过参数和 context 生成 dev/staging/prod 不同规格的栈,避免复制粘贴多份模板。
  • Serverless 应用搭建:用 L2/L3 构造快速定义 API Gateway、Lambda、DynamoDB,权限与事件源映射由构造自动生成。
  • 需要编程能力的基础设施:循环创建多个相似资源、按条件决定是否创建、从配置文件读取参数,这些在纯声明式模板里很笨重。
  • 平台团队沉淀内部标准:把加密、日志、标签、告警等合规配置封装成自研 Construct,分发给业务团队复用,减少遗漏。

计费与成本要点

  • CDK 本身与 CDK CLI 不额外收费,CloudFormation 对资源编排也不单独计费,账单来自被创建的实际资源。
  • Bootstrap 与 assets 会带来少量存储和请求费用:S3 中的模板与资产、ECR 中的镜像,以及部分 L2 构造背后用于自定义资源的 Lambda 调用。
  • 省钱思路:临时环境用完及时 cdk destroy;给 assets 桶配置生命周期规则;避免高频全量部署造成的重复上传与重复调用。
  • 留意 RemovalPolicy/DeletionPolicy:设置为保留的资源在栈删除后仍然存在并继续计费,清理时需人工确认。

上手步骤

  1. 准备环境:安装 Node.js 与 CDK CLI(npm install -g aws-cdk),验证 cdk --version 有输出;同时配置好 AWS 凭证(aws configure 或 SSO 登录),用 aws sts get-caller-identity 验证身份正确。
  2. 初始化项目:cdk init app --language=typescript,验证生成了 bin/、lib/、cdk.json,且 cdk synth 能打印出模板内容。
  3. 执行 bootstrap:cdk bootstrap aws://<account-id>/<region>,验证 CloudFormation 控制台中出现 CDKToolkit 栈且状态正常。
  4. 编写第一个栈:在 lib/ 下的 stack 文件中添加一个 L2 构造(例如一个 Bucket),运行 cdk diff 预览将要创建的资源。
  5. 部署并验证:cdk deploy,在 CloudFormation 控制台确认栈状态为 CREATE_COMPLETE,并检查目标服务中资源已出现。
  6. 清理:cdk destroy,确认栈被删除;若存在保留策略的资源,需到对应服务中手动处理。

常见问题与排查

部署时报 assets 相关错误,提示需要 toolkit 栈

原因:目标账号与区域没有执行过 bootstrap,或 CDKToolkit 栈、其 S3 桶与角色被删除或权限被改。

处理:在正确的账号+区域重新执行 cdk bootstrap,并确认 CLI 使用的凭证指向该账号,必要时加 --profile 明确指定。

控制台手动改过的配置,下次部署被改回去或触发资源替换

原因:CDK 以合成模板为准,CloudFormation 检测到实际配置与模板不一致(drift),部署时会按模板覆盖或重建。

处理:把紧急改动回写到代码;用 drift detection 查看具体差异;存量资源可通过资源导入纳入栈管理,避免反复手工修。

部署报资源已存在或名称冲突

原因:物理名称被硬编码,或同名资源已在栈外创建,CloudFormation 无法接管。

处理:优先不显式指定物理名,交给 CDK 生成;确需固定名称时,先删除或导入已有资源,再重新部署。

cdk synth 通过但部署时属性解析报错

原因:在需要具体值的位置使用了环境无关栈(未指定 env),或引用了合成阶段无法解析的 context 值。

处理:为 Stack 明确指定 account 与 region;把环境相关取值放到 context 或 cdk.json 中传入,避免在查询类场景依赖隐式环境。

最佳实践

  • 把团队标准封装成自研 L3 构造,业务栈只做组合,加密、标签、日志等配置一次定义处处生效。
  • 保持合成结果确定:不要依赖随机值或当前时间,否则每次 cdk diff 都会出现无意义变更,掩盖真实风险。
  • 按生命周期拆分 Stack 并显式指定 env,避免一个巨型栈导致部署慢、失败影响面大、跨环境复用困难。
  • 在 CI 中固化 synth → diff → 审批 → deploy 的流程,并配合单元测试(assertions 模块)与规则检查守住底线。

常见问题

CDK 和 CloudFormation 是什么关系?

CDK 是编写层,最终合成为 CloudFormation 模板,实际资源由 CloudFormation 创建和管理。模板可导出后脱离 CDK 单独使用。

必须会 TypeScript 才能用吗?

不必。CDK 支持 TypeScript、Python、Java、C#/.NET 等多种语言,具体支持情况以官方文档为准,选团队最熟悉的即可。

CDK 会保存类似 Terraform 的 state 文件吗?

不会。部署状态由 CloudFormation 的栈维护,CDK 只负责合成模板与发起部署,因此不存在本地状态丢失的问题。

能管理已经存在的资源吗?

可以,通过 CloudFormation 的资源导入把存量资源纳入栈,但要求资源属性与模板一致,否则导入会失败。

用了 CDK 还能用 SAM CLI 调试 Lambda 吗?

可以。把 cdk synth 生成的模板交给 SAM CLI 做本地调用测试,但本地模拟不能完全替代真实环境验证。

部署到多个账号需要额外做什么?

每个账号与区域都要单独 bootstrap,并在 bootstrap 时配置好信任关系,让部署角色可以跨账号 assume。