🏗️aws-cdk
- プラグイン
- aws-core
- ソース
- GitHub で見る ↗
説明
AWS CDKを使用して、TypeScriptまたはPythonでAWSインフラの作成・デプロイ・トラブルシューティングを行います。 ベストプラクティス、スタックアーキテクチャ、コンストラクトパターンを網羅しています。 次のような場合に使用: CDKコンストラクトの記述、環境のブートストラップ、`cdk deploy` / `cdk synth` / `cdk diff` の実行、CDKまたはCloudFormationエラーの修正、スタック構成の設計、既存リソースのインポート、ドリフトの解消、リソースを置き換えずにスタックをリファクタリングする場合。
原文を表示
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Always use when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
ユースケース
- ✓CDKコンストラクトを記述するとき
- ✓環境のブートストラップが必要なとき
- ✓CDKコマンドを実行するとき
- ✓AWSエラーを修正するとき
- ✓スタックをリファクタリングするとき
本文（日本語訳）
AWS CDK
概要
CDK Constructの作成、デプロイワークフロー、コンプライアンス、ドリフト検出、リソースのインポート、安全なリファクタリング、CDK CLI / CloudFormationエラーのトラブルシューティングに関するドメイン専門知識。
使用しない場面: 生のCloudFormation YAML/JSON、SAM、Terraform/Pulumi、CDK Pipelines以外のCI/CD。これらにはビルトインナレッジまたは専用スキルを使用すること。
重大な警告
デッドロック（deadly embrace）: クロススタック参照を削除するとデプロイがデッドロックする。2回のデプロイによる修正が必要:
- コンシューマー側のimportを削除し、プロデューサー側に
this.exportValue()を追加してデプロイ exportValue()を削除して再デプロイ
詳細: troubleshooting-deployment
Construct IDの変更はリソース置き換えを引き起こす:
Constructのリネームや移動は論理IDの変更につながり、CloudFormationがリソースを置き換える（ステートフルなリソースではデータ損失の危険あり）。
デプロイ前に必ず cdk diff を実行すること。
詳細: refactor-and-prevent-replacement
UPDATE_ROLLBACK_FAILED:
スタックがスタック（stuck）状態になる。cdk rollback $STACK または cdk rollback $STACK --orphan <LogicalId> で修復する。
詳細: troubleshooting-deployment
空でないS3バケットはdestroy後も残存する:
removalPolicy: DESTROY と autoDeleteObjects: true の両方を必ず設定すること。
バージョニングが有効なバケットはさらに厄介で、見かけ上削除されても削除マーカーが残り続ける。
よく使うワークフロー
| タスク | クイックコマンド | 詳細 |
|---|---|---|
| Bootstrap | cdk bootstrap aws://$ACCOUNT/$REGION |
bootstrap-and-project-setup |
| TSプロジェクト新規作成 | cdk init app --language typescript — tsx、eslint-plugin-awscdk を使用 |
bootstrap-and-project-setup |
| Pythonプロジェクト新規作成 | cdk init app --language python — 依存関係をピン留めし、virtualenvを使用 |
bootstrap-and-project-setup |
| デプロイ | cdk synth --strict → cdk diff → cdk deploy |
本番環境へのデプロイ前は必ずdiffを確認 |
| cdk-nag | Aspects.of(app).add(new AwsSolutionsChecks()) |
compliance-and-drift |
| ドリフト検出 | cdk drift $STACK（CIでは --fail を使用） |
compliance-and-drift |
| リソースのインポート | cdk import（対話式）または --resource-mapping（CI向け）、cdk deploy --import-existing-resources |
import-and-migrate |
| 安全なリファクタリング | cdk refactor --unstable=refactor — 同一デプロイ内でプロパティ変更を行わないこと |
refactor-and-prevent-replacement |
トラブルシューティング
| エラー | 原因 → 対処法 |
|---|---|
| DeployFailed / DeploymentError | CDKのエラーメッセージは根本原因ではない。CFNイベントを確認: aws cloudformation describe-stack-events --stack-name $STACK --query "StackEvents[?contains(ResourceStatus,'FAILED')]" 詳細 |
| NoCredentials / ExpiredToken / AssumeRoleFailed | aws sts get-caller-identity + cdk doctor を実行。SSOの期限切れ、env 未設定、sts:AssumeRole 権限の欠如が原因。詳細 |
| アセットエラー (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed) | パスの誤り、Dockerが未起動、またはbootstrapバケットの権限不足。path.join(__dirname, ...) を使用すること。詳細 |
| AppRequired | cdk.json に "app": "npx tsx bin/my-app.ts" を追加する。詳細 |
| AnnotationErrors | 根本的な問題を修正すること。NagSuppressions による抑制は最終手段としてのみ使用。詳細 |
| ConcurrentReadLock / ConcurrentWriteLock | rm -rf cdk.out 後に再実行。並列CIの場合: --output ./cdk.out.$BUILD_ID を指定。詳細 |
| BootstrapVersionValidation | 再bootstrapを実行。--qualifier をすべての箇所で一致させること。詳細 |
| DependencyCycle | 共有リソースを第3のスタックに切り出すか、遅延バインディングにSSMを使用する。詳細 |
| UnresolvedAccount | スタックに env: { account, region } を明示的に設定する。cdk.context.json をコミットすること。詳細 |
| NoStacksMatched | CDKはCFN名ではなく論理ID（コンストラクタの第2引数）を使用する。cdk list でIDを確認すること。詳細 |
| Cannot find module（synth時） | npx tsc --noEmit を実行し、cdk.json のappパスと tsconfig.json の outDir が一致しているか確認。古い .js ファイルを削除する。Python: venvを有効化すること。詳細 |
| V1のimportパス / aws-cdk-libの重複 | V1形式の @aws-cdk/* import、誤った Construct のimport、モノレポ内でのライブラリ重複が原因。詳細 |
| Lambda Cannot find module（実行時） | handlerの値が誤っている、SDK v3への移行漏れ、Pythonの依存パッケージが未バンドルなどが原因。詳細 |
| API Gatewayマルチステージの競合 | RestApi に deploy: false を設定し、Deployment と Stage を明示的に作成する。詳細 |
Constructのパターン
L2 Constructを優先すること。L2が特定のプロパティをサポートしていない場合はMixin/FacadeパターンでL1を使用する。
エスケープハッチ: node.defaultChild → addPropertyOverride
詳細: construct-patterns
追加リソース
- AWSドキュメントで「CDK Developer Guide」「CDK API Reference」「CDK Pipelines」をそれぞれ検索すること
セキュリティに関する考慮事項
- CI/CDの認証情報にはOIDCを使用（静的キーは不可）
- bootstrapに
--custom-permissions-boundaryを指定 - リソース間のIAM権限には
grant*()メソッドを使用 - CIでは
cdk-nag+--strictを有効化 - ステートフルなリソースは独立したスタックに配置し、
terminationProtection: trueを設定 cdk.context.jsonをコミットすること
原文（English）を表示
AWS CDK
Overview
Domain expertise for CDK construct authoring, deployment workflows, compliance, drift, importing resources, safe refactoring, and troubleshooting CDK CLI / CloudFormation errors.
When NOT to use: Raw CloudFormation YAML/JSON. SAM. Terraform/Pulumi. CI/CD beyond CDK Pipelines. Use builtin knowledge or specialized skills for these.
Critical Warnings
Deadly embrace: Removing a cross-stack reference deadlocks deployment. Two-deploy fix required: (1) remove consumer import + add this.exportValue() on producer, deploy; (2) remove exportValue(), deploy again. See troubleshooting-deployment.
Construct ID changes cause replacement: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always cdk diff before deploy. See refactor-and-prevent-replacement.
UPDATE_ROLLBACK_FAILED: Stack is stuck. Fix with cdk rollback $STACK or cdk rollback $STACK --orphan <LogicalId>. See troubleshooting-deployment.
Non-empty S3 buckets persist after destroy: You MUST set both removalPolicy: DESTROY and autoDeleteObjects: true. Versioned buckets are worse — delete markers persist even after apparent deletion.
Common Workflows
| Task | Quick Command | Details |
|---|---|---|
| Bootstrap | cdk bootstrap aws://$ACCOUNT/$REGION |
bootstrap-and-project-setup |
| New TS project | cdk init app --language typescript — use tsx, eslint-plugin-awscdk |
bootstrap-and-project-setup |
| New Python project | cdk init app --language python — pin deps, use virtualenv |
bootstrap-and-project-setup |
| Deploy | cdk synth --strict → cdk diff → cdk deploy |
Always diff before deploy to prod |
| cdk-nag | Aspects.of(app).add(new AwsSolutionsChecks()) |
compliance-and-drift |
| Drift | cdk drift $STACK (use --fail in CI) |
compliance-and-drift |
| Import resource | cdk import (interactive or --resource-mapping for CI), cdk deploy --import-existing-resources |
import-and-migrate |
| Refactor safely | cdk refactor --unstable=refactor — no property changes in same deploy |
refactor-and-prevent-replacement |
Troubleshooting
| Error | Cause → Fix |
|---|---|
| DeployFailed / DeploymentError | CDK error is not root cause. Check CFN events: aws cloudformation describe-stack-events --stack-name $STACK --query "StackEvents[?contains(ResourceStatus,'FAILED')]". Details |
| NoCredentials / ExpiredToken / AssumeRoleFailed | aws sts get-caller-identity + cdk doctor. Expired SSO, missing env, missing sts:AssumeRole. Details |
| Asset errors (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed) | Path wrong, Docker not running, or bootstrap bucket perms. Use path.join(__dirname, ...). Details |
| AppRequired | Add "app": "npx tsx bin/my-app.ts" to cdk.json. Details |
| AnnotationErrors | Fix the underlying issue; suppress with NagSuppressions only as last resort. Details |
| ConcurrentReadLock / ConcurrentWriteLock | rm -rf cdk.out then re-run. Parallel CI: --output ./cdk.out.$BUILD_ID. Details |
| BootstrapVersionValidation | Re-bootstrap. Match --qualifier everywhere. Details |
| DependencyCycle | Extract shared resource into third stack or use SSM for late-binding. Details |
| UnresolvedAccount | Set explicit env: { account, region } on stack. Commit cdk.context.json. Details |
| NoStacksMatched | CDK uses logical ID (2nd constructor arg), not CFN name. cdk list to find IDs. Details |
| Cannot find module (synth time) | Run npx tsc --noEmit, check cdk.json app path matches tsconfig.json outDir, delete stale .js files. Python: activate venv. Details |
| V1 import paths / duplicate aws-cdk-lib | V1 @aws-cdk/* imports, wrong Construct import, duplicate lib copies in monorepos. Details |
| Lambda Cannot find module (runtime) | Wrong handler value, missing SDK v3 migration, Python deps not bundled. Details |
| API Gateway multi-stage conflicts | Set deploy: false on RestApi, create Deployment and Stage explicitly. Details |
Construct Patterns
Prefer L2. Use L1 with Mixins/Facades when L2 lacks a property. Escape hatches: node.defaultChild → addPropertyOverride. See construct-patterns.
Additional Resources
- Search AWS documentation for "CDK Developer Guide", "CDK API Reference" and "CDK Pipelines" respectively
Security Considerations
- OIDC for CI/CD credentials (no static keys)
--custom-permissions-boundaryon bootstrapgrant*()for inter-resource IAMcdk-nag+--strictin CI- Stateful resources in own stack with
terminationProtection: true - Commit
cdk.context.json
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。