这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 引导您的环境以便与 CDK 一起使用 AWS 引导您的 AWS 环境，使其为 C AWS loud Development Kit (AWS CDK) 堆栈部署做好准备。 + 有关环境的介绍，请参阅 [AWS CDK 的环境](environments.md)。 + 有关引导的介绍，请参阅 [AWS CDK 引导](bootstrapping.md)。 ## 如何引导环境 您可以使用 AWS CDK 命令行界面 (AWS CDK CLI) 或您的首选 AWS CloudFormation 部署工具来引导您的环境。 **使用 CDK CLI** 您可以使用 CDK CLI `cdk bootstrap` 命令来引导环境。如果您不需要对引导进行重大修改，我们建议您使用此方法。 **从任何工作目录引导** 要从任何工作目录引导，请提供用于引导的环境作为命令行参数。以下是示例： ``` $ cdk bootstrap ``` 如果您没有 AWS 账号，可以从 AWS 管理控制台中获取。您也可以使用以下 AWS CLI 命令来显示您的默认账户信息，包括您的账号： ``` $ aws sts get-caller-identity ``` 如果您在 AWS `config`和`credentials`文件中命名了个人资料，请使用该`--profile`选项来检索特定个人资料的帐户信息。以下是示例： ``` $ aws sts get-caller-identity --profile ``` 要显示默认区域，请使用 `aws configure get` 命令： ``` $ aws configure get region $ aws configure get region --profile ``` 提供参数时，`aws://` 前缀是可选的。以下参数有效： ``` $ cdk bootstrap <123456789012/us-east-1> ``` 要同时引导多个环境，请提供多个参数： ``` $ cdk bootstrap ``` **从 CDK 项目的父目录中引导** 您可以从包含 `cdk.json` 文件的 CDK 项目的父目录运行 `cdk bootstrap`。如果您不提供环境作为参数，则 CDK CLI 将从默认源（例如 `config` 和 `credentials` 文件）获取环境信息或为 CDK 堆栈指定的任何环境信息。 从 CDK 项目的父目录引导时，通过命令行参数提供的环境优先于其他源。 要引导在 `config` 和 `credentials` 文件中指定的环境，请使用 `--profile` 选项： ``` $ cdk bootstrap --profile ``` 有关 `cdk bootstrap` 命令和支持的选项的更多信息，请参阅 [cdk bootstrap](ref-cli-cmd-bootstrap.md)。 **使用任何 AWS CloudFormation 工具** 您可以从*aws-cdk-cli GitHub 存储库*中复制[引导模板](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml)或使用`cdk bootstrap --show-template`命令获取模板。然后，使用任何 AWS CloudFormation 工具将模板部署到您的环境中。 通过这种方法，你可以使用 AWS CloudFormation StackSets 或 Cont AWS rol Tower。您也可以使用 AWS CloudFormation 控制台或 AWS 命令行界面 (AWS CLI)。在部署模板之前，您可以对其进行修改。这种方法可能更灵活，适合大规模部署。 以下是使用 `--show-template` 选项检索引导模板并将其保存到本地计算机的示例： **Example** ``` $ cdk bootstrap --show-template > bootstrap-template.yaml ``` 在 Windows 上， PowerShell 必须使用它来保留模板的编码。 ``` powershell "cdk bootstrap --show-template | Out-File -encoding utf8 bootstrap-template.yaml" ``` 如果 AWS CloudFormation 模板输出中出现 CDK 通知，请在命令中提供该`--no-notices`选项。 要使用 CDK CLI 部署此模板，可以运行以下命令： ``` $ cdk bootstrap --template ``` 以下是使用 AWS CLI 部署模板的示例： **Example** ``` aws cloudformation create-stack \ --stack-name CDKToolkit \ --template-body file://bootstrap-template.yaml \ --capabilities CAPABILITY_NAMED_IAM \ --region ``` ``` aws cloudformation create-stack ^ --stack-name CDKToolkit ^ --template-body file://bootstrap-template.yaml ^ --capabilities CAPABILITY_NAMED_IAM ^ --region ``` 有关使用引导多个环境的信息 CloudFormation StackSets ，请参阅 C * AWS loud Operations & M [igrations 博客 CloudFormation StackSets中的使用引导 AWS CDK 的多个 AWS 帐户](https://aws.amazon.com/blogs/mt/bootstrapping-multiple-aws-accounts-for-aws-cdk-using-cloudformation-stacksets/)。* ## 何时引导环境 在部署到 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 团队会定期将引导模板更新到新版本。发生这种情况时，我们建议您更新引导堆栈。如果您尚未自定义引导过程，则可以按照最初引导环境时所执行的相同步骤来更新引导堆栈。有关更多信息，请参阅[引导模板版本历史记录](#bootstrap-template-history)。 ## 在引导期间创建的默认资源 **在引导期间创建的 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 环境中查找[上下文值](context.md)的权限。此角色由 CDK CLI 在执行模板合成和部署等任务时代入。 **在引导过程中 IDs 创建的资源** 部署默认引导模板时，将使用以下结构创建 IDs 用于引导的物理资源：。`cdk----` + **限定符**：九个字符的唯一字符串值 `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](bootstrapping-customizing.md) CDK 引导。 ## 使用 CDK 管线进行引导 如果您使用 CDK 管线部署到其他账户的环境中，并且收到如下消息： ``` Policy contains a statement with one or more invalid principals ``` 此错误消息表示其他环境中不存在相应的 IAM 角色。最可能的原因是尚未引导环境。引导环境并重试。 **保护您的引导堆栈不被删除** 如果删除了引导堆栈，则最初在环境中为支持 CDK 部署而配置的 AWS 资源也将被删除。这将导致管线停止工作。如果发生这种情况，没有通用的恢复解决方案。 引导环境后，请勿删除并重新创建环境的引导堆栈。而应尝试通过再次运行 `cdk bootstrap` 命令将引导堆栈更新到新版本。 为了防止引导堆栈被意外删除，我们建议您在 `cdk bootstrap` 命令中提供 `--termination-protection` 选项来启用终止保护。您可以在新的或现有的引导堆栈上启用终止保护。有关启用终止保护的说明，请参阅[为引导堆栈启用终止保护](bootstrapping-customizing.md#bootstrapping-customizing-cli-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](https://docs.aws.amazon.com/securityhub/latest/userguide/kms-controls.html#kms-2)。 | | **17** | 2.72.0 | 解决了 Security Hub 调查发现 [ECR.3](https://docs.aws.amazon.com/securityhub/latest/userguide/ecr-controls.html#ecr-3)。 | | **18** | 2.80.0 | 还原了针对版本 16 所做的更改，因为它们不适用于所有分区，因此不建议这样做。 | | **19** | 2.106.1 | 恢复了对版本 18 所做的更改，其中 AccessControl 属性已从模板中移除。([\$127964](https://github.com/aws/aws-cdk/issues/27964)) | | **20** | 2.119.0 | 向 AWS CloudFormation 部署 IAM 角色添加`ssm:GetParameters`操作。有关更多信息，请参阅 [\$128336](https://github.com/aws/aws-cdk/pull/28336/files#diff-4fdac38426c4747aa17d515b01af4994d3d2f12c34f7b6655f24328259beb7bf)。 | | **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 [\$131949](https://github.com/aws/aws-cdk/pull/31949)。 | | **25** | 2.165.0 | 为引导存储桶添加移除不完整分段上传的支持。未完成分段上传将在 1 天后删除。有关此更改的更多信息，请参阅 `aws-cdk` PR [\$131956](https://github.com/aws/aws-cdk/pull/31956)。 | | **26** | 2.1002.0 | 为 `FileAssetsBucketEncryptionKey` 资源添加两个与删除相关的策略（`UpdateReplacePolicy` 和 `DeletionPolicy`）。这些策略可确保在更新或删除引导堆栈时正确删除旧的 AWS KMS 密钥资源。有关此更改的更多信息，请参阅 `aws-cdk-cli` PR [\$1100](https://github.com/aws/aws-cdk-cli/pull/100)。 | | **27** | 2.1003.0 | 添加新的 Amazon ECR 资源策略，授予 Amazon EMR Serverless 检索容器映像的特定权限。有关此更改的更多信息，请参阅 `aws-cdk-cli` PR [\$1112](https://github.com/aws/aws-cdk-cli/pull/112)。 | | **28** | 2.1015.0 | 为部署角色添加执行堆栈重构操作的 TagSession 权限，为所有角色添加权限。有关此变更的更多信息，请参阅 `aws-cdk-cli` PR [\$1471](https://github.com/aws/aws-cdk-cli/pull/471)。 | | **29** | 2.1026.0 | 除非禁 AssumeRole 用，否则默认情况下，所有提供 a 的呼叫都 ExternalId 将被拒绝。有关此变更的更多信息，请参阅 `aws-cdk-cli` PR [\$1811](https://github.com/aws/aws-cdk-cli/pull/811)。 | | **30** | 2.1034.0 | 向部署角色添加描述堆栈事件的权限，以便能够准确地显示 CloudFormation 早期验证错误。有关此变更的更多信息，请参阅 `aws-cdk-cli` PR [\$1970](https://github.com/aws/aws-cdk-cli/pull/970)。 | ## 从旧版引导模板升级到现代版引导模板 AWS CDK v1 支持两个引导模板，即旧版和现代版。CDK v2 仅支持现代版模板。下面提供了这两个模板之间的简要区别，供您参考。 | 功能 | 旧版（仅限 v1） | 现代版（v1 和 v2） | | --- | --- | --- | | **跨账户部署** | 不允许 | 允许 | | ** AWS CloudFormation 权限** | 使用当前用户的权限（由 AWS 配置文件、环境变量等决定）进行部署 | 使用预置引导堆栈时指定的权限（例如，使用 `--trust`）进行部署 | | **版本控制** | 只有一个版本的引导堆栈可用 | Bootstrap 堆栈已有版本控制；可以在未来的版本中添加新资源， AWS CDK 应用程序可能需要最低版本 | | **资源**\$1 | 亚马逊 S3 存储桶 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/cdk/v2/guide/bootstrapping-env.html) | | ** AWS KMS 密钥** | IAM 角色 | Amazon ECR 存储库 | | **资源命名** | 自动生成 | 确定性 | | **存储桶加密** | 默认密钥 | AWS 默认情况下是托管密钥。您可以进行自定义，以便使用客户托管密钥。 | + *我们将根据需要向引导模板添加其他资源。* 必须通过重新引导将使用旧版模板引导的环境升级为使用 CDK v2 的现代版模板。在删除旧存储桶之前，至少重新部署环境中的所有 AWS CDK 应用程序一次。 ## 解决 Security Hub 调查发现 如果您使用的是 Sec AWS urity Hub，则可能会看到有关由 AWS CDK 引导过程创建的某些资源报告的调查结果。Security Hub 调查发现可帮助您找到资源配置，您应该仔细检查其准确性和安全性。我们已经通过 Sec AWS urity 审查了这些特定的资源配置，并确信它们不会构成安全问题。 **[KMS.2] IAM 委托人不应拥有允许对所有 KMS 密钥进行解密操作的 IAM 内联策略** *部署角色*（`DeploymentActionRole`）授予读取加密数据的权限，这是使用 CDK 管线进行跨账户部署所必需的。此角色中的策略不授予对所有数据的权限。它仅授予从 Amazon S3 和 AWS KMS 读取加密数据的权限，并且仅当这些资源通过其存储桶或密钥策略允许读取加密数据时。 下面是引导模板中*部署角色*的两个语句的代码段： ``` DeploymentActionRole: Type: AWS::IAM::Role Properties: ... Policies: - PolicyDocument: Statement: ... - Sid: PipelineCrossAccountArtifactsBucket Effect: Allow Action: - s3:GetObject* - s3:GetBucket* - s3:List* - s3:Abort* - s3:DeleteObject* - s3:PutObject* Resource: "*" Condition: StringNotEquals: s3:ResourceAccount: Ref: AWS::AccountId - Sid: PipelineCrossAccountArtifactsKey Effect: Allow Action: - kms:Decrypt - kms:DescribeKey - kms:Encrypt - kms:ReEncrypt* - kms:GenerateDataKey* Resource: "*" Condition: StringEquals: kms:ViaService: Fn::Sub: s3.${AWS::Region}.amazonaws.com ... ``` **为什么 Security Hub 会举报这个？** 策略包含组合了 `Condition` 子句的 `Resource: *`。Security Hub 会标记 `*` 通配符。之所以使用此通配符，是因为在启动账户时，CDK Pipelines为工件存储桶创建的 AWS KMS密钥尚不存在，因此ARN无法在引导模板上引用 CodePipeline 该密钥。此外，在设置此标志后，Security Hub 不会考虑 `Condition` 子句。这`Condition`仅限`Resource: *`于从 KMS AWS 密钥的同一个 AWS 账户发出的请求。这些请求必须来自与 AWS KMS 密钥位于相同 AWS 区域的 Amazon S3。 **我需要修复这个发现吗？** 只要您没有将引导模板上的 AWS KMS 密钥修改为过于宽松，*部署角色*就不会允许超出其需要的访问权限。因此，没有必要修复此调查发现。 **如果我想修复这个发现怎么办？** 如何修复此调查发现取决于您是否使用 CDK 管线进行跨账户部署。 **修复 Security Hub 的发现并使用 CDK Pipelines 进行跨账户部署** 1. 如果尚未使用 `cdk bootstrap` 命令部署 CDK 引导堆栈，请执行此操作。 1. 如果尚未创建并部署 CDK Pipeline，请执行此操作。有关说明，请参阅[使用 CDK 管线进行持续集成和交付（CI/CD）](cdk-pipeline.md)。 1. 获取 CodePipeline 项目存储 AWS 桶的 KMS 密钥 ARN。此资源是在创建管线期间创建的。 1. 获取 CDK 引导模板的副本以对其进行修改。以下是使用 AWS CDK CLI 的示例： ``` $ cdk bootstrap --show-template > bootstrap-template.yaml ``` 1. 通过将 `PipelineCrossAccountArtifactsKey` 语句的 `Resource: *` 替换为 ARN 值来修改模板。 1. 部署模板以更新引导堆栈。以下是使用 CDK CLI 的示例： ``` $ cdk bootstrap aws:/// --template bootstrap-template.yaml ``` **如果您没有使用 CDK Pipelines 进行跨账户部署，请修复 Security Hub 的发现** 1. 获取 CDK 引导模板的副本以对其进行修改。以下是使用 CDK CLI 的示例： ``` $ cdk bootstrap --show-template > bootstrap-template.yaml ``` 1. 从模板中删除 `PipelineCrossAccountArtifactsBucket` 和 `PipelineCrossAccountArtifactsKey` 语句。 1. 部署模板以更新引导堆栈。以下是使用 CDK CLI 的示例： ``` $ cdk bootstrap aws:/// --template bootstrap-template.yaml ``` ## 注意事项 由于引导会在您的环境中配置资源，因此当这些资源与 CDK 一起使用时，您可能会产生 AWS 费用。 AWS