CDK CLI を使用してブートストラップをカスタマイズするデフォルトのブートストラップテンプレートを変更するブートストラップ契約に従う

AWS CDK ブートストラップをカスタマイズする

AWS コマンドラインインターフェイス (AWS CDK CLI) を使用するか、AWS CloudFormation ブートストラップテンプレートを変更してデプロイすることで、AWS Cloud Development Kit (AWS CDK) ブートストラップをカスタマイズできます。

ブートストラップの概要については、「AWS CDK ブートストラップ」を参照してください。

CDK CLI を使用してブートストラップをカスタマイズする

CDK CLI を使用してブートストラップをカスタマイズする方法の例を以下に示します。すべての cdk bootstrap オプションのリストについては、「cdk ブーストラップ」を参照してください。

Amazon S3 バケットの名前を上書きする: --bootstrap-bucket-name オプションを使用して、デフォルトの Amazon S3 バケット名を上書きします。これには、テンプレート合成の変更が必要になる場合があります。詳細については、「CDK スタック合成をカスタマイズする」を参照してください。

Amazon S3 バケットのサーバー側の暗号化キーを変更する: デフォルトでは、ブートストラップスタックの Amazon S3 バケットは、サーバー側の暗号化に AWS 管理キーを使用するように設定されています。既存のカスタマー管理キーを使用するには、--bootstrap-kms-key-id オプションを使用し、AWS Key Management Service (AWS KMS) キーの値を指定します。暗号化キーをより詳細に制御したい場合は、カスタマー管理キーを使用するように --bootstrap-customer-key を指定します。

AWS CloudFormation が引き受けるデプロイロールに管理ポリシーをアタッチする

デフォルトでは、スタックは AdministratorAccess ポリシーを使用して、完全な管理者アクセス許可でデプロイされます。独自の管理ポリシーを使用するには、--cloudformation-execution-policies オプションを使用し、デプロイロールにアタッチする管理ポリシーの ARN を指定します。

複数のポリシーを指定するには、カンマで区切られた 1 つの文字列として渡します。


$ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess"

デプロイの失敗を回避するには、指定したポリシーが、ブートストラップされる環境に実行するデプロイに対して十分であることを確認してください。

ブートストラップスタック内のリソースの名前に追加される修飾子を変更する

デフォルトでは、hnb659fds 修飾子はブートストラップスタック内のリソースの物理 ID に追加されます。この値を変更するには、--qualifier オプションを使用します。

この変更は、名前の衝突を避けるために、同じ環境で複数のブートストラップスタックをプロビジョニングする場合に役立ちます。

修飾子の変更は、CDK 自体の自動テスト間の名前の分離を目的としています。CloudFormation 実行ロールに付与された IAM アクセス許可を非常に正確に範囲指定できない限り、1 つのアカウントに 2 つの異なるブートストラップスタックを持つことによるアクセス許可の分離上の利点はありません。したがって、通常、この値を変更する必要はありません。

修飾子を変更するとき、CDK アプリは変更された値をスタックシンセサイザーに渡す必要があります。詳細については、「CDK スタック合成をカスタマイズする」を参照してください。

ブートストラップスタックにタグを追加する

KEY=VALUE の形式の --tags オプションを使用して、ブートストラップスタックに CloudFormation タグを追加します。

ブートストラップされる環境にデプロイできる追加の AWS アカウントを指定する

ブートストラップ中の環境にデプロイすることを許可する追加の AWS アカウントを指定するには、--trust オプションを使用します。デフォルトでは、ブートストラップを実行するアカウントは常に信頼されます。

このオプションは、別の環境から CDK Pipeline がデプロイする環境をブートストラップする場合に便利です。

このオプションを使用する場合は、--cloudformation-execution-policies も指定する必要があります。

信頼されたアカウントを既存のブートストラップスタックに追加するには、以前に提供したアカウントを含め、信頼するすべてのアカウントを指定する必要があります。信頼するアカウントとして新しいアカウントのみを指定した場合、以前に信頼されたアカウントは削除されます。

以下は、2 つのアカウントを信頼する場合の例です。


$ cdk bootstrap aws://123456789012/us-west-2 --trust 234567890123 --trust 987654321098 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess
 ⏳  Bootstrapping environment aws://123456789012/us-west-2...
Trusted accounts for deployment: 234567890123, 987654321098
Trusted accounts for lookup: (none)
Execution policies: arn:aws:iam::aws:policy/AdministratorAccess
CDKToolkit: creating CloudFormation changeset...
 ✅  Environment aws://123456789012/us-west-2 bootstrapped.

ブートストラップする環境内の情報を検索できる追加の AWS アカウントを指定する: --trust-for-lookup オプションを使用して、ブートストラップする環境からコンテキスト情報を検索できる AWS アカウントを指定します。このオプションは、実際にそれらのスタックを直接デプロイするアクセス許可をアカウントに付与することなく、環境にデプロイされるスタックを合成するアクセス許可を付与するのに役立ちます。

ブートストラップスタックの終了保護を有効にする

ブートストラップスタックが削除されると、最初に環境でプロビジョニングされた AWS リソースも削除されます。環境がブートストラップされたら、意図的にブートストラップスタックを削除して再作成しないことをおすすめします。代わりに、cdk bootstrap コマンドを再度実行して、ブートストラップスタックを新しいバージョンに更新してみてください。

--termination-protection オプションを使用して、ブートストラップスタックの終了保護設定を管理します。終了保護を有効にすることで、ブートストラップスタックとそのリソースが誤って削除されるのを防ぐことができます。これは、CDK Pipelines を使用する場合に特に重要です。なぜなら、ブートストラップスタックを誤って削除した場合、一般的な復旧オプションがないからです。

終了保護を有効にした後、AWS CLI または AWS CloudFormation コンソールを使用して検証できます。

終了保護を有効化するには

次のコマンドを実行して、新規または既存のブートストラップスタックで終了保護を有効にします。
```
$ cdk bootstrap --termination-protection
```
AWS CLI または CloudFormation コンソールを使用して確認します。以下に示しているのは、AWS CLI を使用した例です。ブートストラップスタック名を変更した場合は、CDKToolkit をスタック名に置き換えます。
```
$ aws cloudformation describe-stacks --stack-name <CDKToolkit> --query "Stacks[0].EnableTerminationProtection"
true
```

デフォルトのブートストラップテンプレートを変更する

CDK CLI が提供できる以上のカスタマイズが必要な場合は、必要に応じてブートストラップテンプレートを変更できます。次に、テンプレートをデプロイして環境をブートストラップします。

デフォルトのブートストラップテンプレートを変更してデプロイするには

--show-template オプションを使用して、デフォルトのブートストラップテンプレートを取得します。デフォルトでは、CDK CLI はターミナルウィンドウにテンプレートを出力します。CDK CLI コマンドを変更して、テンプレートをローカルマシンに保存できます。以下に例を示します。
```
$ cdk bootstrap --show-template > <my-bootstrap-template.yaml>
```
必要に応じてブートストラップテンプレートを変更します。変更を加える場合は、ブートストラップテンプレート契約に従う必要があります。ブートストラップテンプレート契約の詳細については、「ブートストラップ契約に従う」を参照してください。

デフォルトテンプレートを使用して cdk bootstrap を実行する他のユーザーによって、カスタマイズした内容が誤って上書きされることを防ぐには、BootstrapVariant テンプレートパラメータのデフォルト値を変更します。CDK CLI は、現在デプロイされているテンプレートと同じ BootstrapVariant を持ち、かつ同じかそれ以上のバージョンを持つテンプレートによってのみ、ブートストラップスタックの上書きを許可します。
任意の AWS CloudFormation のデプロイ方法を使用して、変更されたテンプレートをデプロイします。CDK CLI を使用した例を以下に示します。
```
$ cdk bootstrap --template <my-bootstrap-template.yaml>
```

ブートストラップ契約に従う

CDK アプリケーションを適切にデプロイするには、合成中に生成される CloudFormation テンプレートが、ブートストラップ中に作成されるリソースを正しく指定している必要があります。これらのリソースは、一般的にブートストラップリソースと呼ばれます。ブートストラップは、デプロイの実行とアプリケーションアセットの管理に AWS CDK が使用するリソースを AWS 環境に作成します。合成は、アプリケーション内の各 CDK スタックから CloudFormation テンプレートを生成します。これらのテンプレートは、アプリケーションからプロビジョニングされる AWS リソースを定義するだけではありません。これらは、デプロイ中に使用するブートストラップリソースも指定します。

合成中、AWS 環境がどのようにブートストラップされているか、CDK CLI は具体的には把握していません。代わりに CDK CLI は、設定したシンセサイザーに基づいて CloudFormation テンプレートを生成します。そのため、ブートストラップをカスタマイズするときは、合成をカスタマイズする必要があります。合成をカスタマイズする手順については、「CDK スタック合成をカスタマイズする」を参照してください。目的は、合成された CloudFormation テンプレートがブートストラップ環境と互換性があることを確認することです。この互換性は、ブートストラップ契約と呼ばれます。

スタック合成をカスタマイズする最も簡単な方法は、Stack インスタンスの DefaultStackSynthesizer クラスを変更することです。このクラスで提供できる以上のカスタマイズが必要な場合は、IStackSynthesizer を実装するクラスとして独自のシンセサイザーを作成することができます (おそらく DefaultStackSynthesizer から派生させることになります)。

ブートストラップをカスタマイズするときは、ブートストラップテンプレートの契約に従って DefaultStackSynthesizer との互換性を維持します。ブートストラップテンプレート契約を超えてブートストラップを変更する場合は、独自のシンセサイザーを作成する必要があります。

バージョニング

ブートストラップテンプレートには、よく知られた名前とテンプレートのバージョンを反映する出力を持つ Amazon EC2 Systems Manager (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]

ロール

DefaultStackSynthesizer は、5 つの異なる目的のために 5 つの IAM ロールを必要とします。デフォルトのロールを使用していない場合は、DefaultStackSynthesizer オブジェクト内で IAM ロール ARN を指定する必要があります。ロールは以下のとおりです。

デプロイロールは、CDK CLI と AWS CodePipeline によって引き受けられ、環境にデプロイされます。これの AssumeRolePolicy は、環境にデプロイできるユーザーを制御します。テンプレートでは、このロールに必要なアクセス許可を確認できます。
ルックアップロールは、環境でコンテキストルックアップを実行するために、CDK CLI によって引き受けられます。これの AssumeRolePolicy は、環境にデプロイできるユーザーを制御します。このロールに必要なアクセス許可は、テンプレートで確認できます。
ファイル発行ロールとイメージ発行ロールは、環境内にアセットを発行するために、CDK CLI と AWS CodeBuild プロジェクトによって引き受けられます。これらは、それぞれ Amazon S3 バケットと Amazon ECR リポジトリへの書き込みに使用されます。これらのロールには、これらのリソースへの書き込みアクセス許可が必要です。
AWS CloudFormation 実行ロールは AWS CloudFormation に渡され、実際のデプロイを実行します。そのアクセス許可は、デプロイが実行される際に使用されるアクセス許可です。このアクセス許可は、管理ポリシーの ARN を列挙したパラメータとしてスタックに渡されます。

Outputs

CDK CLI は、ブートストラップスタックに以下の CloudFormation 出力が存在することを必要とします。

BucketName – ファイルアセットバケットの名前。
BucketDomainName – ドメイン名形式のファイルアセットバケット。
BootstrapVersion – ブートストラップスタックの最新バージョン。

テンプレート履歴

ブートストラップテンプレートはバージョン管理され、AWS CDK 自体とともに時間の経過とともに進化します。独自のブートストラップテンプレートを指定する場合は、正規のデフォルトテンプレートを使用して最新の状態を維持します。テンプレートがすべての CDK 機能と引き続き連携するようにする必要があります。詳細については、「ブートストラップテンプレートのバージョン履歴」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

環境のブートストラップ

アクセス許可の境界を作成して適用する