自定义 AWS CDK 引导 - AWS Cloud Development Kit (AWS CDK) v2
使用 CDK 自定义CLI引导修改默认的引导模板引导程序模板合约

这是 AWS CDK v2 开发者指南。较旧的 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

自定义 AWS CDK 引导

您可以使用 AWS CDK 命令行界面 (AWS CDK CLI) 或修改和部署 AWS Cloud Development Kit (AWS CDK) 引导模板来自定义 AWS CloudFormation 引导。

有关引导的简介，请参阅。正在引导

使用 CDK 自定义CLI引导

以下是一些示例，说明如何使用 CDK 自定义引导。CLI有关全部 cdk bootstrap 选项的列表，请参阅 cdk bootstrap。

替换 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。

要提供多个策略，请向它们传递一个以逗号分隔的单个字符串：

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

为避免部署失败，请确保您指定的策略足以满足您将在引导环境中执行的任何部署。

更改添加到引导堆栈中资源名称的限定符

默认情况下，hnb659fds限定符会添加到引导堆栈中资源的物理 ID 中。要更改此值，请使用--qualifier选项。

在同一环境中配置多个引导堆栈以避免名称冲突时，此修改非常有用。

更改限定符是为了在 CDK 本身的自动测试之间进行名称隔离。除非您可以非常精确地缩小分配给 CloudFormation 执行角色的 IAM 权限，否则在单个账户中拥有两个不同的引导堆栈不会带来权限隔离的好处。因此，通常无需更改此值。

更改限定符时，您的 CDK 应用程序必须将更改后的值传递给堆栈合成器。有关更多信息，请参阅 自定义 CDK 堆栈合成。

向引导堆栈添加标签

使用格式为的--tags选项将 CloudFormation 标签KEY=VALUE添加到您的引导程序堆栈。

指定 AWS 账户 可以部署到正在引导的环境中的其他内容

使用该--trust选项提供允许部署到正在引导的环境中的其他 AWS 账户 内容。默认情况下，执行引导的帐户将始终受到信任。

当您引导Pipeline来自其他环境的 CDK 将部署到的环境时，此选项非常有用。

使用此选项时，还必须提供--cloudformation-execution-policies。

要将可信帐户添加到现有的引导程序堆栈，必须指定所有要信任的帐户，包括您之前可能提供的帐户。如果您只提供新的可信账户，则以前信任的账户将被删除。

以下是信任两个账户的示例：

$ 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 控制台进行验证。

启用终止保护

  1. 运行以下命令以在新的或现有的引导堆栈上启用终止保护：

    $ cdk bootstrap --termination-protection

  2. 使用 AWS CLI 或 CloudFormation 控制台进行验证。以下是一个使用 AWS CLI的示例。如果您修改了引导程序堆栈名称，请将其CDKToolkit替换为堆栈名称：

    $ aws cloudformation describe-stacks --stack-name CDKToolkit --query "Stacks[0].EnableTerminationProtection"
true

修改默认的引导模板

当您需要的自定义功能超出 CDK 所CLI能提供的范围时，可以根据需要修改引导程序模板。然后，部署模板以引导您的环境。

修改和部署默认引导模板

  1. 使用--show-template选项获取默认的引导模板。默认情况下，CDK CLI 将在您的终端窗口中输出模板。您可以修改 CDK CLI 命令以将模板保存到本地计算机。以下是 示例：

    $ cdk bootstrap --show-template > my-bootstrap-template.yaml

  2. 根据需要修改引导模板。您所做的任何更改都应遵守引导模板合同。有关引导模板合同的更多信息，请参阅。遵循引导程序模板合同

    要确保您的自定义设置不会在以后被cdk bootstrap使用默认模板运行的用户意外覆盖，请更改模板参数的BootstrapVariant默认值。CDK CLI 只允许使用与当前部署的模板相同BootstrapVariant且版本相同或更高的模板覆盖引导堆栈。

  3. 使用您的首选 AWS CloudFormation 部署方法部署修改后的模板。以下是使用 CDK CLI 的示例：

    $ cdk bootstrap --template my-bootstrap-template.yaml

遵循引导程序模板合同

自定义 bootstrapping 时，可能需要自定义堆栈合成行为。这样可以确保您的合成 CloudFormation 模板与您的引导程序堆栈保持兼容。有关更多信息，请参阅 自定义 CDK 堆栈合成。

自定义堆栈合成的最简单方法是修改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需要五个 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 的参数传递到堆栈。

输出

CDK CLI 要求引导堆栈上存在以下 CloudFormation 输出：

  • BucketName— 文件资产存储桶的名称。

  • BucketDomainName— 域名格式的文件资产存储桶。

  • BootstrapVersion— 引导堆栈的当前版本。

模板历史记录

bootstrap模板是版本化的，并且会随着时间的推移而自行演变。 AWS CDK 如果您提供自己的引导程序模板，请使用规范的默认模板使其保持最新状态。您要确保您的模板能够继续使用所有 CDK 功能。有关更多信息，请参阅 Bootstrap 模板版本历史记录。