cdk bootstrapが作る5つのIAMロールとテンプレート版32の更新手順

「SSM parameter /cdk-bootstrap/hnb659fds/version not found」で配備が止まったなら、原因はアプリ側ではなく環境側の準備にあります。cdk bootstrapは、対象のアカウントとリージョンにCDKToolkitという名前のCloudFormationスタックを配備し、資産置き場のS3バケットとECRリポジトリ、デプロイ中に引き受けられる5つのIAMロールを用意するコマンドです。このテンプレートは版番号で管理され、2026年9月15日時点の既定は版32でした。作られる資源の内訳、修飾子hnb659fdsの意味、権限を絞る設計、失敗したスタックを立て直す手順までを、公式ドキュメントとテンプレート本体の実値に当たって整理します。

まとめ｜版番号の確認方法と権限を絞り込むブートストラップ運用の要点

ブートストラップは「一度通れば終わり」の作業ではありません。CDK CLIの更新に追随して版を上げ続ける運用対象です。手元の環境がどの版かは、スタック名を知らなくてもSSMパラメータ1本で判定できます。ここを見ていない現場ほど、CLIを上げた日に原因不明のデプロイ失敗を出しがちです。

権限は、既定例のarn:aws:iam::aws:policy/AdministratorAccessをそのまま本番へ持ち込まない設計を推奨します。実行ポリシーは絞れますが、絞りすぎるとリソース追加のたびに配備が落ちる副作用とセットです。配備対象のサービス群に合わせて明示し、アクセス許可境界で上限を固定する二段構えが扱いやすい構成になります。なお、失敗したCDKToolkitスタックを消して作り直す対処は公式が明確に否定しています。削除ではなく再実行で更新してください。

cdk bootstrapがCDKToolkitスタックとして作る資源とロールの内訳

コマンドが何を作るのかを先に押さえます。抽象的な「デプロイの準備」ではなく、CloudFormationスタック1本として実体があるものです。

CDKToolkitスタックが作るS3バケットとECRリポジトリの命名規則

cdk bootstrapは、指定した環境（アカウントとリージョンの組）にCDKToolkitという名前のCloudFormationスタックを配備します。AWS公式のブートストラップ解説によれば、用意されるのは資産を置くS3バケット、イメージを置くECRリポジトリ、配備時に使うIAMロール群の3種です。

物理IDには規則があります。cdk-（修飾子）-（用途）-（アカウントID）-（リージョン）という構造で、公式の環境ブートストラップ解説にはcdk-hnb659fds-assets-012345678910-us-west-1という実例が載っています。バケット名がこの形なら既定テンプレート由来。違っていれば--bootstrap-bucket-nameなどで上書きされていると判断できます。命名だけで素性が分かるため、複数プロジェクトが同居するアカウントの棚卸しでは最初の手がかりになります。

デプロイ中に引き受けられる5つのIAMロールと役割ごとの権限範囲

既定テンプレートが作るIAMロールは5つです。CDK CLIが直接引き受けるものと、CloudFormationがサービスロールとして引き受けるものが混在しています。表では末尾のRoleを省いて示します。

設計上の要点は、実際にリソースを作る権限がCloudFormationExecutionRoleに集約されている点です。手元の認証情報が持つ権限ではなく、このサービスロールの権限が配備の上限を決めます。裏を返せば、開発者個人に強い権限を配らなくても配備は成立する構造です。LookupRoleだけは読み取り専用で、合成時に環境から値を引くときに使われます。

SSMパラメータに記録される版番号とスタック名に依存しない確認方法

テンプレートは版番号で管理され、その値はSSM Parameter Storeに書かれます。パラメータ名は/cdk-bootstrap/（修飾子）/versionです。スタック名が既定から変えられていても、修飾子さえ分かれば版を特定できます。

aws ssm get-parameter \
  --name /cdk-bootstrap/hnb659fds/version \
  --query Parameter.Value --output text

返る値が現在の版です。CDK CLIのリポジトリにあるbootstrap-template.yamlを2026年9月15日に確認したところ、CdkBootstrapVersionのValueは32でした。同日のnpm上のlatestはCLI（aws-cdk）が2.1141.0、ライブラリ（aws-cdk-lib）が2.269.0。番号体系が離れているのはCLIが別リポジトリへ分離され独自に版を刻むためで、不具合ではありません。

修飾子hnb659fdsが決める物理IDと複数環境を分ける指定

修飾子（qualifier）は、同じ環境に複数のブートストラップスタックを共存させる識別子です。既定値はhnb659fdsという9文字で、公式は「この値自体に意味はない」と明記しています。

修飾子を変えると、バケット名もロール名もパラメータ名もすべて別系統になります。--qualifier dev2024のように指定すれば独立した準備環境を並べられますが、アプリ側の合成設定と揃っていないと配備時に参照先を見失う点に注意してください。共用アカウントを部署ごとに切り分けるなど明確な理由があるときだけ変更し、それ以外は既定のままにしておくほうが事故は減ります。変更の影響範囲はブートストラップのカスタマイズ手順に整理されています。

テンプレート版32までの変更履歴と再ブートストラップが必要になる条件

どの版で何が変わったかを知っておくと、古い環境で起きる症状を推測できます。

版1から版32までに起きた権限の追加とKMSキー既定値の反転

公式の版番号履歴には、版1（CDK 1.40.0）から版32（CDK CLI 2.1120.0）までの変更が並んでいます。実務に効く分岐は3つ。版4でCdkBootstrapVersionのSSMパラメータが入り、スタック名を知らずに版を確認できるようになりました。版6でLookupRoleがデプロイ用ロールから分離。版24と版25（いずれも2.165.0）では、資産バケットの非現行オブジェクト保持が365日から30日へ短縮され、未完了のマルチパートアップロードが1日で削除されるようになりました。

直近の変更は権限の締め直しが中心です。版28（2.1015.0）でスタックリファクタリング用の権限とTagSessionが追加され、版29（2.1026.0）ではExternalIdを伴うAssumeRoleが既定で拒否されるようになりました。版31（2.1116.0）でcloudformation:GetHookResultが加わり、版32（2.1120.0）では個別に並んでいた権限文がAWSCloudFormationReadOnlyAccessマネージドポリシーへ置換。KMSキーの扱いも途中で反転しています。古いテンプレートは環境ごとにKMSキーを作っていましたが、現在の既定はキーを作りません。課金を止めたい場合は--no-bootstrap-customer-keyを付けて再実行します。

古い版のまま運用したときに現れる失敗と再ブートストラップの判断基準

版が古いこと自体は、すぐには表面化しません。問題が出るのは、CDK CLIを新しくした側とブートストラップ済みの環境がずれたときです。CDKアプリは必要な最小版を宣言できるので、満たさない環境へ配備しようとすると合成または配備の段階で弾かれます。

判断基準はシンプルです。CLIを更新したら対象環境の版をSSMパラメータで確認し、テンプレート側の現行値より古ければcdk bootstrapを再実行します。ExternalIdの既定拒否が入った版29のような変更は、外部サービスからロールを引き受ける構成で挙動が変わるため、更新前にAssumeRole経路を洗い出してください。停止時間を伴う作業ではありませんが、CI側のロール設定を同時に見直す必要が出ることがあります。

AdministratorAccessを避ける実行ポリシーと信頼アカウントの指定

公式の例示がAdministratorAccessであるため、そのまま本番へ持ち込まれた環境をよく見かけます。絞る方法と、絞った結果どこが壊れるかを整理します。

実行ポリシーをAdministratorAccessから絞るときの副作用と手順

cdk bootstrapのコマンドリファレンスには、--cloudformation-execution-policiesに複数のマネージドポリシーARNをカンマ区切りで渡す例が載っています。ここで渡したポリシーがCloudFormationExecutionRoleに付き、配備できるリソースの範囲を決めます。

# 単一アカウント・単一リージョンの準備
npx cdk bootstrap aws://123456789012/ap-northeast-1

# CI用アカウントからのクロスアカウント配備を許可する
npx cdk bootstrap aws://123456789012/ap-northeast-1 \
  --trust 234567890123 \
  --trust-for-lookup 234567890123 \
  --cloudformation-execution-policies arn:aws:iam::aws:policy/AmazonS3FullAccess,arn:aws:iam::aws:policy/AWSLambda_FullAccess

副作用を先に書きます。絞った実行ポリシーは、アプリが新しい種類のリソースを足すたびに不足します。LambdaとS3だけを許可した状態でDynamoDBのテーブルを追加すると、配備はAccessDeniedで失敗。権限が足りないのはCloudFormationであって開発者の認証情報ではないため、手元の権限を強くしても解決しません。ブートストラップをやり直して実行ポリシーを足す作業になります。構成変更が頻繁なフェーズでは、絞り込みの運用コストが安全性の利得を上回りがちです。開発環境は広めに、本番は配備対象サービスを列挙して固定する使い分けを推奨します。

信頼アカウントの指定でクロスアカウント配備を成立させる2つの条件

--trustは、配備を実行させたい別アカウントのIDを指定するオプションです。CI用アカウントから本番アカウントへ配備する構成では、本番側をブートストラップするときにCI側のアカウントIDを信頼させます。読み取り専用の参照だけを許すなら--trust-for-lookupを併用してください。

成立条件は2つ。1つは信頼される側のロールが実際に存在していること、もう1つは引き受ける側のプリンシパルにsts:AssumeRoleが許可されていることです。公式のトラブルシューティングには「Policy contains a statement with one or more invalid principals」というエラーが挙げられており、これは相手側の環境がまだブートストラップされていないときに出ます。文面がIAMポリシーの構文を疑わせる書き方のため、原因の切り分けで遠回りしやすい箇所です。マルチアカウント構成の設計や既存環境の移管で判断に迷う場合は、AWSインフラ構築の支援で権限境界の設計から引き受けています。

アクセス許可境界を適用したときに詰まるロール生成とその回避策

組織のガードレールでアクセス許可境界が必須になっている環境では、--custom-permissions-boundaryで既存の境界ポリシー名を渡します。試験的に確認したいだけなら--example-permissions-boundaryで雛形を生成させる手もあります。

npx cdk bootstrap --custom-permissions-boundary cdk-exec-boundary

詰まりやすいのは、境界を強制するSCPがiam:CreateRoleに条件を付けている場合です。ブートストラップは5つのロールを作りますが、境界が付かないロールが混ざると条件に合致せず、作成そのものが拒否されます。回避策は--show-templateでテンプレートを書き出し、境界を全ロールへ付けた自前版を--templateで食わせる方法です。

npx cdk bootstrap --show-template > bootstrap-template.yaml
npx cdk bootstrap --template bootstrap-template.yaml

自前テンプレートに切り替えたら、版番号の追随は自分の責任です。公式も「独自テンプレートを提供するなら正準の既定テンプレートに追随させ続けること」と注記済み。差分を追えないなら、境界の要件をSCP側で緩める交渉のほうが結果的に安く付きます。

cdk init・synth・diff・deployがブートストラップ版に依存する箇所

どこで版番号が参照されるかを知っておくと、エラーの出どころを絞れます。

cdk initで作られる雛形とブートストラップ前に確認する設定

cdk initのリファレンスにあるとおり、initはテンプレートと言語を指定して雛形を作ります。この時点でAWSへの通信は発生せず、ブートストラップの有無も問われません。

確認しておきたいのはcdk.jsonに書かれる設定です。修飾子を既定から変えている組織では、ここに合成時の修飾子を書かないと、配備段階で存在しないロールを探しに行きます。雛形の構造やスタックの分け方はAWS CDKのスタック設計とデプロイ制御の記事で扱っているため、分割方針から決めたい場合はそちらへ。CDKの全体像やCloudFormation・Terraformとの違いはAWS CDKの仕組みと他ツールとの違いをまとめた記事が入口になります。

cdk synthとdiffが版番号を参照する箇所とデプロイ前の検証

cdk synthはアプリからCloudFormationテンプレートを生成するコマンドで、生成物にはブートストラップ版の最小要件がメタデータとして埋まります。環境から値を引く処理を含む場合はLookupRoleを使うため、未ブートストラップの環境では合成の段階で失敗します。

cdk diffは配備済みスタックと合成結果の差分を出します。CIに組み込むなら、差分が出たときに人の承認を挟む構成が扱いやすい形です。cdk deployは内部で変更セットを作って実行する流れで、この過程でDeploymentActionRoleが引き受けられます。版が古くてロールの権限が欠けているとここで止まり、エラーはCloudFormation側の文言で返るため、CDKの問題だと気づきにくい箇所です。

ブートストラップが失敗したときの原因切り分けと復旧の実務手順

失敗の型は限られており、対処の可否も明確に分かれます。

ブートストラップ未実施を示すエラー文言から原因を切り分ける順序

最も多いのは次の文言です。公式ドキュメントにも実例として載っています。

Deployment failed: Error: BootstrapExampleStack:
SSM parameter /cdk-bootstrap/hnb659fds/version not found.
Has the environment been bootstrapped?

切り分けは3段階です。第1に、対象アカウントとリージョンでブートストラップが実行されているか。東京で準備してバージニアへ配備しようとする取り違えは頻出します。第2に、修飾子が一致しているか。パラメータ名の中央部分が既定のhnb659fdsでなければ、アプリ側の設定と揃っていません。第3に、SSMパラメータを読む権限が実行者にあるか。存在するのに読めないだけ、という状態でも同じ文言が出ます。

スタックを削除して作り直す対処が事故になる理由と正しい復旧手順

CDKToolkitスタックがUPDATE_ROLLBACK_FAILEDなどで固まったとき、消して作り直したくなります。これは避けてください。公式は「環境をブートストラップした後は、ブートストラップスタックを削除して作り直さないこと。代わりにcdk bootstrapを再実行して新しい版へ更新すること」と明記しています。

理由は資産バケットにあります。配備済みスタックが参照するLambdaのコード資産やコンテナイメージは、このバケットとECRリポジトリに置かれたものです。スタックを削除するとこれらが失われ、既存スタックの更新やロールバックが資産を見つけられずに失敗します。バケットが残っていても、再作成時に別名になれば参照は切れます。正しい復旧はCloudFormationのコンソールで失敗要因を解消し、cdk bootstrapを再実行する手順です。削除が許されるのは、その環境にCDK配備済みスタックが1つも無い場合に限られます。

cdk gcで消せる資産と消せない資産｜バケット肥大化の抑え方

ブートストラップ用バケットは放置すると増え続けます。対処コマンドには前提条件がつきます。

cdk gcが試験段階である前提と実行時に必要になる明示指定

cdk gcのリファレンスには、このコマンドが開発途上であると明記されています。現在の機能は本番で使える品質としつつ、コマンドの範囲と機能は変更されうるため、利用者は--unstable=gcを渡して明示的に同意する必要があります。フラグを省くと実行できません。

npx cdk gc --unstable=gc --type=s3 \
  --rollback-buffer-days 30 \
  --created-buffer-days 10

自動化に組み込む前に知っておくべき制約です。オプション名や既定の挙動が将来変わりうると公式が宣言している以上、CIの定期ジョブへ無警戒に入れるとCLI更新時に落ちます。四半期ごとの棚卸しとして人が実行し、結果を確認する運用から始めるのが無難です。

保持日数の既定値30日とロールバックの余地を残す掃除の運用設計

削除の判断で効くのが2つのバッファ指定です。--rollback-buffer-daysは、未使用と判定してから実際に削除するまでの猶予日数。--created-buffer-daysは、作成から一定日数が経っていない資産を対象外にします。前者は「直前のバージョンへ戻せる余地」を、後者は「配備途中の資産を巻き込まない安全弁」を担います。

組み合わせる相手が、版24で入った保持日数の変更です。非現行オブジェクトの保持は365日から30日へ短縮されました。バケット側のライフサイクルが30日で片付ける設定である以上、gcのバッファをこれより長く取っても対象は先に消えます。ロールバック可能な期間を実質的に決めているのはライフサイクル設定だ、という理解で運用を組んでください。--actionにdelete-taggedを与えると、以前の実行でタグ付けされた資産だけを削除できます。タグ付けを先に行い、影響を確認してから削除へ進む二段運用が安全です。

よくある質問

ブートストラップの運用で問い合わせの多い点を5つ挙げます。

ブートストラップのテンプレート版はどこで確認できますか？

対象環境の版はSSM Parameter Storeの/cdk-bootstrap/（修飾子）/versionに入っています。修飾子が既定ならhnb659fdsです。CLIが配布する最新版は、CDK CLIリポジトリのbootstrap-template.yamlにあるCdkBootstrapVersionのValueで確認でき、2026年9月15日時点では32でした。両者を突き合わせ、環境側が古ければ再実行します。

既存のCDKToolkitスタックを削除して作り直しても問題ありませんか？

そのアカウントとリージョンにCDKで配備したスタックが1つでも残っているなら、削除しないでください。資産バケットとECRリポジトリのコード資産やイメージが失われ、既存スタックの更新とロールバックができなくなります。公式も削除ではなくcdk bootstrapの再実行による更新を指示しています。抜けられないときはCloudFormation側で失敗要因を解消してから再実行してください。

AdministratorAccessを付与せずにブートストラップできますか？

できます。CloudFormationに渡す実行ポリシーは--cloudformation-execution-policiesで任意のマネージドポリシーへ差し替えられます。ただし実行者自身には、公式が示す最小権限としてcloudformation・ecr・ssm・s3・iamの各操作が必要です。絞った場合はアプリが新種のリソースを追加するたびに配備が失敗するため、対象サービスを列挙できる本番環境から適用するのが現実的な順序になります。

修飾子を変更すると既存の環境はどうなりますか？

修飾子を変えると、バケット名・ロール名・SSMパラメータ名がすべて別系統になり、新しいブートストラップスタックが並立します。既存スタックが壊れるわけではありませんが、アプリ側の合成設定を新しい修飾子に合わせない限り、配備は元の系統を参照し続けます。同一アカウントを複数チームで分離したい場合など、理由が明確なときに限定してください。

ブートストラップ用のS3バケットが増え続けるのは止められますか？

cdk gcで未使用資産を整理できます。実行には--unstable=gcの明示指定が必要で、コマンド自体は開発途上という位置づけです。あわせてテンプレート版24以降では非現行オブジェクトの保持が30日、版25以降では未完了のマルチパートアップロードが1日で削除される設定に変わりました。古い版のままの環境はこの掃除設定が入っていないため、まず再ブートストラップで版を上げてください。

関連記事

• AWS CDK（cdk）とは？仕組み・使い方とCloudFormation・Terraformとの違い：CDKそのものの仕組みと他のIaCツールとの違いを、入門の位置から整理しています。
• AWS CDKのスタックとは？CloudFormationスタックとの対応と分割・デプロイ：ブートストラップ後に設計するスタックの分割粒度とデプロイ制御を扱っています。
• CDK for Terraform（CDKTF）とは？提供終了後の移行判断を解説：同じCDKの名を持つTerraform版の現況と、移行先の判断をまとめています。