这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 自定义 AWS CDK 引导
您可以通过使用 AWS CDK 命令行界面 (AWS CDK CLI) 或通过修改和部署 AWS CloudFormation 引导模板来自定义 AWS 云开发工具包 (AWS CDK) 引导。
有关引导的介绍，请参阅 [AWS CDK 引导](bootstrapping.md)。
## 使用 CDK CLI 自定义引导
以下是如何使用 CDK CLI 自定义引导的几个示例。有关所有 `cdk bootstrap` 选项的列表，请参阅 [cdk bootstrap](ref-cli-cmd-bootstrap.md)。
**覆盖 Amazon S3 存储桶的名称**
使用 `--bootstrap-bucket-name` 选项可覆盖默认 Amazon S3 存储桶名称。这可能需要您修改模板合成。有关更多信息，请参阅[自定义 CDK 堆栈合成](configure-synth.md#bootstrapping-custom-synth)。
**修改 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 堆栈合成](configure-synth.md#bootstrapping-custom-synth)。
**向引导堆栈添加标签**
使用 `KEY=VALUE` 格式的 `--tags` 选项可以向引导堆栈添加 CloudFormation 标签。
**指定可以部署到所引导的环境的其他 AWS 账户**
使用 `--trust` 选项可提供允许部署到所引导的环境的其他 AWS 账户。默认情况下，执行引导的账户将始终受到信任。
当您引导来自其他环境的 CDK Pipeline 将部署到的环境时，此选项非常有用。
使用此选项时，还必须提供 `--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
```
1. 使用 AWS CLI 或 CloudFormation 控制台进行验证。以下是一个使用 AWS CLI 的示例。如果您修改了引导堆栈名称，请将 `CDKToolkit` 替换为堆栈名称：
```
$ aws cloudformation describe-stacks --stack-name --query "Stacks[0].EnableTerminationProtection"
true
```
## 修改默认引导模板
当您需要的自定义设置超出 CDK CLI 能提供的范围时，可以根据需要修改引导模板。然后，部署模板以引导环境。
**修改和部署默认引导模板**
1. 使用 `--show-template` 选项获取默认引导模板。默认情况下，CDK CLI 将在终端窗口中输出模板。您可以修改 CDK CLI 命令以将模板保存到本地计算机。以下是示例：
```
$ cdk bootstrap --show-template >
```
1. 根据需要修改引导模板。您所做的任何更改都应遵循引导模板合约。有关引导模板合约的更多信息，请参阅[遵循引导合约](#bootstrapping-contract)。
要确保您的自定义设置不会在以后被使用默认模板运行 `cdk bootstrap` 的用户意外覆盖，请更改 `BootstrapVariant` 模板参数的默认值。CDK CLI 只允许使用具有相同 `BootstrapVariant` 且版本等于或高于当前所部署模板的模板来覆盖引导堆栈。
1. 使用您的首选 AWS CloudFormation 部署方法部署修改后的模板。以下是使用 CDK CLI 的示例：
```
$ cdk bootstrap --template
```
## 遵循引导合约
为了正确部署 CDK 应用程序，合成过程中生成的 CloudFormation 模板必须正确指定引导过程中创建的资源。这些资源通常称为*引导资源*。引导会在 AWS 环境中创建 AWS CDK 用于执行部署和管理应用程序资产的资源。合成会根据应用程序中的每个 CDK 堆栈生成 CloudFormation 模板。这些模板不只是定义将从您的应用程序中预置的 AWS 资源。它们还指定部署期间要使用的引导资源。
在合成期间，CDK CLI 并不具体知道 AWS 环境是如何引导的。CDK CLI 会根据您配置的合成器生成 CloudFormation 模板。因此，自定义引导时，您可能需要自定义合成。有关自定义合成的说明，请参阅[自定义 CDK 堆栈合成](configure-synth.md#bootstrapping-custom-synth)。目的是确保合成的 CloudFormation 模板与引导的环境兼容。这种兼容性称为*引导合约*。
自定义堆栈合成的最简单方法是修改 `Stack` 实例中的 `DefaultStackSynthesizer` 类。如果您需要的自定义设置超出了此类所能提供的范围，您可以编写自己的合成器作为实现 ` [IStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IStackSynthesizer.html) `（可能派生自 `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` – 引导堆栈的当前版本。
### 模板历史记录
引导模板受版本控制，并且会因 AWS CDK 本身随着时间推移而发生变化。如果您提供自己的引导模板，请使其与规范默认模板保持同步。您希望确保模板能够继续使用所有 CDK 功能。有关更多信息，请参阅[引导模板版本历史记录](bootstrapping-env.md#bootstrap-template-history)。