AWS CDK

Overview

CDK コンストラクト作成、デプロイメントワークフロー、コンプライアンス、ドリフト、リソースインポート、安全なリファクタリング、および CDK CLI / CloudFormation エラーのトラブルシューティングに関するドメイン専門知識です。

使用しない場合: 生の CloudFormation YAML/JSON。SAM。Terraform/Pulumi。CDK Pipelines 以外の CI/CD。これらについては組み込み知識または専門スキルを使用します。

重大な警告

デッドロック: クロススタック参照を削除するとデプロイメントがデッドロックします。2 段階のデプロイが必要です: (1) コンシューマー インポートを削除し、プロデューサーに this.exportValue() を追加してデプロイ、(2) exportValue() を削除してもう一度デプロイ。troubleshooting-deployment を参照してください。

構築 ID の変更は置換を引き起こします: コンストラクトの名前変更または移動は論理 ID を変更 → CloudFormation はリソースを置換します (ステートフルリソースはデータ損失)。常に deploy の前に cdk diff を実行してください。refactor-and-prevent-replacement を参照してください。

UPDATE_ROLLBACK_FAILED: スタックが停止しています。cdk rollback $STACK または cdk rollback $STACK --orphan <LogicalId> で修正します。troubleshooting-deployment を参照してください。

空でない S3 バケットは destroy 後も残ります: removalPolicy: DESTROY と autoDeleteObjects: true の両方を設定する必要があります。バージョン管理されたバケットはさらに悪く、表示上削除された後でも削除マーカーが残ります。

Common Workflows

タスク	クイックコマンド	詳細
ブートストラップ	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 — deps をピン留め、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 (対話型または CI 用の --resource-mapping)、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 が実行されていない、またはブートストラップバケットのパーミッションの問題。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	再度ブートストラップします。すべての場所で --qualifier を一致させます。詳細
DependencyCycle	共有リソースを 3 番目のスタックに抽出するか、遅延バインディング用に SSM を使用します。詳細
UnresolvedAccount	スタックに明示的な env: { account, region } を設定します。cdk.context.json をコミットします。詳細
NoStacksMatched	CDK は論理 ID (2 番目のコンストラクタ引数) を使用し、CFN 名ではありません。ID を見つけるには cdk list を実行します。詳細
Cannot find module (synth 時)	npx tsc --noEmit を実行し、cdk.json app パスが tsconfig.json の outDir と一致するか確認し、古い .js ファイルを削除します。Python: venv をアクティベートします。詳細
V1 インポートパス / 重複した aws-cdk-lib	V1 の @aws-cdk/* インポート、間違った Construct インポート、monorepos での重複ライブラリコピー。詳細
Lambda Cannot find module (ランタイム)	誤ったハンドラー値、不足した SDK v3 マイグレーション、Python deps がバンドルされていない。詳細
API Gateway マルチステージコンフリクト	RestApi で deploy: false を設定し、Deployment と Stage を明示的に作成します。詳細

Construct パターン

L2 を推奨します。L2 にプロパティが不足している場合は、Mixins/Facades で L1 を使用します。エスケープハッチ: node.defaultChild → addPropertyOverride。construct-patterns を参照してください。

追加リソース

• AWS ドキュメント「CDK Developer Guide」、「CDK API Reference」、および「CDK Pipelines」をそれぞれ検索してください

セキュリティに関する考慮事項

• CI/CD 認証情報用の OIDC (静的キーなし)
• ブートストラップ時の --custom-permissions-boundary
• リソース間 IAM 用の grant*()
• CI での cdk-nag + --strict
• terminationProtection: true を設定した独自スタック内のステートフルリソース
• cdk.context.json をコミット