はじめに
私が初めて、bootstrapと出会ったのはAWS勉強会でGenUのハンズオンに参加した時のことでした。
AWS素人の私は、言われるがまま手順通りに構築を行い、見事にbootstrapの実行でエラーになりました。
講師にヘルプを求めると、以前も同じ手順と環境でハンズオンを実施したため、その環境が残存しているのが問題だと説明してくれました。
しかし、次々に周りの人も同じ事象に陥り、bootstrapのエラー復旧で大半の時間を費やし、その後に新しい問題も発生し、講師側も問題を解決できず、全員が環境構築段階でタイムオーバーを迎えました。
それ以降、bootstrapは複雑かつ面倒なものだと勝手に解釈し、bootstrapが何かも知らないまま使い続けているのですが、いつかは「ボーっと生きてんじゃねーよ！」と言われかねないので、改めてChatGPTで問題解決を図ることにしました。
bootstrapとは
AWS CDK の bootstrap とは、CDK アプリケーションをデプロイするために AWS アカウント側に必要なインフラ（初期資源）を事前に準備する作業です。
具体的に bootstrap が作成するもの
主に以下のリソースを、指定されたアカウント・リージョンに構築します。
| リソース | 詳細 |
|---|---|
| S3 バケット（CDKToolkit） | デプロイ時に使用するアセット（Lambdaのコード、コンテナイメージ、CloudFormationテンプレートなど）を格納します。 |
| ECR リポジトリ（必要時） | コンテナイメージアセットをデプロイするために使用されます。 |
| IAM ロール | CDK が CloudFormation スタックのデプロイ時に利用する権限ロール。(cfn-execution-role, deploy-role, lookup-roleなど) |
| その他 | CDK バージョンに応じた管理リソース |
つまり bootstrap は、CDK が安全かつ自動的にデプロイできるための土台（ツールキット）を AWS 側に作る作業です。
理解すべきポイント
bootstrap で作成したリソースはアカウント、及びリージョンに紐づけられる。
AWS CDK bootstrap の実際の時系列処理
CDK の bootstrap (cdk bootstrap) は、内部的には 1つの CloudFormation スタック（CDKToolkit）を作成する処理です。
したがって流れは次のようになります。
-
CDK が bootstrap 用テンプレートを生成する
CDK CLI は、内部の「bootstrap テンプレート」を使用して、CloudFormation 用のテンプレートを生成します。
含まれるもの（CDK v2 例）
・S3 バケット
・いくつかの IAM ロール
・必要に応じた ECR アセット設定など。 -
CloudFormation へテンプレートが送信され、スタック作成が開始される
CLI は生成したテンプレートを CloudFormation に送って、以下の名前でスタック作成を開始します。
・CDKToolkit -
CloudFormation がテンプレートの内容に基づきリソースを作成する（時系列）
CloudFormation がテンプレートを読み、依存関係に基づいて順序を自動決定し、以下の順で作成します。
(1) IAM ロールの作成
CloudFormation は最初にロールを作ることが多いです。
（後続の処理で権限が必要になるため）
(2) S3 バケットの作成
アセットのアップロード先として参照されるもの。
(3) 必要に応じて ECR リポジトリ（または関連パーミッション）の作成
Docker イメージを扱う場合に使用。
(4) Outputs の設定
作成したロールやバケットの ARN をスタックの Outputs に出力。 -
CloudFormation のスタック「CDKToolkit」が完成
この時点で bootstrap は完了し、CDK のデプロイ時に必要な「作業場」が整います。
初心者は繰り返し作業を行うことで知識と経験を得るもの。
次では、１回やったんだから２回目もできるだろと思って、見事にハマったことを説明します。
bootstrapは毎回実施する必要はない
２回目の環境構築時に、bootstrapを行うとエラーが発生し、すでに環境（IAMロール）が存在していると怒られて、bootstrapで作った環境は使いまわすものだと、この時に知りました。
bootstrap は 1 回実施すれば、なぜ次の構築では不要なのか
理由は、bootstrap が作成する S3 バケットや IAM ロールなどの 基盤リソースは、アカウント＋リージョン単位で共有されるためです。
理解すべきポイント
一度 bootstrap を実行すると、そのアカウント・リージョン内のすべての CDK プロジェクトが同じ bootstrap リソースを再利用できる。
つまり、次回別の CDK プロジェクトをデプロイするとき、すでに S3 バケットや IAM ロールが整っているため、再度 bootstrap する必要がない。
例えるなら、CDK 用の作業場（道具一式）を最初に作っておき、以降はその作業場を使い回すというイメージです。
bootstrap を再度実行するケース
通常は不要ですが、以下の場合には再実行します。
・CDK の major version アップデートで bootstrap テンプレートが変わった
・bootstrap リソース（S3 バケットや IAM ロール）を誤って削除した
・セキュリティ要件変更で新しいロール・ポリシーを生成したい
・--profile や --cloudformation-execution-policies など設定変更が必要なとき
まとめ
| 目的 | 内容 |
|---|---|
| bootstrap の役割 | CDK デプロイに必要な S3 バケット・IAM ロールなどの「土台」を AWS アカウントに作ること |
| 一度で良い理由 | これらの基盤リソースはアカウント＋リージョン単位で共有され、次以降の CDK プロジェクトが使い回せるため |
最後に
最後に bootstrap が実行されたかどうかを判断する術を記載しておきます。
1. 最も確実で実務的：cdk deploy のエラーで判定する
CDK が bootstrap されていないアカウント／リージョンに対して cdk deploy を実行すると、次のような典型的なエラーが発生します。
・S3 バケット（cdktoolkit-stagingbucket-）が見つからない
・IAM ロール（cdk-hnb659fds-deploy-role- など）が無い
・Bootstrap stack (CDKToolkit) が存在しない
CDK は必要な bootstrap リソースを自動検出するため、deploy のエラーは明確な “bootstrap 未実施” のサインです。
とはいえ、人間の心理としてエラー結果で判断するというのは、気持ちがいいものではありませんね。
2. CloudFormation に bootstrap stack (CDKToolkit) があるか確認する
bootstrap が正常に実行されていれば、CloudFormation に以下のスタックが存在します。
スタック名: CDKToolkit
CloudFormation コンソール、CLI のいずれでも確認できます。
確認コマンド (AWS CLI)
aws cloudformation describe-stacks --stack-name CDKToolkit
見つからなければ bootstrap されていません。
3. S3 バケットが存在するか確認する（補助的）
bootstrap によって作成される代表的なバケット：
cdktoolkit-stagingbucket-*
次のコマンドで確認できます。
確認コマンド
aws s3 ls | grep cdktoolkit
ただし、ユーザーが手動で削除したケースもありえるため、CloudFormation スタックの確認の方が正確です。
4. IAM ロールの確認（高度だが確度が高い）
bootstrap が成功していれば、以下の IAM ロールが存在します：
例：
cdk-hnb659fds-deploy-role--
cdk-hnb659fds-cfn-exec-role--
cdk-hnb659fds-file-publishing-role--
CLI 例：
aws iam list-roles | grep cdk-hnb659fds
ただし、細かなバージョン差異があるため CloudFormation を確認する方が簡便です。
5. CDK コマンドによる事前チェックは「ない」
現時点の AWS CDK には、"bootstrap が必要かを自動判定して教える専用コマンド" はありません。
CDK はデプロイ時に必要なリソースを見てエラーを出す方式のため、本番前チェックとしては次がベストプラクティスです：
cdk synth
cdk diff
cdk deploy (テスト用のサンドボックス環境で)
実務でのおすすめ確認フロー（効率的）
CloudFormation で CDKToolkit スタックが存在するか確認
→ 無ければ bootstrap 必要
存在していれば基本的に問題なし。
ただし、CDK の major version 更新後は以下を確認する：
・S3 バケット
・IAM ロール
・Bootstrap version (スタックの Outputs に記載)
不整合が気になる場合は安全に再 bootstrap しても良い：
cdk bootstrap
※ 再 bootstrap は既存リソースを置き換えるのではなく、基本的に上書き更新されるため安全性が高いです。
まとめ（最も合理的な方法）
| 方法 | 信頼度 | 説明 |
|---|---|---|
| CloudFormation に CDKToolkit があるか確認 | 最高 | 公式に bootstrap が作成するスタック |
| cdk deploy のエラー確認 | 高 | デプロイ時に自動検出できる |
| S3 バケット確認 | 中 | 手動削除の可能性あり |
| IAM ロール確認 | 中 | バージョン差異がある |
| CDK の専用判定コマンド | 無 | 提供されていない |
今回、調べてみて、過去の構築エラーの原因と対策内容が頭の中で繋がった気がします。