これはAWS CDK v2 開発者ガイドです。古いCDK v1は2022年6月1日にメンテナンスを開始し、今後は重大なバグ修正とセキュリティパッチのみが提供されます。新機能はCDK v2専用に開発されます。CDK v1 Support は、2023 年 6 月 1 日に完全に終了します。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
ブートストラッピング
ブートストラップは、AWS CDKAWS CDKAWSアプリケーションを環境にデプロイする前にリソースをプロビジョニングするプロセスです。(AWSAWS環境はアカウントとリージョンの組み合わせです)。
これらのリソースには、ファイルを保存するための Amazon S3 バケットや、デプロイの実行に必要なアクセス権限を付与する IAM ロールが含まれます。
必要なリソースは、AWS CloudFormationブートストラップスタックと呼ばれるスタックで定義され、CDKToolkit
通常は名前が付けられます。AWS CloudFormation他のスタックと同様に、AWS CloudFormationデプロイされるとコンソールに表示されます。
注記
CDK v2 は、モダンテンプレートと呼ばれるブートストラップテンプレートを使用します。CDK v1 のレガシーテンプレートは v2 ではサポートされていません。
環境は独立しています。複数の環境 (AWS異なるアカウントまたは同じアカウント内の異なるリージョン) にデプロイする場合は、各環境を個別にブートストラップする必要があります。
重要
AWSブートストラップされたリソースに保存されているデータには料金が発生する可能性があります。
注記
AWS KMS key以前のバージョンのブートストラップテンプレートでは、ブートストラップ環境ごとにがデフォルトで作成されていました。KMS キーに課金されないようにするには、--no-bootstrap-customer-key
を使用してこれらの環境を再ブートストラップしてください。現在のデフォルトではKMSキーがないため、このような請求を回避できます。
AWS CDK必要なリソースがない環境にアプリケーションをデプロイしようとすると、環境をブートストラップするように促すエラーメッセージが表示されます。
CDK Pipelines を使用して別のアカウントの環境にデプロイしているときに、次のようなメッセージが表示される場合
Policy contains a statement with one or more invalid principals
このエラーメッセージは、適切な IAM ロールが他の環境に存在しないことを意味します。最も可能性の高い原因は、ブートストラップの欠如です。
注記
CDK Pipelines を使用してそのアカウントにデプロイしている場合は、アカウントのブートストラップスタックを削除して再作成しないでください。パイプラインは動作を停止します。ブートストラップスタックを新しいバージョンに更新するには、cdk bootstrap
代わりに再実行してブートストラップスタックを所定の位置に更新します。
ブートストラップ
ブートストラップとは、AWS特定の環境 (アカウントとリージョン)AWS CloudFormation にテンプレートをデプロイすることです。ブートストラップテンプレートは、ブートストラップリソースの一部の側面をカスタマイズするパラメータを受け入れます (を参照ブートストラップのカスタマイズ)。したがって、ブートストラップには、次の 2 つの方法があります。
-
AWS CDKcdk bootstrapツールキットのコマンドを使用してください。これは最も簡単な方法で、ブートストラップする環境が少ない場合に適しています。
-
AWS CDKツールキットから提供されたテンプレートを、AWS CloudFormation別のデプロイツールを使用してデプロイします。これにより、AWS CloudFormation StackSets またはだけでなくAWS Control Tower、AWS CloudFormationコンソールまたはも使用できますAWS CLI。展開前にテンプレートに小さな変更を加えることができます。このアプローチはより柔軟で、大規模な導入に適しています。
環境を複数回ブートストラップしてもエラーにはなりません。ブートストラップする環境がすでにブートストラップされている場合、そのブートストラップスタックは必要に応じてアップグレードされます。そうしないと、何も起こりません。
AWS CDKツールキットによるブートストラップ
cdk bootstrap
コマンドを使用して 1AWS つ以上の環境をブートストラップします。基本的な形式では、このコマンドは 1AWS つ以上の指定された環境 (この例では 2 つ) をブートストラップします。
cdk bootstrap aws://
ACCOUNT-NUMBER-1
/REGION-1
aws://ACCOUNT-NUMBER-2
/REGION-2
...
次の例は、それぞれ 1 つと 2 つの環境のブートストラップを示しています。(AWSどちらも同じアカウントを使用します。) 2 番目の例に示すように、aws://
環境を指定する場合のプレフィックスはオプションです。
cdk bootstrap aws://123456789012/us-east-1 cdk bootstrap 123456789012/us-east-1 123456789012/us-west-1
CDK ToolkitAWS CDK は常に現在のディレクトリにあるアプリを合成します。cdk bootstrap
コマンドで少なくとも 1 つの環境を指定しない場合、アプリで参照されているすべての環境がブートストラップされます。
スタックが環境に依存しない (つまり、env
プロパティを持たない) 場合は、CDK の環境を適用してスタックを環境固有のものにします。CDK の環境は、--profileまたは環境変数を使用して指定された環境か、AWSそれ以外の場合はデフォルトの環境です。その後、その環境はブートストラップされます。
たとえば、次のコマンドは、AWS CDKprod
AWSプロファイルを使用して現在のアプリを合成し、その環境をブートストラップします。
cdk bootstrap --profile prod
AWS CloudFormationテンプレートからのブートストラップ
AWS CDKAWS CloudFormationブートストラップはテンプレートによって実行されます。ファイル内のこのテンプレートのコピーを取得するにはbootstrap-template.yaml
、次のコマンドを実行します。
AWS CDK GitHub テンプレートはリポジトリにもあります
このテンプレートは、cdk bootstrap --template
TEMPLATE_FILENAME
AWS CloudFormationまたはお好みのテンプレート展開メカニズムを使用して展開します。たとえば、次のコマンドは、次のコマンドを使用してテンプレートをデプロイしますAWS CLI。
ブートストラップ
前述のように、AWS CDK v1はレガシーとモダンの2つのブートストラップテンプレートをサポートしていました。CDK v2 は最新のテンプレートのみをサポートします。参考までに、これら 2 つのテンプレートの大まかな違いを以下に示します。
特徴 | レガシー (v1 のみ) | モダン (v1 および v2) |
---|---|---|
クロスアカウントデプロイメント | 許可されていません | 許可 |
AWS CloudFormationパーミッション | 現在のユーザーの権限 (AWSプロファイル、環境変数などによって決まる) を使用してデプロイします | --trust ブートストラップスタックのプロビジョニング時に指定された権限を使用してデプロイします (たとえば、 |
バージョニング | ブートストラップスタックのバージョンは 1 つしかありません | ブートストラップスタックはバージョン管理されており、新しいリソースはfuture バージョンで追加される可能性があり、AWS CDKアプリには最低限のバージョンが必要になる可能性があります |
リソース * | Amazon S3 バケット | Amazon S3 バケット |
AWS KMS key | ||
IAM ロール | ||
Amazon ECR リポジトリ | ||
バージョニングの SSM パラメータ | ||
リソース命名 | [自動生成] | 決定論的 |
バケット暗号化 | デフォルトキー | カスタマーマネージドキー |
* 必要に応じて、ブートストラップテンプレートにリソースを追加します。
レガシーテンプレートを使用してブートストラップされた環境は、ブートストラップを再実行して CDK v2 用の最新テンプレートを使用するようにアップグレードする必要があります。レガシーバケットを削除する前に、AWS CDK環境内のすべてのアプリケーションを少なくとも 1 回再デプロイしてください。
ブートストラップのカスタマイズ
ブートストラップリソースをカスタマイズする方法は 2 つあります。
-
cdk bootstrap
コマンドではコマンドラインパラメータを使用します。これにより、テンプレートのいくつかの部分を変更できます。 -
デフォルトのブートストラップテンプレートを変更し、自分でデプロイします。これにより、ブートストラップリソースをより完全に制御できます。
以下のコマンドラインオプションを CDK Toolkit で使用するとcdk bootstrap、ブートストラップテンプレートに一般的に必要な調整を行うことができます。
-
-bootstrap-bucket-name-Amazon S3 バケットの名前。CDK アプリへの変更が必要な場合があります (を参照スタック・シンセサイザー)。
-
--bootstrap-kms-key-idS3AWS KMS バケットの暗号化に使用されるキーを上書きします。
-
--cloudformation-execution-policiesAWS CloudFormationスタックのデプロイ時に引き受けるデプロイロールにアタッチする必要がある管理ポリシーの ARN を指定します。デフォルトでは、
AdministratorAccess
スタックはポリシーを使用して完全な管理者権限でデプロイされます。ポリシー ARN は、個々の ARN をカンマで区切って 1 つの文字列引数として渡す必要があります。例:
--cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess".
重要
デプロイの失敗を避けるため、指定するポリシーが、ブートストラップ対象の環境で実行するデプロイに十分であることを確認してください。
-
--qualifierは、ブートストラップスタックのすべてのリソースの名前に追加される文字列です。修飾子を使用すると、を使用して同じ環境で複数のブートストラップスタックをプロビジョニングするときに、リソース名の衝突を回避できます--toolkit-stack-name。デフォルトはです
hnb659fds
(この値には意味がありません)。修飾子を変更するには、CDK アプリが変更された値をスタックシンセサイザーに渡す必要もあります。詳細については、「スタック・シンセサイザー」を参照してください。
-
--tagsブートストラップスタックに 1AWS CloudFormation つ以上のタグを追加します。
-
--trustAWSブートストラップ対象の環境にデプロイできるアカウントを一覧表示します。
このフラグは、別の環境の CDK Pipeline がデプロイされる環境をブートストラップするときに使用します。ブートストラップを行うアカウントは常に信頼されています。
-
--trust-for-lookupは、AWSブートストラップ中の環境からコンテキスト情報を検索できるアカウントの一覧です。
このフラグを使用すると、実際にスタックを直接デプロイする権限を与えることなく、環境にデプロイされるスタックを合成する権限をアカウントに付与できます。
-
--termination-protectionブートストラップスタックが削除されないようにします。詳細については、『AWS CloudFormationユーザーガイド』の「スタックが削除されないように保護する」を参照してください。
重要
最新のブートストラップテンプレートでは、AWS--trust
によって暗示される権限がリスト内のどのアカウントにも効果的に付与されます。--cloudformation-execution-policies
デフォルトでは、これにより、ブートストラップアカウント内の任意のリソースに対する読み取りと書き込みの権限が拡張されます。ブートストラップスタックには、使い慣れたポリシーと信頼できるアカウントを設定してください。
テンプレートのカスタマイズ
AWS CDKToolkit スイッチが提供できる以上のカスタマイズが必要な場合は、ブートストラップテンプレートをニーズに合わせて変更できます。--show-templateテンプレートはフラグを使用して取得できることを忘れないでください。
cdk bootstrap --show-template
変更を加える場合は、ブートストラップテンプレート契約に従う必要があります。
で説明されているようにAWS CloudFormationテンプレートからのブートストラップ、またはを使用して、cdk bootstrap --template変更したテンプレートをデプロイします。
cdk bootstrap --template bootstrap-template.yaml
スタック・シンセサイザー
デプロイ可能なスタックを正常に合成するには、AWS CDKアプリで使用可能なブートストラップリソースをアプリが把握している必要があります。スタックシンセサイザーは、AWS CDKスタックのテンプレートの合成方法を制御するクラスです。これには、ブートストラップリソースの使用方法 (ブートストラップバケットに保存されているアセットを参照する方法など) が含まれます。
AWS CDKDefaultStackSynthesizer
のビルトインスタックシンセサイザーが呼び出されます。クロスアカウントデプロイと CDK Pipelines デプロイの機能が含まれています。
synthesizer
プロパティを使用してスタックシンセサイザーをインスタンス化するときに、スタックシンセサイザーをスタックに渡すことができます。
synthesizer
プロパティを指定しない場合は、DefaultStackSynthesizer
が使用されます。
合成のカスタマイズ
bootstrap テンプレートに加えた変更によっては、合成をカスタマイズする必要もあります。はDefaultStackSynthesizer
、以下のプロパティを使用してカスタマイズできます。
これらのプロパティのどれも必要なカスタマイズを提供しない場合は、シンセサイザーを実装するクラスIStackSynthesizer
(おそらくから派生したクラスDefaultStackSynthesizer
) として記述できます。
修飾子の変更
修飾子は、個別のブートストラップスタック内のリソースを区別するために、ブートストラップリソースの名前に追加されます。同じ環境 (AWSアカウントとリージョン) に 2 つの異なるバージョンのブートストラップスタックをデプロイするには、スタックに異なる修飾子が必要です。
この機能は、CDK 自体の自動テスト間で名前を分離することを目的としています。AWS CloudFormation実行ロールに与えられる IAM 権限の範囲をきわめて正確に絞り込めない限り、1 つのアカウントに 2 つの異なるブートストラップスタックがあっても権限分離のメリットはありません。したがって、通常、この値を変更する必要はありません。
修飾子を変更するには、次のプロパティを使用してシンセサイザーをインスタンス化して、DefaultStackSynthesizer
どちらかを設定します。
または、修飾子をコンテキストキーとして設定しますcdk.json
。
{ "app": "...", "context": { "@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER" } }
リソース名の変更
DefaultStackSynthesizer
他のすべてのプロパティは、ブートストラップテンプレート内のリソースの名前に関連しています。これらのプロパティのいずれかを指定する必要があるのは、ブートストラップテンプレートを変更し、リソース名または命名スキームを変更した場合のみです。
すべてのプロパティで特殊なプレースホルダー${Qualifier}
、${AWS::Partition}
、${AWS::AccountId}
、を使用できます${AWS::Region}
。これらのプレースホルダーは、qualifier
それぞれパラメーターの値、AWSスタックの環境のパーティション、アカウント ID、リージョンの値に置き換えられます。
次の例は、シンセサイザーをインスタンス化するかのように、で最も一般的に使用されるプロパティとそのデフォルト値を示しています。DefaultStackSynthesizer
詳細な一覧については、「DefaultStackSynthesizerProps」を参照してください。
ブートストラップテンプレート契約
ブートストラップスタックの要件は、使用しているスタックシンセサイザーによって異なります。独自のスタックシンセサイザーを作成すると、シンセサイザーが必要とするブートストラップリソースと、シンセサイザーがそれらを見つける方法を完全に制御できます。
このセクションでは、DefaultStackSynthesizer
がブートストラップテンプレートに期待する内容について説明します。
バージョニング
テンプレートには、よく知られている名前の SSM パラメータを作成するためのリソースと、テンプレートのバージョンを反映する出力が含まれている必要があります。
Resources: CdkBootstrapVersion: Type: AWS::SSM::Parameter Properties: Type: String Name: Fn::Sub: '/cdk-bootstrap/${Qualifier}/version' Value: 4 Outputs: BootstrapVersion: Value: Fn::GetAtt: [CdkBootstrapVersion, Value]
ロール
には、5 つの目的に応じて 5 つの IAMDefaultStackSynthesizer
ロールが必要です。デフォルトのロールを使用していない場合は、使用するロールの ARN をシンセサイザーに伝える必要があります。
役割は以下のとおりです。
-
デプロイメントの役割は、AWS CDKAWS CodePipelineツールキットと環境へのデプロイによって引き受けられます。
AssumeRolePolicy
誰が環境にデプロイできるかを制御します。テンプレートでは、このロールに必要な権限を確認できます。 -
ルックアップの役割は、AWS CDKツールキットが環境内でコンテキスト検索を実行するときに引き受けます。
AssumeRolePolicy
誰が環境にデプロイできるかを制御します。このロールに必要な権限は、テンプレートで確認できます。 -
ファイル公開の役割と画像公開の役割は、AWS CDKAWS CodeBuildツールキットとプロジェクトによって割り当てられ、アセットを環境に公開します。これらはそれぞれ、S3 バケットと ECR リポジトリに書き込めるように使用されます。これらのロールには、これらのリソースへの書き込みアクセス権が必要です。
-
AWS CloudFormation実行ロールは、AWS CloudFormation実際のデプロイを実行するために渡されます。その権限は、デプロイが実行される権限です。権限は、管理ポリシー ARN を一覧表示するパラメータとしてスタックに渡されます。
[Outputs] (出力)
AWS CDKツールキットでは、 CloudFormation ブートストラップスタックに次の出力が存在する必要があります。
-
BucketName
: ファイルアセットバケットの名前 -
BucketDomainName
: ドメイン名形式のファイルアセットバケット -
BootstrapVersion
: ブートストラップスタックの現在のバージョン
テンプレート履歴
ブートストラップテンプレートはバージョン管理されており、AWS CDK時間の経過とともにそれ自体も進化します。独自のブートストラップテンプレートを提供する場合は、正規のデフォルトテンプレートを使用して最新の状態に保ってください。テンプレートがすべての CDK 機能で引き続き機能することを確認する必要があります。
このセクションには、各バージョンで行われた変更のリストが含まれています。
テンプレートのバージョン | AWS CDK バージョン | 変更 |
---|---|---|
1 | 1.40.0 | バケット、キー、リポジトリ、ロールを含むテンプレートの初期バージョン。 |
2 | 1.45.0 | アセットの公開ロールを個別のファイル公開ロールと画像公開ロールに分割します。 |
3 | 1.46.0 | FileAssetKeyArn エクスポートを追加すると、アセットコンシューマーに復号化権限を追加できます。 |
4 | 1.61.0 | AWS KMSアクセス権限は Amazon S3 経由で暗黙的に適用されるようになり、不要になりましたFileAsetKeyArn 。CdkBootstrapVersion SSM パラメータを追加して、スタック名を知らなくてもブートストラップスタックのバージョンを確認できるようにします。 |
5 | 1.87.0 | デプロイロールは SSM パラメータを読み取ることができます。 |
6 | 1.108.0 | デプロイロールとは別にルックアップロールを追加します。 |
6 | 1.109.0 | デプロイメント、ファイル公開、aws-cdk:bootstrap-role およびイメージ公開ロールにタグをアタッチします。 |
7 | 1.110.0 | デプロイロールはターゲットアカウントのバケットを直接読み取ることができなくなりました。(ただし、このロールは実質的には管理者であり、AWS CloudFormationいつでもその権限を使用してバケットを読み取れるようにすることができます)。 |
8 | 1.114.0 | lookup ロールには、ターゲット環境に対する完全な読み取り専用権限があり、aws-cdk:bootstrap-role タグも付いています。 |
9 | 2.1.0 | Amazon S3 アセットのアップロードが、一般的に参照されている暗号化 SCP によって拒否されないように修正しました。 |
10 | 2.4.0 | Amazon ECR ScanOnPush は、現在、デフォルトで有効になります。 |
11 | 2.18.0 | Lambda が Amazon ECR リポジトリからプルすることを許可するポリシーを追加して、ブートストラップを再実行しても処理されないようにします。 |
12 | 2.20.0 | 実験的なサポートを追加しますcdk import。 |
13 | 2.25.0 | ブートストラップで作成された Amazon ECR リポジトリ内のコンテナイメージを変更不能にします。 |
14 | 2.34.0 | Amazon ECR イメージスキャンをデフォルトでリポジトリレベルでオフにし、イメージスキャンをサポートしないリージョンのブートストラップを許可します。 |