20251121 AWS CDK ブートストラップエラー解決ガイド

Transcript

1. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 1 © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. AWS CDK ブートストラップエラー解決ガイド よくある問題と解決策 沖村 光一郎 Cloud Support Engineer アマゾンウェブサービスジャパン合同会社 2025/11 JAWS-UG CDK 支部
2. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 2 自己紹介 • 沖村光一郎 • アマゾンウェブサービスジャパン合同会社 クラウドサポートエンジニア Subject Matter Expert(SME) 好きなサービス Amazon ECS AWS CloudFormation AWS CDK
3. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 3 概要 • CDK を使う際、最初にブートストラップする必要があり、CDK を使用するた めのリソースが作成される • これらの作成されたリソースを変更、削除してしまい、トラブルになる • 特定のご要件によるブートストラップの設定方法がわからない • サポートの経験を元に、よくあるケースと対処法を紹介します
4. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 4 アジェンダ • AWS CDK におけるブートストラップとは • ブートストラップのよくある問題と解決策 • ブートストラップについて AWS サポートに問い合わせたい
5. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 5 © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. AWS CDK における ブートストラップとは
6. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 6 AWS CDK におけるブートストラップとは • CDK からリソースをデプロイする時に使用する共通的なリソース を準備すること
7. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 7 AWS CDK におけるブートストラップとは AWS Black Belt Online Seminar Basic #2 基本的なコンポーネントと機能 https://pages.awscloud.com/rs/112-TZM-766/images/AWS-Black-Belt_2023_AWS-CDK-Basic-2-Features_0831_v1.pdf#page=8 CloudFormation Template Source Code CloudFormation cdk deploy Context 値の保存、解決 Deploy AWS CDK CDK CLI (CDK Toolkit) CDK App 呼び出し CDK CLI からデプロイを実⾏ するためのリソースを作成
8. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 8 環境にブートストラップする • cdk bootstrap <aws://(アカウントID)/(リージョン名)> • <> の引数を指定しない場合、デフォルトでは bin/*.ts の内容から対象アカウントと リージョンを判断 • CDK では AWS アカウント x リージョンの組み合わせを “環境” と呼んでい る • 環境毎にブートストラップが必要 • 複数の環境を指定可能 • cdk bootstrap <aws://123456789012/us-east-1> <aws://123456789012/us-east-2>
9. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 9 ブートストラップで作成されるリソース ECR リポジトリ S3 バケット LookUpRole CloudFormationExecution Role CloudFormation DeploymentAction Role ImagePublishing Role FilePublishing Role PassRole AWSリソース AssumeRole CDKCLI ブートストラップバージョンの参照 アセットファイルアップロード コンテナイメージの push スタック操作 ※ 使⽤される IAM, S3, ECR, SSM リソースは DefaultStackSynthesizer の場合 SSM Parameter Store リソースの参照 User cdk deploy ⾚枠内のリソースが CDKToolkit スタック経由で作成される CDK Security and Safety Dev Guide https://github.com/aws/aws-cdk/wiki/Security-And-Safety-Dev-Guide#controlling-the-permissions-used-by-cdk-deployments
10. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 10 ブートストラップで作成されるリソース • CDK にて使用される IAM ロールの詳細については下記セッション をご確認ください。 • CDK を安心して使うために改めて読み直そう。CDK Security and Safety Dev Guide（DEV-1-10） • https://www.youtube.com/watch?v=5waGpEIgJCg
11. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 11 ブートストラップに必要な権限 • ブートストラップを実行する IAM ロール/IAMユーザに 右のアクションの許可が必要 • --profile オプションを付与することで実 行するプロファイルを切り替えられる CDK Security and Safety Dev Guide https://github.com/aws/aws-cdk/wiki/Security-And-Safety-Dev-Guide#controlling-the-permissions-used-by-cdk-deployments
12. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 12 © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. ブートストラップの よくある問題と解決策
13. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 13 ブートストラップのトラブルシューティング事例 • Q1: CDKToolkit スタックを消してしまった • Q2: ブートストラップ実行時に S3 バケットの AlreadyExists エラーが出る • Q3: ブートストラップで作成されるリソースを制限、リネームしたい
14. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 15 Q1: CDKToolkit スタックを消してしまった 1. アセット用 S3 バケットがアカウントに存在するか確認 • cdk-(qualifier)-assets-(アカウントID)-(リージョン名) • qualifier: デフォルト hnb659fds [補足] CDKToolKit スタックを削除してもアセット用 S3 バケットは削 除されない • DeletionPolicy に Retain が設定されている https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml#L238
15. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 16 Q1: CDKToolkit スタックを消してしまった 2. 任意のバックアップ用 S3 バケットを作成し アセット用 S3 バケット内のオブジェクトをコピー • S3 バケット内のすべてのオブジェクトのコピー方法 • https://repost.aws/ja/knowledge-center/move-objects-s3-bucket 3. アセット用の S3 バケットを削除 バックアップ用 S3 バケット アセット用 S3 バケット
16. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 17 Q1: CDKToolkit スタックを消してしまった 4. ブートストラップを再実行してCDKToolKit スタックを再作成 5. バックアップ用 S3 バケットからアセット用オブジェクトを アセット用の S3 バケットにコピー バックアップ用 S3 バケット 新 アセット用 S3 バケット
17. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 18 Q1: CDKToolkit スタックを消してしまった 6. バックアップ用 S3 バケットを削除 [補足] オブジェクトのコピーをする必要はあるのか • CDK から既にデプロイしているスタックがある場合は必須。 アセットが見つからずロールバックデプロイで失敗する状況を防ぐ バックアップ用 S3 バケット 新 アセット用 S3 バケット
18. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 21 Q2: ブートストラップ実行時に S3 バケットの AlreadyExists エラーが出る • 次のような AlreadyExists エラーが発生します • 次の状況でブートストラップを実行している • CDKToolKit スタックを削除後、再度ブートストラップを実行している • CDKToolKit スタックを削除してもアセット用 S3 バケットは削除されない
19. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 22 Q2: ブートストラップ実行時に S3 バケットの AlreadyExists エラーが出る • CDKToolKit スタックがアカウントにあるか確認 • 誤って CDKToolKit スタックを削除していないか • なければ「Q1: CDKToolKit スタックを消してしまった」手順にて復旧
20. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 23 Q3:ブートストラップで作成されるリソース を制限、リネームしたい • プロジェクトの命名規約に沿ったリソース名に変更したい • CloudFormationExecutionRole の権限を絞りたい • デフォルトでは AdministratorAccess ポリシーが付与される • コンテナアセットは使わないので ECR リポジトリを削除したい • ブートストラップはカスタマイズできる
21. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 24 ブートストラップのカスタマイズ • アセット用 S3 バケット名を変更する • --bootstrap-bucket-name オプション • S3 バケット名はすべての AWS アカウントで一意である必要 • CloudFormationExecuteionRole にアタッチする管理ポリシーを変 更する • --cloudformation-execution-policies オプション
22. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 25 ブートストラップのカスタマイズ • ブートストラップに使用する CloudFormation テンプレートを 変更できる 1. cdk bootstrap --show-template > <my-bootstrap-template.yaml> にてファイル出力 2. テンプレートを変更 3. cdk bootstrap --template <my-bootstrap-template.yaml> にてブートストラップ • その他の変更については以下ドキュメントを参照 • https://docs.aws.amazon.com/ja_jp/cdk/v2/guide/bootstrapping-customizing.html
23. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 30 © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. ブートストラップについて AWS サポートに問い合わせたい
24. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 31 自分でできるトラブルシューティング • ブートストラップの実行結果にエラー内容がないか • --verbose --debug オプションを付けて実行することで 詳細なログが取得できる • (認証系の問題の場合) コマンドを実行した IAM ロール/ユーザーは 正しいか • AWS CLI の aws sts get-caller-identity コマンドの実行結果を確認
25. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 32 AWS サポートへの問い合わせ • 下記情報を添えて問い合わせください • --verbose --debug オプション を付与した cdk bootstrap コマンドの 実行結果 • AWS CLI の aws sts get-caller-identity コマンドの実行結果 • cdk --version コマンドの実行結果 (CDK CLI のバージョン) • (可能な場合) CDK コマンドを実行しているディレクトリ配下一式 • 個人情報、パスワード、API キーといった秘匿情報などは必ず削除またはマスク
26. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 33 [補足] AWS サポートへの問い合わせ • AWS サポートではお客様の課題解決を効率よく迅速に行いたいと 考えております 初回お問い合わせ時に事前情報をいただくことで、お客様の状況 を詳細に把握した上での回答が可能です • 問い合わせに関するガイドラインもご活用ください • https://aws.amazon.com/jp/premiumsupport/tech-support-guidelines/
27. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 34 まとめ • AWS CDK におけるブートストラップとは • CDK を利用するために必要なリソースを作成 • ブートストラップのよくある問題と解決策 • お客様自身でトラブルシューティング可能 • ブートストラップについて AWS サポートに問い合わせたい • 必要な情報を揃え、早期問題解決につなげよう
28. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark. 35 Thank you! © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Amazon Confidential and Trademark.