これは v2 AWS CDK デベロッパーガイドです。古い CDKv1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
AWS Cloud Development Kit (AWS CDK) スタック合成をカスタマイズするには、デフォルトのシンセサイザーを変更するか、他の使用可能な組み込みシンセサイザーを使用するか、独自のシンセサイザーを作成します。
AWS CDK には、合成動作をカスタマイズするために使用できる以下の組み込みシンセサイザーが含まれています。
-
DefaultStackSynthesizer
– シンセサイザーが未指定の場合、これが自動的に使用されます。CDK Pipelines コンストラクトを使用したクロスアカウントデプロイとデプロイをサポートします。ブートストラップ契約には、既知の名前の既存の Amazon S3 バケット、既知の名前の既存の Amazon ECRリポジトリ、および既知の名前の 5 つの既存のIAMロールが必要です。デフォルトのブートストラップテンプレートは、これらの要件を満たしています。 -
CliCredentialsStackSynthesizer
– このシンセサイザーのブートストラップ契約には、既存の Amazon S3 バケットと既存の Amazon ECRリポジトリが必要です。IAM ロールは必要ありません。デプロイを実行するために、このシンセサイザーは のアクセス許可に依存します。 CDKCLI ユーザー と は、IAMデプロイ認証情報を制限したい組織に適しています。このシンセサイザーは、クロスアカウントデプロイまたはCDKパイプラインをサポートしていません。 -
LegacyStackSynthesizer
– このシンセサイザーは v1 CDK 合成動作をエミュレートします。ブートストラップ契約には、任意の名前の既存の Amazon S3 バケットが必要であり、アセットの場所が CloudFormation スタックパラメータとして渡されることを想定しています。このシンセサイザーを使用する場合は、 CDKCLI デプロイを実行する 。
これらの組み込みシンセサイザーがユースケースに適さない場合は、独自のシンセサイザーを を実装するクラスとして記述IStackSynthesizer
したり、 からシンセサイザー
DefaultStackSynthesizer
のカスタマイズ
DefaultStackSynthesizer
は、 AWS CDKのデフォルトのシンセサイザーです。CDK アプリケーションのクロスアカウントデプロイ、および の明示的なサポートがないが、 などの通常のデプロイをサポートする CI/CD AWS CDKシステムからCDKのアプリケーションの CloudFormation デプロイを可能にするように設計されています AWS CodePipeline。このシンセサイザーは、ほとんどのユースケースに最適なオプションです。
DefaultStackSynthesizer
のブートストラップ契約
DefaultStackSynthesizer
には、以下のブートストラップ契約が必要です。ブートストラップ時に作成する必要があるリソースは以下のとおりです。
ブートストラップのリソース | 説明 | デフォルトの想定リソース名 | 目的 |
---|---|---|---|
Amazon S3 バケット |
ステージングバケット |
cdk-hnb659fds-assets- |
ファイルアセットを保存します。 |
Amazon ECRリポジトリ |
ステージングリポジトリ |
cdk-hnb659fds-container-assets- |
の保存と管理 Docker イメージアセット。 |
IAM ロール |
デプロイロール |
cdk-hnb659fds-deploy-role- |
が引き受ける CDK CLI および CodePipeline は、他のロールを AWS CloudFormation 引き受け、デプロイを開始する可能性があります。 このロールの信頼ポリシーは、 AWS CDK この AWS 環境で を使用してデプロイできるユーザーを制御します。 |
IAM ロール |
AWS CloudFormation 実行ロール |
cdk-hnb659fds-cfn-exec-role- |
このロールは、デプロイを実行する AWS CloudFormation ために によって使用されます。 このロールのポリシーは、CDKデプロイが実行できるオペレーションを制御します。 |
IAM ロール |
ルックアップロール |
cdk-hnb659fds-lookup-role- |
このロールは、 CDKCLI は環境コンテキストルックアップを実行する必要があります。 このロールの信頼ポリシーは、環境内の情報を参照できるユーザーを制御します。 |
IAM ロール |
ファイル発行ロール |
cdk-hnb659fds-file-publishing-role- |
このロールは、Amazon S3 ステージングバケットにアセットをアップロードするために使用されます。これはデプロイロールから引き受けられます。 |
IAM ロール |
イメージ発行ロール |
cdk-hnb659fds-image-publishing-role- |
このロールはアップロードに使用されます Docker Amazon ECRステージングリポジトリへの イメージ。これはデプロイロールから引き受けられます。 |
SSM パラメータ |
ブートストラップバージョンのパラメータ |
/cdk-bootstrap/hnb659fds/ |
ブートストラップテンプレートのバージョンです。これは、ブートストラップテンプレートと CDK CLI は要件を検証します。 |
CDK スタック合成をカスタマイズする方法の 1 つは、 を変更することですDefaultStackSynthesizer
。Stack
インスタンスの synthesizer
プロパティを使用して、このシンセサイザーを単一のCDKスタック用にカスタマイズできます。App
インスタンスの defaultStackSynthesizer
プロパティを使用して、CDKアプリ内のすべてのスタックDefaultStackSynthesizer
の を変更することもできます。
修飾子の変更
ブートストラップ時に作成されたリソースの名前には修飾子が追加されます。デフォルトでは、この値は hnb659fds
です。ブートストラップ中に修飾子を変更する場合は、同じ修飾子を使用するようにCDKスタック合成をカスタマイズする必要があります。
修飾子を変更するには、 の qualifier
プロパティを設定するDefaultStackSynthesizer
か、CDKプロジェクトの cdk.json
ファイルで修飾子をコンテキストキーとして設定します。
以下は、DefaultStackSynthesizer
の qualifier
プロパティを設定する場合の例です。
new MyStack(this, 'MyStack', {
synthesizer: new DefaultStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
以下は、cdk.json
で修飾子をコンテキストキーとして設定する場合の例です。
{
"app": "...",
"context": {
"@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER"
}
}
リソース名の変更
DefaultStackSynthesizer
の他のすべてのプロパティは、ブートストラップテンプレート内のリソースの名前に関連しています。これらのプロパティについて指定が必要になるのは、ブートストラップテンプレートを変更してリソース名または命名スキームを変更したときのみです。
すべてのプロパティは、特殊なプレースホルダー ${Qualifier}
、${AWS::Partition}
、${AWS::AccountId}
、${AWS::Region}
を受け入れます。これらのプレースホルダーは、 qualifier
パラメータの値と、スタックの環境の AWS パーティション、アカウント ID、および AWS リージョン 値でそれぞれ置き換えられます。
以下の例は、シンセサイザーをインスタンス化する場合と同じ形で、DefaultStackSynthesizer
で最もよく使用されるプロパティとそのデフォルト値を示しています。詳細なリストについては、「」を参照してくださいDefaultStackSynthesizerProps。
new DefaultStackSynthesizer({
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
// ARN of the role assumed by the CLI and Pipeline to deploy here
deployRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-deploy-role-${AWS::AccountId}-${AWS::Region}',
deployRoleExternalId: '',
// ARN of the role used for file asset publishing (assumed from the CLI role)
fileAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-file-publishing-role-${AWS::AccountId}-${AWS::Region}',
fileAssetPublishingExternalId: '',
// ARN of the role used for Docker asset publishing (assumed from the CLI role)
imageAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-image-publishing-role-${AWS::AccountId}-${AWS::Region}',
imageAssetPublishingExternalId: '',
// ARN of the role passed to CloudFormation to execute the deployments
cloudFormationExecutionRole: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-cfn-exec-role-${AWS::AccountId}-${AWS::Region}',
// ARN of the role used to look up context information in an environment
lookupRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-lookup-role-${AWS::AccountId}-${AWS::Region}',
lookupRoleExternalId: '',
// Name of the SSM parameter which describes the bootstrap stack version number
bootstrapStackVersionSsmParameter: '/cdk-bootstrap/${Qualifier}/version',
// Add a rule to every template which verifies the required bootstrap stack version
generateBootstrapVersionRule: true,
})
CliCredentialsStackSynthesizer
を使用する
CDK デプロイ中にアクセス許可を付与するために使用されるセキュリティ認証情報を変更するには、 を使用して合成をカスタマイズできますCliCredentialsStackSynthesizer
。このシンセサイザーは、Amazon S3 バケットや Amazon ECRリポジトリなどのアセットを保存するためにブートストラップ中に作成されるデフォルトの AWS リソースで動作します。ブートストラップCDK中に によって作成されたデフォルトのIAMロールを使用する代わりに、デプロイを開始するアクターのセキュリティ認証情報を使用します。したがって、アクターのセキュリティ認証情報には、すべてのデプロイアクションを実行するための有効なアクセス許可が必要です。以下の図は、このシンセサイザーを使用した場合のデプロイプロセスを示したものです。
CliCredentialsStackSynthesizer
を使用する場合:
-
デフォルトでは、 はアクターのアクセス許可を使用してアカウントでAPI呼び出し CloudFormation を実行します。したがって、現在の ID には、 CloudFormation スタック内の AWS リソースに必要な変更を加えるためのアクセス許可と、
CreateStack
や などの必要な CloudFormation オペレーションを実行するためのアクセス許可が必要ですUpdateStack
。デプロイ機能は、アクターのアクセス許可に制限されます。 -
アセットの公開と CloudFormation デプロイは、現在の IAM ID を使用して行われます。この ID には、アセットバケットとリポジトリに対する読み取りと書き込みの両方の十分なアクセス許可が必要です。
-
ルックアップは現在のIAMアイデンティティを使用して実行され、ルックアップはポリシーの対象となります。
このシンセサイザーを使用する場合、任意の で --role-arn
オプションを使用して指定することで、別の CloudFormation 実行ロールを使用できます。 CDKCLI コマンド。
CliCredentialsStackSynthesizer
のブートストラップ契約
CliCredentialsStackSynthesizer
には、以下のブートストラップ契約が必要です。ブートストラップ時に作成する必要があるリソースは以下のとおりです。
ブートストラップのリソース | 説明 | デフォルトの想定リソース名 | 目的 |
---|---|---|---|
Amazon S3 バケット |
ステージングバケット |
cdk-hnb659fds-assets- |
ファイルアセットを保存します。 |
Amazon ECRリポジトリ |
ステージングリポジトリ |
cdk-hnb659fds-container-assets- |
の保存と管理 Docker イメージアセット。 |
リソース名の中の文字列 hnb659fds
は、修飾子と呼ばれます。デフォルト値に特別な意味はありません。修飾子が異なってさえいれば、1 つの環境内にブートストラップリソースの複数のコピーを持つことができます。複数のコピーを持つことで、同一環境内の異なるアプリケーションのアセットを分離して管理できます。
デフォルトのブートストラップテンプレートをデプロイすることで、CliCredentialsStackSynthesizer
のブートストラップ契約を満たすことができます。デフォルトのブートストラップテンプレートはIAMロールを作成しますが、このシンセサイザーはロールを使用しません。ブートストラップテンプレートをカスタマイズしてIAMロールを削除することもできます。
CliCredentialsStackSynthesizer
の変更
ブートストラップ時に修飾子またはデフォルトのブートストラップリソース名を変更する場合は、同じ名前を使用するようにシンセサイザーを変更する必要があります。シンセサイザーは、1 つのスタックまたはアプリ内のすべてのスタックに対して変更できます。以下に例を示します。
new MyStack(this, 'MyStack', {
synthesizer: new CliCredentialsStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
以下の例は、CliCredentialsStackSynthesizer
で最もよく使用されるプロパティとそのデフォルト値を示しています。詳細なリストについては、「」を参照してくださいCliCredentialsStackSynthesizerProps。
new CliCredentialsStackSynthesizer({
// Value for '${Qualifier}' in the resource names
qualifier: 'hnb659fds',
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
})
LegacyStackSynthesizer
を使用する
は LegacyStackSynthesizer
v1 CDK デプロイの動作をエミュレートします。アクセス許可の確立には、デプロイを実行するアクターのセキュリティ認証情報が使用されます。ファイルアセットは、 という名前の AWS CloudFormation スタックを使用して作成する必要があるバケットにアップロードされますCDKToolkit
。CDK CLI は、 という名前のアンマネージド型 Amazon aws-cdk/assets
ECRリポジトリを作成して保存します。Docker イメージアセット。このリポジトリのクリーンアップおよび管理はユーザーの責任です。を使用して合成されたスタックは、 を使用してのみデプロイLegacyStackSynthesizer
できます。 CDKCLI.
v1 から CDK v2 LegacyStackSynthesizer
に移行していて、環境を再ブートストラップできない場合は、 CDK を使用できます。新しいプロジェクトでは、LegacyStackSynthesizer
を使用しないことをおすすめします。
LegacyStackSynthesizer
のブートストラップ契約
LegacyStackSynthesizer
には、以下のブートストラップ契約が必要です。ブートストラップ時に作成する必要があるリソースは以下のとおりです。
ブートストラップのリソース | 説明 | デフォルトの想定リソース名 | 目的 |
---|---|---|---|
Amazon S3 バケット |
ステージングバケット |
cdk-hnb659fds-assets- |
ファイルアセットを保存します。 |
CloudFormation 出力 |
バケット名出力 |
スタック – 出力名 – |
ステージングバケットの名前を説明する CloudFormation 出力 |
LegacyStackSynthesizer
は、固定名を持つ Amazon S3 バケットが存在することを想定していません。代わりに、合成された CloudFormation テンプレートには、ファイルアセットごとに 3 つの CloudFormation パラメータが含まれます。これらのパラメータは、各ファイルアセットの Amazon S3 バケット名、Amazon S3 オブジェクトキー、アーティファクトハッシュを保存します。
Docker イメージアセットは、 という名前の Amazon ECRリポジトリに公開されますaws-cdk/assets
。この名前はアセットごとに変更できます。リポジトリが存在しない場合、リポジトリが作成されます。
CloudFormation スタックはデフォルト名 で存在する必要がありますCDKToolkit
。このスタックには、 CloudFormationステージングバケットを参照BucketName
する という名前のエクスポートが必要です。
デフォルトのブートストラップテンプレートは、LegacyStackSynthesizer
のブートストラップ契約を満たします。ただし、Amazon S3 バケットは、ブートストラップテンプレートのブートストラップリソースからのみ使用されます。ブートストラップテンプレートをカスタマイズして、Amazon ECR、IAM、および SSMブートストラップリソースを削除できます。
LegacyStackSynthesizer
のデプロイの手順
このシンセサイザーを使用すると、デプロイ時に以下のプロセスが実行されます。
-
CDK CLI は、環境
CDKToolkit
内で という名前の CloudFormation スタックを検索します。このスタックから、 CDKCLI は、 という名前の CloudFormation 出力を読み取りますBucketName
。cdk deploy
で--toolkit-stack-name
オプションを使用することで、別のスタック名を指定できます。 -
デプロイのアクセス許可の確立には、デプロイを開始するアクターのセキュリティ認証情報が使用されます。したがって、アクターはすべてのデプロイアクションを実行するために十分なアクセス許可が必要です。これには、Amazon S3 ステージングバケットの読み取りと書き込み、Amazon ECRリポジトリの作成と書き込み、 AWS CloudFormation デプロイの開始とモニタリング、デプロイに必要なAPI呼び出しの実行が含まれます。
-
必要に応じて、アクセス許可が有効であれば、Amazon S3 ステージングバケットにファイルアセットが発行されます。
-
必要に応じて、またアクセス許可が有効な場合は、Docker イメージアセットは、アセットの
repositoryName
プロパティによって という名前のリポジトリに発行されます。リポジトリ名を指定しない場合、デフォルト値は'aws-cdk/assets'
になります。 -
アクセス許可が有効な場合、 AWS CloudFormation デプロイが実行されます。Amazon S3 ステージングバケットとキーの場所は CloudFormation パラメータとして渡されます。