設定和自訂CDK堆疊合成 - AWS Cloud Development Kit (AWS CDK) V2
設定CDK堆疊合成合成堆疊 CDK自訂CDK堆疊合成

這是 AWS CDK v2 開發人員指南。較舊的 CDK V1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定和自訂CDK堆疊合成

您必須先合成 AWS Cloud Development Kit (AWS CDK) 堆疊，才能部署堆疊。堆棧合成是從CDK堆棧生成 AWS CloudFormation 模板和部署工件的過程。範本和人工因素稱為雲端組合。雲端組件是部署來佈建您的資源 AWS。如需部署如何運作的詳細資訊，請參閱AWS CDK 部署的運作方式。

為了使您的CDK應用程序正確部署，在合成過程中生成的 CloudFormation 模板必須正確指定在引導過程中創建的資源。因此，引導和合成必須相互補充，部署才能成功：

  • 啟動安裝是設定部署 AWS 環境的一次性程序。 AWS CDK 它會設定環境中用於部署的特定 AWS 資源。CDK這些通常稱為引導資源。如需有關啟動載入的指示，請參閱。引導您的環境以與 AWS CDK

  • CloudFormation 在合成過程中生成的模板包括有關要使用的引導資源的信息。在合成過程中，CDKCLI不知道具體如何您的 AWS 環境已啟動載入。相反地，會根據您為每個CDK堆疊配置的合成器CDKCLI產生 CloudFormation 範本。若要成功部署，合成器必須產生參考正確啟動程序資源的 CloudFormation 範本以便使用。

配CDK備了默認合成器和引導配置，旨在協同工作。如果您自訂一個，則必須將相關自訂套用至另一個自訂。

設定CDK堆疊合成

您可以使用Stack執行個體的synthesizer屬性來設定CDK堆疊合成。此屬性指定您的CDK堆棧將如何合成。您提供實作或之類別的執行個IStackSynthesizer體IReusableStackSynthesizer。它的方法將被調用每一個資產被添加到堆棧或當堆棧被合成時。以下是在堆棧中使用此屬性的基本示例：

TypeScript
new MyStack(this, 'MyStack', {
  // stack properties
  synthesizer: new DefaultStackSynthesizer({
    // synthesizer properties
  }),
});
JavaScript
new MyStack(this, 'MyStack', {
  // stack properties
  synthesizer: new DefaultStackSynthesizer({
    // synthesizer properties
  }),
});
Python
MyStack(self, "MyStack",
    # stack properties
    synthesizer=DefaultStackSynthesizer(
        # synthesizer properties
))
Java

new MyStack(app, "MyStack", StackProps.builder()
  // stack properties
  .synthesizer(DefaultStackSynthesizer.Builder.create()
    // synthesizer properties
    .build())
  .build();
C#
new MyStack(app, "MyStack", new StackProps
// stack properties
{
    Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps
    {
        // synthesizer properties
    })
});
Go
func main() {
  app := awscdk.NewApp(nil)

  NewMyStack(app, "MyStack", &MyStackProps{
    StackProps: awscdk.StackProps{
      Synthesizer: awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{
        // synthesizer properties
      }),
    },
  })

  app.Synth(nil)
}

您還可以使用實例的defaultStackSynthesizer屬性為CDK應用程序中的所有CDK堆棧配置合成App器：

TypeScript

import { App, Stack, DefaultStackSynthesizer } from 'aws-cdk-lib';

const app = new App({
  // Configure for all stacks in this app
  defaultStackSynthesizer: new DefaultStackSynthesizer({
    /* ... */
  }),
});
JavaScript

const { App, Stack, DefaultStackSynthesizer } = require('aws-cdk-lib');

const app = new App({
  // Configure for all stacks in this app
  defaultStackSynthesizer: new DefaultStackSynthesizer({
    /* ... */
  }),
});
Python

from aws_cdk import App, Stack, DefaultStackSynthesizer

app = App(
    default_stack_synthesizer=DefaultStackSynthesizer(
        # Configure for all stacks in this app
        # ...
    )
)
Java

import software.amazon.awscdk.App;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.DefaultStackSynthesizer;

public class Main {
    public static void main(final String[] args) {
        App app = new App(AppProps.builder()
            // Configure for all stacks in this app
            .defaultStackSynthesizer(DefaultStackSynthesizer.Builder.create().build())
            .build()
        );
    }
}
C#

using Amazon.CDK;
using Amazon.CDK.Synthesizers;

namespace MyNamespace
{
    sealed class Program
    {
        public static void Main(string[] args)
        {
            var app = new App(new AppProps
            {
                // Configure for all stacks in this app
                DefaultStackSynthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps
                {
                    // ...
                })
            });
        }
    }
}
Go

package main

import (
    "github.com/aws/aws-cdk-go/awscdk/v2"
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
)

func main() {
    defer jsii.Close()
    
    app := awscdk.NewApp(&awscdk.AppProps{
        // Configure for all stacks in this app
        DefaultStackSynthesizer: awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{
            // ...
        }),
    })
}

默認情況下， AWS CDK 用途DefaultStackSynthesizer。如果您未配置合成器，將使用此合成器。

如果您不修改啟動載入 (例如對啟動程序堆疊或範本進行變更)，則不必修改堆疊合成。您甚至不需要提供合成器。CDK將使用預設DefaultStackSynthesizer類別來設定CDK堆疊合成，以便與您的引導程式堆疊正確互動。

合成堆疊 CDK

若要合成CDK堆疊，請使用指 AWS CDK 令行介面 (AWS CDK CLI) cdk synth 指令。若要取得有關此指令的更多資訊，包括可與此指令搭配使用的選項，請參閱〈〉cdk synthesize。

如果您的CDK應用程序包含單個堆棧，或者要合成所有堆棧，則不必提供CDK堆棧名稱作為參數。默認情況下，CDKCLI將您的CDK堆棧合成為 AWS CloudFormation 模板。每個堆疊的json格式化範本會儲存到目cdk.out錄中。如果您的應用程序包含單個堆棧，則會將yaml格式化的模板打印到stdout。以下是範例：

$ cdk synth
Resources:
  CDKMetadata:
    Type: AWS::CDK::Metadata
    Properties:
      Analytics: v2:deflate64:H4sIAAAAAAAA/unique-identifier
    Metadata:
      aws:cdk:path: CdkAppStack/CDKMetadata/Default
    Condition: CDKMetadataAvailable
    ...

如果您的CDK應用程序包含多個堆棧，則可以提供堆棧的邏輯 ID 以合成單個堆棧。以下是範例：

$ cdk synth MyStackName

如果您不合成堆棧並運行cdk deploy，則在部署之前CDKCLI將自動合成堆棧。

自訂CDK堆疊合成

AWS CDK 包括以下內置合成器，可用於自定義合成行為：

  • DefaultStackSynthesizer— 如果您沒有指定合成器，則會自動使用此合成器。它支援使用CDK管道建構的跨帳戶部署和部署。其啟動程序合約需要具有已知名稱的現有 Amazon S3 儲存貯體、具有已知名稱的現有 Amazon ECR 儲存庫，以及五個具有已知名稱的現有IAM角色。預設的啟動載入範本符合這些需求。

  • CliCredentialsStackSynthesizer— 此合成器的啟動程序合約需要現有的 Amazon S3 儲存貯體和現有的 Amazon ECR 儲存庫。它不需要任何IAM角色。若要執行部署，此合成器依賴CDKCLI使用者的權限，建議您用於想要限制IAM部署認證的組織。此合成器不支援跨帳戶部署或CDK管道。

  • LegacyStackSynthesizer— 該合成器模擬 CDK v1 合成行為。其啟動程序合約需要任意名稱的現有 Amazon S3 儲存貯體，並預期資產的位置作為 CloudFormation 堆疊參數傳入。如果您使用此合成器，則必須使用CDKCLI來執行部署。

如果這些內置合成器都不適合您的用例，則可以將自己的合成器編寫為實現IStackSynthesizer或查看. Construct Hub

自訂 DefaultStackSynthesizer

DefaultStackSynthesizer是的預設合成器 AWS CDK。它的設計目的是允許跨帳戶部署CDK應用程式，以及從 CI/CD 系統部署CDK應用程式，該系統不具有明確支援 AWS CDK，但支援一般 CloudFormation 部署，例如. AWS CodePipeline該合成器是大多數用例的最佳選擇。

DefaultStackSynthesizer引導合同

DefaultStackSynthesizer需要以下引導合同。這些是引導過程中必須創建的資源：

引導資源 描述 預設預期的資源名稱 用途

Amazon S3 儲存貯體

分期桶

CDK-HNB659F-資產-ACCOUNT-REGION

儲存檔案資產。

Amazon ECR 倉庫

暫存儲庫

CDK-HNB659-fds-container-assetsACCOUNT-REGION

儲存和管理Docker影像資產。

IAM角色

部署角色

CDK-HNB659-fds-deploy-roleACCOUNT-REGION

假設CDKCLI並可能 CodePipeline 承擔其他角色並開始部 AWS CloudFormation 署。

此角色的信任原則控制誰可以 AWS CDK 在此 AWS 環境中部署。

IAM角色

AWS CloudFormation 執行角色

CDK-HNB659-fds-cfn-exec-roleACCOUNT-REGION

此角色用 AWS CloudFormation 於執行部署。

此角色的原則控制CDK部署可執行的作業。

IAM角色

查閱角色

CDK-HNB659-fds-lookup-roleACCOUNT-REGION

當CDKCLI需要執行環境前後關聯查詢時，會使用此角色。

此角色的信任原則控制誰可以查詢環境中的資訊。

IAM角色

檔案發佈角色

CDK-HNB659-fds-file-publishing-roleACCOUNT-REGION

此角色用於將資產上傳到 Amazon S3 暫存貯體。它是從部署角色假定的。

IAM角色

影像發佈角色

CDK-HNB659-fds-image-publishing-roleACCOUNT-REGION

此角色用於將Docker映像上傳到 Amazon ECR 預備存放庫。它是從部署角色假定的。

SSM參數

引導版本參數

/CD-啟動程序/hnb659fds/version

啟動程序範本的版本。它是由引導模板和驗證CDKCLI需求使用。

自訂CDK堆疊合成的一種方法是修改DefaultStackSynthesizer. 您可以使用執行個體的synthesizer屬性，為單一CDK堆疊自訂此合成Stack器。您也可以使用App實例的defaultStackSynthesizer屬性修改DefaultStackSynthesizerCDK應用程序中的所有堆棧。

變更限定詞

限定詞會新增至啟動載入期間建立的資源名稱。根據預設，此值為 hnb659fds。當您在啟動載入期間修改限定詞時，您需要自訂CDK堆疊合成以使用相同的限定詞。

若要變更限定詞，請在CDK專cdk.json案檔案中配置限定詞的內容，DefaultStackSynthesizer或將限定詞設定為內容索引鍵。qualifier

以下是配置qualifier屬性的範例DefaultStackSynthesizer：

TypeScript
new MyStack(this, 'MyStack', {
  synthesizer: new DefaultStackSynthesizer({
    qualifier: 'MYQUALIFIER',
  }),
});
JavaScript
new MyStack(this, 'MyStack', {
  synthesizer: new DefaultStackSynthesizer({
    qualifier: 'MYQUALIFIER',
  }),
})
Python
MyStack(self, "MyStack",
    synthesizer=DefaultStackSynthesizer(
        qualifier="MYQUALIFIER"
))
Java
new MyStack(app, "MyStack", StackProps.builder()
  .synthesizer(DefaultStackSynthesizer.Builder.create()
    .qualifier("MYQUALIFIER")
    .build())
  .build();
C#
new MyStack(app, "MyStack", new StackProps
{
    Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps
    {
        Qualifier = "MYQUALIFIER"
    })
});
Go
func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack {
	var sprops awscdk.StackProps
	if props != nil {
		sprops = props.StackProps
	}
	stack := awscdk.NewStack(scope, &id, &sprops)

	synth := awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{
		Qualifier: jsii.String("MYQUALIFIER"),
	})

	stack.SetSynthesizer(synth)

	return stack
}

以下是在中將限定詞配置為上下文鍵的示例cdk.json：

{
  "app": "...",
  "context": {
    "@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER"
  }
}

變更資源名稱

所有其他DefaultStackSynthesizer屬性都與引導模板中的資源的名稱有關。只有在修改啟動程序範本並變更資源名稱或命名配置時，才需要提供這些屬性中的任何一個。

所有屬性都接受特殊的預留位置${Qualifier}${AWS::Partition}、${AWS::AccountId}、和${AWS::Region}。這些預留位置會分別取代為qualifier參數值，以及堆疊環境的分 AWS 割區、帳戶 ID 和 AWS 區域 值。

下列範例會顯示最常用的屬性DefaultStackSynthesizer及其預設值，就像您正在實體化合成器一樣。如需完整清單，請參閱 DefaultStackSynthesizerProps：

TypeScript
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,

})
JavaScript
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,
})
Python
DefaultStackSynthesizer(
  # Name of the S3 bucket for file assets
  file_assets_bucket_name="cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}",
  bucket_prefix="",

  # Name of the ECR repository for Docker image assets
  image_assets_repository_name="cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}",
  docker_tag_prefix="",

  # ARN of the role assumed by the CLI and Pipeline to deploy here
  deploy_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-deploy-role-${AWS::AccountId}-${AWS::Region}",
  deploy_role_external_id="",

  # ARN of the role used for file asset publishing (assumed from the CLI role)
  file_asset_publishing_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-file-publishing-role-${AWS::AccountId}-${AWS::Region}",
  file_asset_publishing_external_id="",

  # ARN of the role used for Docker asset publishing (assumed from the CLI role)
  image_asset_publishing_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-image-publishing-role-${AWS::AccountId}-${AWS::Region}",
  image_asset_publishing_external_id="",

  # ARN of the role passed to CloudFormation to execute the deployments
  cloud_formation_execution_role="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
  lookup_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-lookup-role-${AWS::AccountId}-${AWS::Region}",
  lookup_role_external_id="",

  # Name of the SSM parameter which describes the bootstrap stack version number
  bootstrap_stack_version_ssm_parameter="/cdk-bootstrap/${Qualifier}/version",

  # Add a rule to every template which verifies the required bootstrap stack version
  generate_bootstrap_version_rule=True,
)
Java
DefaultStackSynthesizer.Builder.create()
  // 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}")

  .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)
.build()
C#
new DefaultStackSynthesizer(new DefaultStackSynthesizerProps
{
    // 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}",

    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。此合成器可與啟動載入期間建立的預設 AWS 資源搭配使用，以存放資產，例如 Amazon S3 儲存貯體和 Amazon ECR 儲存庫。它不會使用在啟動載入CDK期間建立的預設IAM角色，而是使用起始部署之 Actor 的安全性認證。因此，Actor 的安全性認證必須具有執行所有部署動作的有效權限。下圖說明使用此合成器時的部署程序：

預設 AWS CDK 部署程序的流程圖。

使用時CliCredentialsStackSynthesizer：

  • 根據預設， CloudFormation 會使用 actor 的權限在您的帳戶中執行API呼叫。因此，目前的身分識別必須具有對 CloudFormation 堆疊中的 AWS 資源進行必要變更的權限，以及執行必要 CloudFormation 作業的權限，例如CreateStack或UpdateStack。部署功能將限制為演員的權限。

  • 將使用目前的IAM身分識別來完成資產發佈和 CloudFormation 部署。此身份必須具有足夠的權限，以讀取和寫入資產存儲桶和存儲庫。

  • 查詢是使用目前的IAM身分識別來執行，而查閱則受其原則限制。

使用此合成器時，您可以透過搭配任何指CDKCLI令使用--role-arn選項來指定單獨的 CloudFormation 執行角色。

CliCredentialsStackSynthesizer引導合同

CliCredentialsStackSynthesizer需要以下引導合同。這些是引導過程中必須創建的資源：

引導資源 描述 預設預期的資源名稱 用途

Amazon S3 儲存貯體

分期桶

CDK-HNB659F-資產-ACCOUNT-REGION

儲存檔案資產。

Amazon ECR 倉庫

暫存儲庫

CDK-HNB659-fds-container-assetsACCOUNT-REGION

儲存和管理Docker影像資產。

資源名稱hnb659fds中的字串稱為限定詞。它的默認值沒有特殊意義。只要它們具有不同的限定詞，您就可以在單一環境中擁有多個啟動程序資源副本。擁有多個副本對於在相同環境中保持不同應用程式的資產分開非常有用。

您可以部署默認引導模板以滿足CliCredentialsStackSynthesizer的引導程序合同。默認的引導模板將創建IAM角色，但是該合成器不會使用它們。您也可以自訂啟動程序範本以移除IAM角色。

修改 CliCredentialsStackSynthesizer

如果您在啟動載入期間變更限定詞或任何預設啟動程序資源名稱，則必須修改合成器以使用相同的名稱。您可以為單個堆疊或應用程式中的所有堆疊修改合成器。以下是範例：

TypeScript
new MyStack(this, 'MyStack', {
  synthesizer: new CliCredentialsStackSynthesizer({
    qualifier: 'MYQUALIFIER',
  }),
});
JavaScript
new MyStack(this, 'MyStack', {
  synthesizer: new CliCredentialsStackSynthesizer({
    qualifier: 'MYQUALIFIER',
  }),
})
Python
MyStack(self, "MyStack",
    synthesizer=CliCredentialsStackSynthesizer(
        qualifier="MYQUALIFIER"
))
Java
new MyStack(app, "MyStack", StackProps.builder()
  .synthesizer(CliCredentialsStackSynthesizer.Builder.create()
    .qualifier("MYQUALIFIER")
    .build())
  .build();
C#
new MyStack(app, "MyStack", new StackProps
{
    Synthesizer = new CliCredentialsStackSynthesizer(new CliCredentialsStackSynthesizerProps
    {
        Qualifier = "MYQUALIFIER"
    })
});

下面的例子顯示了最常用的屬性CliCredentialsStackSynthesizer及其默認值一起。如需完整清單，請參閱 CliCredentialsStackSynthesizerProps：

TypeScript
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: '',
})
JavaScript
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: '',
})
Python
CliCredentialsStackSynthesizer(
  # Value for '${Qualifier}' in the resource names
  qualifier="hnb659fds",
  
  # Name of the S3 bucket for file assets
  file_assets_bucket_name="cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}",
  bucket_prefix="",

  # Name of the ECR repository for Docker image assets
  image_assets_repository_name="cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}",
  docker_tag_prefix="",
)
Java
CliCredentialsStackSynthesizer.Builder.create()
  // 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('')
.build()
C#
new CliCredentialsStackSynthesizer(new CliCredentialsStackSynthesizerProps
{

    // 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模擬 CDK v1 部署的行為。執行部署之參與者的安全性認證將用於建立權限。檔案資產將上傳至必須使用名為的 AWS CloudFormation 堆疊建立的值區CDKToolkit。CDKCLI將創建一個名為ECRaws-cdk/assets存儲Docker圖像資產的非託管 Amazon 存儲庫。您將負責清理和管理此存儲庫。使用合成的堆疊只LegacyStackSynthesizer能使用 CDKCLI.

LegacyStackSynthesizer如果您要從 CDK v1 遷移到 CDK v2，並且無法重新啟動您的環境，則可以使用。對於新專案，我們建議您不要使用LegacyStackSynthesizer。

LegacyStackSynthesizer引導合同

LegacyStackSynthesizer需要以下引導合同。這些是引導過程中必須創建的資源：

引導資源 描述 預設預期的資源名稱 用途

Amazon S3 儲存貯體

分期桶

CDK-HNB659F-資產-ACCOUNT-REGION

儲存檔案資產。

CloudFormation 輸出

值區名稱輸出

堆疊 — CDKToolkit

輸出名稱 — BucketName

描述暫存貯體名稱的 CloudFormation 輸出

LegacyStackSynthesizer不會假設存在具有固定名稱的 Amazon S3 儲存貯體。而是，合成的 CloudFormation 範本會針對每個檔案資產包含三個 CloudFormation 參數。這些參數將存放每個檔案資產的 Amazon S3 儲存貯體名稱、Amazon S3 物件金鑰和成品雜湊。

Docker影像資產將發佈到名為的 Amazon ECR 儲存庫aws-cdk/assets。每個資產都可以變更此名稱。如果存儲庫不存在，則將創建它們。

CloudFormation 堆疊必須以預設名稱存在CDKToolkit。此堆疊必須具有名為的 CloudFormation匯出BucketName，該匯出參照暫存貯體。

默認的引導模板滿足LegacyStackSynthesizer引導合同。不過，只會使用啟動程序範本的啟動程序資源中的 Amazon S3 儲存貯體。您可以自訂啟動程序範本以移除 Amazon ECR IAM、和SSM啟動程序資源。

LegacyStackSynthesizer部署程序

使用此合成器時，會在部署期間執行下列程序：

  • 會CDKCLI尋找CDKToolkit在您的環境中命名的 CloudFormation 堆疊。從這個堆棧中，CDKCLI讀取名為的 CloudFormation 輸出BucketName。您可以使用與--toolkit-stack-name選項cdk deploy來指定不同的堆疊名稱。

  • 啟動部署之參與者的安全性認證將用於建立部署權限。因此，演員必須具有足夠的權限才能執行所有部署動作。這包括讀取和寫入 Amazon S3 暫存貯體、建立和寫入 Amazon ECR 儲存庫、啟動和監控 AWS CloudFormation 部署，以及執行部署所需的任何API呼叫。

  • 如有必要，且許可有效時，檔案資產將發佈到 Amazon S3 暫存貯體。

  • 如有必要，且權限有效時，Docker影像資產會發佈至由資產repositoryName屬性命名的儲存庫。'aws-cdk/assets'如果您未提供存放庫名稱，則預設值為。

  • 如果權限有效，則會執行 AWS CloudFormation 部署。Amazon S3 暫存貯體和金鑰的位置會作為 CloudFormation 參數傳遞。