aws-cdk

AWS CDK

概要

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

使用しない場合： 生の CloudFormation YAML／JSON、SAM、Terraform／Pulumi、CDK Pipelines の範囲外の CI/CD。これらには組み込みの知識または専門スキルを使用してください。

重要な警告

デッドリーロック：スタック間参照を削除すると、デプロイがデッドロックします（Export ... cannot be deleted as it is in use by ...）。推奨される修正方法は、まず参照を弱めることです。CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH)、次にWEAKを指定してから削除します（デプロイを3回行います）。従来の代替策は、this.exportValue()を使う2回のデプロイの手順です。troubleshooting-deploymentを参照してください。

コンストラクト ID を変更すると置き換えが発生します：コンストラクトの名前変更や移動によって論理 ID が変わり、CloudFormation がリソースを置き換えます（ステートフルなリソースではデータが失われます）。デプロイ前に必ずcdk diffを実行してください。refactor-and-prevent-replacementを参照してください。

UPDATE_ROLLBACK_FAILED：スタックが停止しています。cdk rollback $STACKまたはcdk rollback $STACK --orphan <LogicalId>で修正してください。ただし、Express モードのスタックは例外で、ロールバックできません。troubleshooting-deploymentを参照してください。

ホットスワップと Express モードは開発専用です：--hotswap／--hotswap-fallbackは CloudFormation を迂回し、意図的にドリフトを発生させます。--expressはリソースが安定する前に成功を報告し、自動ロールバックを無効にします。本番環境ではどちらも絶対に使用しないでください。--expressによるデプロイが失敗した場合、ロールバックはできません。別の--expressデプロイで前進させて復旧してください。fast-deploymentsを参照してください。

空でない S3 バケットは破棄後も残ります：removalPolicy: DESTROYとautoDeleteObjects: trueの両方を必ず設定してください。バージョニングが有効なバケットはさらに厄介で、削除されたように見えても削除マーカーが残ります。

よくあるワークフロー

タスク	クイックコマンド	詳細
ブートストラップ	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 deploy --hotswap-fallback、cdk watch、またはcdk deploy --express — 開発専用。本番環境では使用禁止	fast-deployments
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

高速デプロイ — Hotswap と Express（開発専用）

どちらも安全性を犠牲にして速度を優先するため、本番環境ではどちらも使用しないでください。

選び方： 主に Hotswap 対応リソースを扱い、ドリフトが問題にならない場合は、最速の反復のために --hotswap / --hotswap-fallback を使用してください。ドリフトを許容できない場合、またはリソースが Hotswap に対応していない場合は、--express を使用してください。

復旧ワークフロー（--revert-drift による Hotswap のドリフト解消、失敗した --express デプロイのロールフォワード）、Hotswap 対応リソースのルール、本番環境での使用禁止を徹底する IAM／監視については、完全版ガイド fast-deployments をご覧ください。

トラブルシューティング

エラー	原因 → 対処
DeployFailed / DeploymentError	CDK エラーは根本原因ではありません。cdk deploy $STACK --verbose を実行し、その後 cdk --unstable=diagnose diagnose $STACK を実行します（CLI ≥ 2.1120.0）。それ以外の場合は aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true を実行します。最初の _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	共有リソースを別のスタックに切り出すか、遅延バインディングに 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 のインポートパス / aws-cdk-lib の重複	V1 の @aws-cdk/* インポート、誤った Construct のインポート、またはモノレポ内でのライブラリの重複コピーが原因です。詳細
Lambda Cannot find module（実行時）	ハンドラーの値の誤り、AWS SDK v3 への移行漏れ、または Python の依存関係がバンドルされていないことが原因です。詳細
API Gateway の複数ステージの競合	RestApi に deploy: false を設定し、Deployment と Stage を明示的に作成してください。詳細
--hotswap で変更がデプロイされない	ホットスワップに対応していないリソースへの変更は、警告なしに無視され、ログにのみ記録されます。コマンドは成功を報告します。出力を確認してください。代わりに --hotswap-fallback を使用すると、CloudFormation によるデプロイが強制されます。詳細
--express のデプロイ失敗 / ロールバックできない	Express モードでは Rollback Stack API を使用できず、標準のデプロイを復旧に使用してはなりません。ロールフォワードするには、原因を修正してから cdk deploy $STACK --express を実行してください。詳細
開発スタックで予期しないドリフトが発生する	ホットスワップと cdk watch は、仕様上ドリフトを発生させます。元に戻すまでは、CloudFormation の記録ではなく、稼働中のリソースが正しい状態を示します。cdk deploy $STACK --revert-drift で整合性を取り戻してください。このコマンドは Drift Aware Changesets を使用して、稼働中のリソースをテンプレートに合わせます（望ましい状態に現状を合わせます。ドリフトしたリソースに合わせて CF の記録を書き換えることはありません）。詳細

コンストラクトのパターン

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 をコミットします