这是 AWS CDK v2 开发者指南。较旧的 CDK v1 于 2022 年 6 月 1 日进入维护阶段,并于 2023 年 6 月 1 日终止支持。
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
您可以通过修改默认合成器、使用其他可用的内置合成器或创建自己的合成器来自定义 AWS Cloud Development Kit (AWS CDK) 堆栈合成。
AWS CDK 包括以下内置合成器,可用于自定义合成行为:
-
DefaultStackSynthesizer
:如果您未指定合成器,则会自动使用此合成器。它支持跨账户部署和使用 Pipelin CDKes 结构的部署。它的引导程序合同需要一个已知名称的现有 Amazon S3 存储桶、一个已知名称的现有 Amazon ECR 存储库以及五个已知名称的现有IAM角色。默认的引导模板可满足这些要求。 -
CliCredentialsStackSynthesizer
— 该合成器的引导程序合同需要现有的 Amazon S3 存储桶和现有的亚马逊存储库。ECR它不需要任何IAM角色。要执行部署,此合成器依赖于的权限 CDK CLI user and 建议想要限制IAM部署凭证的组织使用。此合成器不支持跨账户部署或流水线。CDK -
LegacyStackSynthesizer
— 该合成器模拟 CDK v1 的合成行为。它的引导程序合同要求使用任意名称的现有 Amazon S3 存储桶,并期望将资产的位置作为 CloudFormation 堆栈参数传入。如果您使用此合成器,则必须使用 CDK CLI 执行部署。
如果这些内置合成器都不适合您的用例,则可以将自己的合成器编写为实现IStackSynthesizer
或查看来自的合成器的类
自定义 DefaultStackSynthesizer
DefaultStackSynthesizer
是 AWS CDK的默认合成器。它旨在允许跨账户部署CDK应用程序,以及从不明确支持但支持常规部署的 CI/CD 系统 CloudFormation 部署CDK应用程序,例如。 AWS CDK AWS CodePipeline此合成器是大多数用例的最佳选择。
DefaultStackSynthesizer
引导合约
DefaultStackSynthesizer
需要以下引导程序合约。这些是在引导过程中必须创建的资源:
引导资源 | 描述 | 默认的预期资源名称 | 用途 |
---|---|---|---|
Amazon S3 存储桶 |
暂存存储桶 |
cdk-hnb659fds-assets-- |
存储文件资产。 |
亚马逊ECR存储库 |
暂存存储库 |
cdk-hnb659--fds-container-assets |
存储和管理 Docker 图像资产。 |
IAM 角色 |
部署角色 |
cdk-hnb659--fds-deploy-role |
由... 假设 CDK CLI 并 CodePipeline 有可能担任其他角色并开始部 AWS CloudFormation 署。 此角色的信任策略控制谁可以在此 AWS 环境 AWS CDK 中使用进行部署。 |
IAM 角色 |
AWS CloudFormation 执行角色 |
cdk-hnb659--fds-cfn-exec-role |
使用此角色 AWS CloudFormation 来执行部署。 此角色的策略控制CDK部署可以执行的操作。 |
IAM 角色 |
查找角色 |
cdk-hnb659--fds-lookup-role |
此角色用于以下情况 CDK CLI 需要执行环境上下文查找。 此角色的信任策略会控制谁可以在环境中查找信息。 |
IAM 角色 |
文件发布角色 |
cdk-hnb659--fds-file-publishing-role |
此角色可用于将资产上传到 Amazon S3 暂存存储桶。它是从部署角色中代入的。 |
IAM 角色 |
映像发布角色 |
cdk-hnb659--fds-image-publishing-role |
此角色用于上传 Docker 将图像存储到 Amazon ECR 暂存存储库。它是从部署角色中代入的。 |
SSM 参数 |
引导版本参数 |
/cdk-bootstrap/hnb659fds/ |
引导模板的版本。它由引导模板和 CDK CLI 以验证需求。 |
自定义CDK堆栈合成的一种方法是修改DefaultStackSynthesizer
. 您可以使用实例的synthesizer
属性为单个CDK堆栈自定义此合成器。Stack
您也可以使用App
实例DefaultStackSynthesizer
的defaultStackSynthesizer
属性修改CDK应用程序中的所有堆栈。
更改限定符
限定符将添加到引导过程中创建的资源的名称中。默认情况下,此值为 hnb659fds
。在引导过程中修改限定符时,需要自定义CDK堆栈合成以使用相同的限定符。
要更改限定符,请在CDK项目文件中配置限定符的qualifier
属性DefaultStackSynthesizer
或将该限定符配置为上下文密钥。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
。此合成器使用在引导过程中创建的默认 AWS 资源来存储资产,例如 Amazon S3 存储桶和 Amazon 存储库。ECR它不使用在引导CDK期间创建的默认IAM角色,而是使用启动部署的参与者的安全证书。因此,角色的安全凭证必须具有有效的权限才能执行所有部署操作。下图说明了使用此合成器时的部署过程:
使用 CliCredentialsStackSynthesizer
时:
-
默认情况下,使用操作者的权限在您的账户中 CloudFormation 执行API呼叫。因此,当前身份必须具有对 CloudFormation 堆栈中的 AWS 资源进行必要更改的权限,以及执行必要 CloudFormation 操作的权限,例如
CreateStack
或UpdateStack
。部署能力将仅限于角色的权限。 -
资产发布和 CloudFormation 部署将使用当前IAM身份完成。此身份必须具有足够的权限才能向资产存储桶和存储库读取和写入数据。
-
使用当前IAM身份执行查找,查询受其策略的约束。
使用此合成器时,你可以使用单独的 CloudFormation 执行角色,方法是使用 any 的--role-arn
选项来指定它 CDK CLI 命令。
CliCredentialsStackSynthesizer
引导合约
CliCredentialsStackSynthesizer
需要以下引导程序合约。这些是在引导过程中必须创建的资源:
引导资源 | 描述 | 默认的预期资源名称 | 用途 |
---|---|---|---|
Amazon S3 存储桶 |
暂存存储桶 |
cdk-hnb659fds-assets-- |
存储文件资产。 |
亚马逊ECR存储库 |
暂存存储库 |
cdk-hnb659--fds-container-assets |
存储和管理 Docker 图像资产。 |
资源名称中的 hnb659fds
字符串称为限定符。它的默认值没有特殊意义。您可以在一个环境中拥有多个引导资源的副本,只要它们有不同的限定符即可。拥有多个副本对于将同一环境中不同应用程序的资产分割开来非常有用。
您可以部署默认引导模板以满足 CliCredentialsStackSynthesizer
的引导合约。默认的引导模板将创建IAM角色,但是这个合成器不会使用它们。您也可以自定义引导模板以删除IAM角色。
修改 CliCredentialsStackSynthesizer
如果您在引导过程中更改了限定符或任何默认的引导资源名称,则必须修改合成器以使用相同的名称。您可以修改应用中单个堆栈或所有堆栈的合成器。以下是示例:
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
模拟 CDK v1 部署的行为。执行部署的角色的安全凭证将用于建立权限。文件资产将上传到必须使用名为的 AWS CloudFormation 堆栈创建的存储桶CDKToolkit
。这些区域有:CDKCLI 将创建一个名aws-cdk/assets
为存储的非托管 Amazon ECR 存储库 Docker 图像资产。您将负责清理和管理此存储库。使用合成的堆栈LegacyStackSynthesizer
只能使用部署 CDK CLI.
LegacyStackSynthesizer
如果您要从 CDK v1 迁移到 CDK v2,并且无法重新启动您的环境,则可以使用。对于新项目,我们不建议使用 LegacyStackSynthesizer
。
LegacyStackSynthesizer
引导合约
LegacyStackSynthesizer
需要以下引导程序合约。这些是在引导过程中必须创建的资源:
引导资源 | 描述 | 默认的预期资源名称 | 用途 |
---|---|---|---|
Amazon S3 存储桶 |
暂存存储桶 |
cdk-hnb659fds-assets-- |
存储文件资产。 |
CloudFormation 输出 |
存储桶名称输出 |
堆栈: 输出名称: |
描述暂存存储桶名称的 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
。您可以使用cdk deploy
的--toolkit-stack-name
选项指定不同的堆栈名称。 -
启动部署的角色的安全凭证将用于为部署建立权限。因此,角色必须具有足够的权限才能执行所有部署操作。这包括读取和写入 Amazon S3 暂存存储桶、创建和写入 Amazon ECR 存储库、启动和监控 AWS CloudFormation 部署以及执行部署所需的任何API调用。
-
如有必要,如果权限有效,则文件资产将发布到 Amazon S3 暂存存储桶。
-
如有必要,如果权限有效,Docker 图像资源将发布到以该资产的
repositoryName
属性命名的存储库中。如果您不提供存储库名称,则默认值为'aws-cdk/assets'
。 -
如果权限有效,则执行 AWS CloudFormation 部署。Amazon S3 暂存存储桶和密钥的位置作为 CloudFormation 参数传递。