mastering-aws-cdk

用途

Mastering AWS CDK 是一个专注于 AWS CDK v2（TypeScript）基础设施即代码开发的指导技能，帮助开发者构建、部署和排查 AWS 云基础设施。它围绕 CDK 应用与堆栈的完整生命周期提供结构化的工作流程、服务模式、故障排查方法以及 CI/CD 与可观测性参考。

主要能力

该技能覆盖以下方面：

在 TypeScript 中构建新的 CDK 应用或堆栈。
重构或拆分堆栈以管理资源数量限制。
调试 synth、diff、deploy 失败以及 CloudFormation 回滚。
将现有资源导入 CDK 管理。
通过 JSON/YAML 配置文件驱动堆栈。
设置 GitHub Actions OIDC 部署。
在 AWS 托管服务上实现服务模式。
编写 CDK 测试并运行安全检查。

触发该技能的关键词包括：cdk、cdk deploy、cdk diff、cdk synth、cdk import、cdk watch、cdk refactor、cdk bootstrap、cdk-nag、hotswap、CloudFormation、stack rollback、cdk.context.json、cdk.json、SSM Parameter Store、hnb659fds、OIDC GitHub Actions 等。

使用方式

快速开始步骤：

确认目标账户、区域和环境（dev/stage/prod）。
运行 cdk synth 然后 cdk diff 验证变更。
在 CI 中使用 cdk deploy --require-approval=never 部署。

工作流程分为六个阶段：

信息收集：收集账户与区域、环境名称与阶段、目标服务与集成、需要导入或避免替换的现有资源。
堆栈设计：保持堆栈资源数低于 500（超出则拆分或使用嵌套堆栈）；通过 props 或显式导出传递输出；为有状态资源设置移除策略（默认保留）。
实现：优先使用 L2 构造，仅在存在缺口时使用 L1；应用最小权限 IAM 授权；保持资源名称确定性。
验证：使用 cdk synth 检查模板，cdk diff 审查变更，cdk doctor 检查环境问题。
部署：确保账户/区域已完成 bootstrap；失败时查看 CloudFormation 事件；仅在 CI 中使用 --require-approval=never。
可观测性：尽早添加日志保留、告警和仪表板；在需要分布式追踪时使用 X-Ray。

参考文件

技能包含以下参考文件，按任务组织：

references/troubleshooting.md：错误消息与修复。
references/cicd-github.md：GitHub Actions OIDC 设置。
references/services.md：Lambda、ECS、MSK、DynamoDB、Aurora、S3、EventBridge 模式。
references/observability.md：CloudWatch、X-Ray、仪表板、告警。
references/architecture-ops.md：确定性、配置驱动模式、导入、漂移与运维工作流。
references/testing-security.md：CDK 测试、cdk-nag 与合规检查。
references/latest-features.md：新构造、CLI 能力与近期模式。

适用场景

该技能适用于以下情况：在 TypeScript 中构建新的 CDK 应用或堆栈；重构或拆分堆栈以管理限制；调试 synth/diff/deploy 失败或 CloudFormation 回滚；将现有资源导入 CDK 管理；通过 JSON/YAML 配置文件驱动堆栈；设置 GitHub Actions OIDC 部署；在 AWS 托管服务上实现服务模式；编写 CDK 测试并运行安全检查。

限制与约束

该技能仅支持 TypeScript 版 CDK，不适用于以下情况：

Terraform、Pulumi 或原生 CloudFormation 模板。
手动控制台驱动的资源管理。
Python、Java、Go、C# 版 CDK。

此外，技能包含以下护栏规则：

不要在控制台中修改由 CloudFormation 管理的资源。
避免在资源定义中使用动态值（如 Date.now、random）。
使用 env: { account, region } 进行查找（VPC/AZ/AMI）。
从配置数据生成构造时使用稳定 ID。
对现有资源使用 cdk import（收养）；fromXxx 仅用于只读引用。
不要在生产流水线中使用 hotswap。

调试检查清单包括：检查 CloudFormation 事件（控制台 -> 堆栈 -> 事件）；使用详细输出重新运行 cdk deploy --progress events；检查模板 cdk synth > template.yaml；运行 cdk diff；检查服务日志（Lambda：CloudWatch，ECS：任务事件）；运行 cdk doctor。