引导您的环境以便与 CDK 一起使用 AWS - AWS Cloud Development Kit (AWS CDK) v2
如何引导环境何时引导环境在引导期间创建的默认资源引导环境时要使用的权限自定义引导使用 CDK 管线进行引导引导模板版本历史记录

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

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

引导您的环境以便与 CDK 一起使用 AWS

引导您的 AWS 环境，为 AWS 云开发套件 (AWS CDK) 堆栈部署做好准备。

如何引导环境

您可以使用 AWS CDK 命令行界面 (AWS CDK CLI) 或您的首选 AWS CloudFormation 部署工具来引导您的环境。

使用 CDK CLI

您可以使用 CDK CLI cdk bootstrap 命令来引导环境。如果您不需要对引导进行重大修改，我们建议您使用此方法。

从任何工作目录引导

要从任何工作目录引导，请提供用于引导的环境作为命令行参数。以下是示例：

$ cdk bootstrap <aws://123456789012/us-east-1>
提示

如果您没有 AWS 账号，可以从 AWS 管理控制台中获取。您也可以使用以下 AWS CLI 命令来显示您的默认账户信息，包括您的账号：

$ aws sts get-caller-identity

如果您在 AWS config和credentials文件中命名了个人资料，请使用该--profile选项来检索特定个人资料的帐户信息。以下是示例：

$ aws sts get-caller-identity --profile <prod>

要显示默认区域，请使用 aws configure get 命令：

$ aws configure get region
$ aws configure get region --profile <prod>

提供参数时，aws:// 前缀是可选的。以下参数有效：

$ cdk bootstrap <123456789012/us-east-1>

要同时引导多个环境，请提供多个参数：

$ cdk bootstrap <aws://123456789012/us-east-1> <aws://123456789012/us-east-2>
从 CDK 项目的父目录中引导

您可以从包含 cdk.json 文件的 CDK 项目的父目录运行 cdk bootstrap。如果您不提供环境作为参数，则 CDK CLI 将从默认源（例如 config 和 credentials 文件）获取环境信息或为 CDK 堆栈指定的任何环境信息。

从 CDK 项目的父目录引导时，通过命令行参数提供的环境优先于其他源。

要引导在 config 和 credentials 文件中指定的环境，请使用 --profile 选项：

$ cdk bootstrap --profile <prod>

有关 cdk bootstrap 命令和支持的选项的更多信息，请参阅 cdk bootstrap。

使用任何 AWS CloudFormation 工具

您可以从aws-cdk-cli GitHub 存储库中复制引导模板或使用cdk bootstrap --show-template命令获取模板。然后，使用任何 AWS CloudFormation 工具将模板部署到您的环境中。

通过这种方法，你可以使用 AWS CloudFormation StackSets 或 Cont AWS rol Tower。您也可以使用 AWS CloudFormation 控制台或 AWS 命令行界面 (AWS CLI)。在部署模板之前，您可以对其进行修改。这种方法可能更灵活，适合大规模部署。

以下是使用 --show-template 选项检索引导模板并将其保存到本地计算机的示例：

例
macOS/Linux
$ cdk bootstrap --show-template > bootstrap-template.yaml
Windows

在 Windows 上， PowerShell 必须使用它来保留模板的编码。

powershell "cdk bootstrap --show-template | Out-File -encoding utf8 bootstrap-template.yaml"
注意

如果 AWS CloudFormation 模板输出中出现 CDK 通知，请在命令中提供该--no-notices选项。

要使用 CDK CLI 部署此模板，可以运行以下命令：

$ cdk bootstrap --template <bootstrap-template.yaml>

以下是使用 AWS CLI 部署模板的示例：

例
macOS/Linux
aws cloudformation create-stack \
  --stack-name CDKToolkit \
  --template-body file://<path/to/>bootstrap-template.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <us-west-1>
Windows
aws cloudformation create-stack ^
  --stack-name CDKToolkit ^
  --template-body file://<path/to/>bootstrap-template.yaml ^
  --capabilities CAPABILITY_NAMED_IAM ^
  --region <us-west-1>

有关使用引导多个环境的信息 CloudFormation StackSets ，请参阅 C AWS loud Operations & M igrations 博客 CloudFormation StackSets中的使用引导 AWS CDK 的多个 AWS 帐户。

何时引导环境

在部署到 AWS 环境之前，必须引导每个环境。我们建议您主动引导计划使用的每个环境。您可以在计划将 CDK 应用程序实际部署到环境中之前执行此操作。通过主动引导环境，可以防止未来可能出现的问题，例如 Amazon S3 存储桶名称冲突或将 CDK 应用程序部署到尚未引导的环境中。

可以多次引导一个环境。如果已经引导过环境，则将在必要时升级引导堆栈。否则，什么也不会发生。

如果您尝试将 CDK 堆栈部署到尚未引导的环境中，则会看到如下错误：

$ cdk deploy

✨  Synthesis time: 2.02s

 ❌ Deployment failed: Error: BootstrapExampleStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
更新你的引导程序堆栈

CDK 团队会定期将引导模板更新到新版本。发生这种情况时，我们建议您更新引导堆栈。如果您尚未自定义引导过程，则可以按照最初引导环境时所执行的相同步骤来更新引导堆栈。有关更多信息，请参阅引导模板版本历史记录。

在引导期间创建的默认资源

在引导期间创建的 IAM 角色

默认情况下，引导会在您的环境中配置以下 AWS 身份和访问管理 (IAM) 角色：

  • CloudFormationExecutionRole

  • DeploymentActionRole

  • FilePublishingRole

  • ImagePublishingRole

  • LookupRole

CloudFormationExecutionRole

此 IAM 角色是一个 CloudFormation 服务角色，用于授予代表您执行堆栈部署的 CloudFormation 权限。此角色授予在您的账户中执行 AWS API 调用的 CloudFormation 权限，包括部署堆栈。

通过使用服务角色，为该服务角色配置的权限决定了可以对您的 CloudFormation 资源执行哪些操作。如果没有此服务角色，则您在 CDK CLI 中提供的安全证书将决定允许执行的操作。 CloudFormation

DeploymentActionRole

此 IAM 角色授予在您的环境中执行部署的权限。此角色由 CDK CLI 在部署期间代入。

通过使用角色进行部署，您可以执行跨账户部署，因为该角色可以由不同账户中的 AWS 身份担任。

FilePublishingRole

此 IAM 角色授予对引导的 Amazon Simple Storage Service（Amazon S3）存储桶执行操作的权限，包括上传和删除资产。此角色由 CDK CLI 在部署期间代入。

ImagePublishingRole

此 IAM 角色授予对引导的 Amazon Elastic Container Registry（Amazon ECR）存储库执行操作的权限。此角色由 CDK CLI 在部署期间代入。

LookupRole

此 IAM 角色readOnly授予从 AWS 环境中查找上下文值的权限。此角色由 CDK CLI 在执行模板合成和部署等任务时代入。

在引导过程中 IDs 创建的资源

部署默认引导模板时，将使用以下结构创建 IDs 用于引导的物理资源：。cdk-<qualifier>-<description>-<account-ID>-<Region>

  • 限定符：九个字符的唯一字符串值 hnb659fds。实际值没有意义。

  • 描述：资源的简短描述。例如 container-assets。

  • 账户 ID-环境的 AWS 账户 ID。

  • 区域-环境 AWS 区域。

以下是在引导期间创建的 Amazon S3 暂存存储桶的物理 ID 示例：cdk-hnb659fds-assets-012345678910-us-west-1。

引导环境时要使用的权限

引导 AWS 环境时，执行引导的 IAM 身份必须至少具有以下权限：

{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:*",
                "ecr:*",
                "ssm:*",
                "s3:*",
                "iam:*"
            ],
            "Resource": "*"
        }
    ]
}

随着时间的推移，引导堆栈（包括创建的资源及其所需的权限）可能会更改。对于未来的更改，您可能需要修改引导环境所需的权限。

自定义引导

如果默认引导模板不符合您的需求，则可以通过以下方式自定义如何将资源引导到您的环境中：

  • 将命令行选项与 cdk bootstrap 命令结合使用：此方法最适合进行命令行选项支持的细微、特定更改。

  • 修改默认引导模板并进行部署：此方法最适合进行复杂的更改，或者如果您想完全控制引导期间预置的资源的配置，也适合使用此方法。

有关自定义引导的更多信息，请参阅自定义 AWS CDK 引导。

使用 CDK 管线进行引导

如果您使用 CDK 管线部署到其他账户的环境中，并且收到如下消息：

Policy contains a statement with one or more invalid principals

此错误消息表示其他环境中不存在相应的 IAM 角色。最可能的原因是尚未引导环境。引导环境并重试。

保护您的引导堆栈不被删除

如果删除了引导堆栈，则最初在环境中为支持 CDK 部署而配置的 AWS 资源也将被删除。这将导致管线停止工作。如果发生这种情况，没有通用的恢复解决方案。

引导环境后，请勿删除并重新创建环境的引导堆栈。而应尝试通过再次运行 cdk bootstrap 命令将引导堆栈更新到新版本。

为了防止引导堆栈被意外删除，我们建议您在 cdk bootstrap 命令中提供 --termination-protection 选项来启用终止保护。您可以在新的或现有的引导堆栈上启用终止保护。有关启用终止保护的说明，请参阅为引导堆栈启用终止保护。

引导模板版本历史记录

引导模板是版本化的，并且会随着时间的推移与 CDK 本身一起演变。 AWS 如果您提供自己的引导模板，请使其与规范默认模板保持同步。您希望确保模板能够继续使用所有 CDK 功能。

注意

默认情况下，早期版本的引导模板会在每个引导环境中创建一个 AWS KMS 密钥。为避免产生 KMS 密钥费用，请使用 --no-bootstrap-customer-key 重新引导这些环境。当前的默认值为无 KMS 密钥，这有助于避免产生这些费用。

本节包含每个版本中所做的更改列表。

模板版本 AWS CDK 版本 更改

1

1.40.0

模板的初始版本，其中包含存储桶、密钥、存储库和角色。

2

1.45.0

将资产发布角色拆分为单独的文件和图像发布角色。

3

1.46.0

添加了 FileAssetKeyArn 导出，以便能够向资产使用者添加解密权限。

4

1.61.0

AWS KMS 权限现在是通过 Amazon S3 隐含的，不再需要FileAssetKeyArn。添加了 CdkBootstrapVersion SSM 参数，这样就可以在不知道堆栈名称的情况下验证引导堆栈版本。

5

1.87.0

部署角色可以读取 SSM 参数。

6

1.108.0

添加了独立于部署角色的查找角色。

6

1.109.0

为部署、文件发布和图像发布角色附加了 aws-cdk:bootstrap-role 标签。

7

1.110.0

部署角色无法再直接读取目标账户中的存储桶。（但是，此角色实际上是管理员，无论如何都可以随时使用其 AWS CloudFormation 权限使存储桶可读）。

8

1.114.0

查找角色对目标环境具有完全只读权限，并且带有一个 aws-cdk:bootstrap-role 标签。

9

2.1.0

修复了 Amazon S3 资产上传会被常引用的加密 SCP 拒绝的问题。

10

2.4.0

现在，Amazon ECR ScanOnPush 已默认启用。

11

2.18.0

添加了允许 Lambda 从 Amazon ECR 存储库拉取数据的策略，使其能够在重新引导后继续运行。

12

2.20.0

增加了对实验性 cdk import 的支持。

13

2.25.0

使引导创建的 Amazon ECR 存储库中的容器映像不可变。

14

2.34.0

默认情况下，在存储库级别关闭了 Amazon ECR 映像扫描，以允许引导不支持映像扫描的区域。

15

2.60.0

无法标记 KMS 密钥。

16

2.69.0

解决了 Security Hub 调查发现 KMS.2。

17

2.72.0

解决了 Security Hub 调查发现 ECR.3。

18

2.80.0

还原了针对版本 16 所做的更改，因为它们不适用于所有分区，因此不建议这样做。

19

2.106.1

恢复了对版本 18 所做的更改，其中 AccessControl 属性已从模板中移除。(#27964)

20

2.119.0

向 AWS CloudFormation 部署 IAM 角色添加ssm:GetParameters操作。有关更多信息，请参阅 #28336。

21

2.149.0

向文件发布角色添加了条件。

22

2.160.0

向引导 IAM 角色的信任策略添加了 sts:TagSession 权限。

23

2.161.0

向部署 IAM 角色的信任策略添加了 cloudformation:RollbackStack 和 cloudformation:ContinueUpdateRollback 权限。这提供了针对 cdk rollback 命令的权限。

24

2.165.0

将引导存储桶中非当前对象的保留天数从 365 天更改为 30 天。由于新 cdk gc 命令引入了删除引导存储桶中对象的能力，因此这种新行为确保已删除的对象在引导存储桶中保留 30 天而不是 365 天。有关此更改的更多信息，请参阅 aws-cdk PR #31949。

25

2.165.0

为引导存储桶添加移除不完整分段上传的支持。未完成分段上传将在 1 天后删除。有关此更改的更多信息，请参阅 aws-cdk PR #31956。

26

2.1002.0

为 FileAssetsBucketEncryptionKey 资源添加两个与删除相关的策略（UpdateReplacePolicy 和 DeletionPolicy）。这些策略可确保在更新或删除引导堆栈时正确删除旧的 AWS KMS 密钥资源。有关此更改的更多信息，请参阅 aws-cdk-cli PR #100。

27

2.1003.0

添加新的 Amazon ECR 资源策略，授予 Amazon EMR Serverless 检索容器映像的特定权限。有关此更改的更多信息，请参阅 aws-cdk-cli PR #112。

28

2.1015.0

为部署角色添加执行堆栈重构操作的 TagSession 权限，为所有角色添加权限。有关此变更的更多信息，请参阅 aws-cdk-cli PR #471。

29

2.1026.0

除非禁 AssumeRole 用，否则默认情况下，所有提供 a 的呼叫都 ExternalId 将被拒绝。有关此变更的更多信息，请参阅 aws-cdk-cli PR #811。

30

2.1034.0

向部署角色添加描述堆栈事件的权限，以便能够准确地显示 CloudFormation 早期验证错误。有关此变更的更多信息，请参阅 aws-cdk-cli PR #970。

[#bootstrapping-template] == 从传统引导模板升级到现代引导模板

AWS CDK v1 支持两个引导模板，即旧版和现代版。CDK v2 仅支持现代版模板。下面提供了这两个模板之间的简要区别，供您参考。

[cols= “1h,1,1"，options= “header"]

| 功能 | Legacy（仅限 v1）| 现代（v1 和 v2）

|跨账户部署 |不允许 |允许

|AWS CloudFormation 权限 |使用当前用户的权限（由 AWS 配置文件、环境变量等决定）进行部署 |使用配置引导堆栈时指定的权限进行部署（例如，使用）--trust

|版本控制 |只有一个版本的 bootstrap 堆栈可用 |Bootstrap 堆栈已版本控制；将来的版本中可以添加新资源，CDK 应用程序可能需要最低版本 AWS

|资源* |亚马逊 S3 存储桶 a|

  • 亚马逊 S3 存储桶

  • AWS KMS 密钥

  • IAM 角色

  • Amazon ECR 存储库

  • 用于版本控制的 SSM 参数

|AWS KMS 密钥 |IAM 角色 |亚马逊 ECR 存储库

|资源命名 |自动生成 |确定性

|存储桶加密 |默认密钥 | 默认情况下为AWS 托管密钥。您可以进行自定义，以便使用客户托管密钥。

*如果您没有使用CDK Pipelines进行跨账户部署，请修复 Security Hub 的发现

:::: + . Obtain a copy of the CDK bootstrap template to modify it. The following is an example, using the CDK CLI: + [source,bash,subs="verbatim,attributes"] ---- $ cdk bootstrap --show-template bootstrap-template.yaml ---- . Delete the PipelineCrossAccountArtifactsBucket and PipelineCrossAccountArtifactsKey statements from the template. . Deploy the template to update your bootstrap stack. The following is an example, using the CDK CLI: + [source,bash,subs="verbatim,attributes"] ---- $ cdk bootstrap aws://account-id/region --template bootstrap-template.yaml ----

[#bootstrapping-env-considerations] == 注意事项

由于引导会在您的环境中配置资源，因此当这些资源与 CDK 一起使用时，您可能会产生 AWS 费用。 AWS

* 我们将根据需要向引导模板添加其他资源。

必须通过重新引导将使用旧版模板引导的环境升级为使用 CDK v2 的现代版模板。在删除旧存储桶之前，至少重新部署环境中的所有 AWS CDK 应用程序一次。

[#bootstrapping-securityhub] == 地址 Security Hub 的调查结果

如果您使用的是 Sec AWS urity Hub，则可能会看到有关由 AWS CDK 引导过程创建的某些资源报告的调查结果。Security Hub 调查发现可帮助您找到资源配置，您应该仔细检查其准确性和安全性。我们已经通过 Sec AWS urity 审查了这些特定的资源配置，并确信它们不会构成安全问题。

[# bootstrapping-securityhub-kms 2] [KMS.2] IAM 委托人不应拥有允许对所有 KMS 密钥进行解密操作的 IAM 内联策略:: + 部署角色 (DeploymentActionRole) 授予读取加密数据的权限，这是使用 CDK Pipelines 进行跨账户部署所必需的。此角色中的策略不授予对所有数据的权限。它仅授予从 Amazon S3 和 AWS KMS 读取加密数据的权限，并且仅当这些资源通过其存储桶或密钥策略允许读取加密数据时。+ 以下是引导模板中部署角色中这两条语句的片段：+ [source、yaml、subs= “verbatim、attribates”]----：类型：: IAM:: Role Properties:...-Sid:...-Sid：允许操作：-s3：*-s3:-s3DeploymentActionRole: aBort*-s3 AWS: *-s3: aBort*-s3: *- PolicyDocument s3: aBort*-s3: *-s3: *-s3: aBort*-s3: *-s3: GetObject *-s3: aBort*-s3: GetBucket *-s3: *-s3: PutObject * 资源:“” 条件:: s3:: Ref::-Sid: DeleteObject Eff PipelineCrossAccountArtifactsBucket ection: Allow Action:-解密- StringNotEquals ResourceAccount AWS AccountId PipelineCrossAccountArtifactsKey kms: kms:DescribeKey- kms: 加密- kms: ReEncrypt- kms: GenerateDataKey * 资源：“” 条件：:: Fn StringEquals kms:ViaService:: Sub: s3。 $ {AWS:: Region} .amazonaws.com...----+ [# 2-whybootstrapping-securityhub-kms] *为什么 Security Hub 会举报这个？ ::: + 保单包含一个Resource: *合并Condition条款。Security Hub 会标记 * 通配符。之所以使用此通配符，是因为在启动账户时，CDK Pipelines为工件存储桶创建的 AWS KMS密钥尚不存在，因此ARN无法在引导模板上引用 CodePipeline 该密钥。此外，在设置此标志后，Security Hub 不会考虑 Condition 子句。这Condition仅限Resource: 于从 KMS AWS 密钥的同一个 AWS 账户发出的请求。这些请求必须来自与 AWS KMS 密钥位于同一 AWS 区域的 Amazon S3。+ [# bootstrapping-securityhub-kms 2-decide] *我需要修复这个发现吗？

::: + 只要您没有将引导模板上的 AWS KMS 密钥修改为过于宽松，则部署角色不允许超出其需要的访问权限。因此，没有必要修复此调查发现。+ [# bootstrapping-securityhub-kms 2-fix] 如果我想修复这个发现怎么办？ ::: + 如何修复这一发现取决于您是否将使用CDK Pipelines进行跨账户部署。+ 要修复 Security Hub 的发现并使用 CDK Pipelines 进行跨账户部署：:: +。如果您尚未执行此操作，请使用cdk bootstrap命令部署 CDK 引导堆栈。如果尚未创建并部署 CDK Pipeline，请执行此操作。有关说明，请参阅使用 CDK Pipelines 进行持续集成和交付 (CI/CD)。获取 CodePipeline 项目存储 AWS 桶的 KMS 密钥 ARN。此资源是在创建管道期间创建的。获取 CDK 引导模板的副本以对其进行修改。以下是使用 AWS CDK CLI 的示例：+ [source、bash、subs= “verbatim，attribates”]----$ cdk bootstrap--show-template bootstrap-template-template.yaml----。通过将PipelineCrossAccountArtifactsKey语句替换Resource: 为您的 ARN 值来修改模板。部署模板以更新引导堆栈。以下是使用 CDK CLI 的示例：+ [source、bash、subs= “verbatim，attribates”]----$ cdk bootstrap aws: //account-id/region--template bootstrap-template.template.yaml —---+