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

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

# `cdk bootstrap`
<a name="ref-cli-cmd-bootstrap"></a>

将名为 `CDKToolkit` 的 CDK 引导堆栈部署到 AWS 环境中，从而为 CDK 部署准备 AWS 环境。

引导堆栈是一个 CloudFormation 堆栈，用于在 AWS 环境中预置 Amazon S3 存储桶和 Amazon ECR 存储库。在部署期间，AWS CDK CLI 使用这些资源来存储合成的模板和相关资产。

## 使用量
<a name="ref-cli-cmd-bootstrap-usage"></a>

```
$ cdk bootstrap <arguments> <options>
```

## 参数
<a name="ref-cli-cmd-bootstrap-args"></a><a name="ref-cli-cmd-bootstrap-args-env"></a>

 **AWS 环境**   
将引导堆栈部署到的目标 AWS 环境，格式如下：`aws://<account-id>/<region>`。  
示例：`aws://123456789012/us-east-1`  
可以在单个命令中多次提供此参数，以便将引导堆栈部署到多个环境中。  
默认情况下，CDK CLI 将引导 CDK 应用程序中引用的所有环境，或者根据默认源来确定环境。这可以是使用 `--profile` 选项从环境变量指定的环境，也可以是默认 AWS CLI 源指定的环境。

## 选项
<a name="ref-cli-cmd-bootstrap-options"></a>

有关适用于所有 CDK CLI 命令的全局选项的列表，请参阅[全局选项](ref-cli-cmd.md#ref-cli-cmd-options)。<a name="ref-cli-cmd-bootstrap-options-bootstrap-bucket-name"></a>

 `--bootstrap-bucket-name, --toolkit-bucket-name, -b <STRING>`   
CDK CLI 将使用的 Amazon S3 存储桶的名称。将创建此存储桶，且当前一定不存在此存储桶。  
提供此选项可覆盖 Amazon S3 存储桶的默认名称。  
使用此选项时，可能需要自定义合成。要了解更多信息，请参阅[自定义 CDK 堆栈合成](configure-synth.md#bootstrapping-custom-synth)。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-bootstrap-customer-key"></a>

 `--bootstrap-customer-key <BOOLEAN>`   
为引导存储桶创建客户主密钥（CMK）（您需要付费，但可以自定义权限，仅限现代引导）。  
此选项与 `--bootstrap-kms-key-id` 不兼容。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-bootstrap-kms-key-id"></a>

 `--bootstrap-kms-key-id <STRING>`   
用于 `SSE-KMS` 加密的 AWS KMS 主密钥 ID。  
提供此选项可覆盖用于加密 Amazon S3 存储桶的默认 AWS KMS 密钥。  
此选项与 `--bootstrap-customer-key` 不兼容。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-cloudformation-execution-policies"></a>

 `--cloudformation-execution-policies <ARRAY>`   
在部署堆栈期间，应附加到 AWS CloudFormation 所担任的部署角色的托管 IAM 策略 ARN。  
默认情况下，使用 `AdministratorAccess` 策略以完整管理员权限来部署堆栈。  
您可以在单个命令中多次提供此选项。您还可以将多个 ARN 作为单个字符串提供，各个 ARN 之间用逗号分隔。以下是示例：  

```
$ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess"
```
为避免部署失败，请确保您指定的策略足以满足将在引导的环境中执行的任何部署。  
此选项仅适用于现代引导。  
现代引导模板可以有效地向 `--trust` 列表中的任何 AWS 账户授予 `--cloudformation-execution-policies` 隐含的权限。默认情况下，这会扩展对引导账户中任何资源的读取和写入权限。请务必使用您熟悉的策略和可信账户来[配置引导堆栈](bootstrapping-customizing.md)。
 *默认值*：`[]`<a name="ref-cli-cmd-bootstrap-options-custom-permissions-boundary"></a>

 `--custom-permissions-boundary, -cpb <STRING>`   
指定要使用的权限边界的名称。  
此选项与 `--example-permissions-boundary` 不兼容。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-example-permissions-boundary"></a>

 `--example-permissions-boundary, -epb <BOOLEAN>`   
使用 AWS CDK 提供的示例权限边界。  
此选项与 `--custom-permissions-boundary` 不兼容。  
CDK 提供的权限边界策略应视为示例。如果您正在测试该功能，请编辑内容并参考示例策略。将其转换为实际部署的新策略（如果尚不存在）。需要关注的是避免出现偏差。最有可能的是，权限边界得以维护，并有专门的约定，其中包括命名。  
有关配置权限（包括使用权限边界）的更多信息，请参阅《[Security and Safety Dev Guide](https://github.com/aws/aws-cdk/wiki/Security-And-Safety-Dev-Guide)》。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-execute"></a>

 `--execute <BOOLEAN>`   
配置是否执行更改集。  
 *默认值*：`true`<a name="ref-cli-cmd-bootstrap-options-force"></a>

 `--force, -f <BOOLEAN>`   
应始终进行引导，即使会导致引导模板版本降级。  
 *默认值*：`false`<a name="ref-cli-cmd-bootstrap-options-help"></a>

 `--help, -h <BOOLEAN>`   
显示 `cdk bootstrap` 命令的命令参考信息。<a name="ref-cli-cmd-bootstrap-options-previous-parameters"></a>

 `--previous-parameters <BOOLEAN>`   
对现有参数使用以前的值。  
使用一组参数部署了引导模板后，必须将此选项设置为 `false`，才能在将来的部署中更改任何参数。当为 `false` 时，必须重新提供之前提供的所有参数。  
 *默认值*：`true`<a name="ref-cli-cmd-bootstrap-options-public-access-block-configuration"></a>

 `--public-access-block-configuration <BOOLEAN>`   
Amazon S3 存储桶上的屏蔽公共访问权限配置，由 CDK CLI 创建和使用。  
 *默认值*：`true`<a name="ref-cli-cmd-bootstrap-options-qualifier"></a>

 `--qualifier <STRING>`   
九位字符串值，对于每个引导堆栈都是唯一的。将添加此值到引导堆栈中资源的物理 ID 中。  
通过提供限定符，可以避免在同一环境中预置多个引导堆栈时资源名称冲突。  
更改限定符时，CDK 应用程序必须将更改后的值传递给堆栈合成器。有关更多信息，请参阅[自定义 CDK 堆栈合成](configure-synth.md#bootstrapping-custom-synth)。  
 *默认值*：`hnb659fds`。此值没有任何意义。<a name="ref-cli-cmd-bootstrap-options-show-template"></a>

 `--show-template <BOOLEAN>`   
不进行引导，而是将当前的引导模板打印到标准输出 (`stdout`)。然后，您就可以根据需要复制和自定义模板。  
 *默认值*：`false`<a name="ref-cli-cmd-bootstrap-options-tags"></a>

 `--tags, -t <ARRAY>`   
要添加到引导堆栈的标签，格式为 `KEY=VALUE`。  
 *默认值*：`[]`<a name="ref-cli-cmd-bootstrap-options-template"></a>

 `--template <STRING>`   
使用给定文件中的模板，而不是内置模板。<a name="ref-cli-cmd-bootstrap-options-termination-protection"></a>

 `--termination-protection <BOOLEAN>`   
在引导堆栈上切换 AWS CloudFormation 终止保护。  
当为 `true` 时，表示已启用终止保护。这可以防止意外删除引导堆栈。  
要了解有关终止保护的更多信息，请参阅《AWS CloudFormation 用户指南》**中的[防止堆栈被删除](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html)。  
 *默认值*：未定义<a name="ref-cli-cmd-bootstrap-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
要创建的引导堆栈的名称。  
默认情况下，`cdk bootstrap` 会将名为 `CDKToolkit` 的堆栈部署到指定的 AWS 环境中。使用此选项可为引导堆栈提供不同的名称。  
CDK CLI 使用此值来验证引导堆栈版本。  
 *默认值*：`CDKToolkit`  
 *必需*：是<a name="ref-cli-cmd-bootstrap-options-trust"></a>

 `--trust <ARRAY>`   
应信任的 AWS 账户 ID，以便在此环境中执行部署。  
执行引导的账户将始终受到信任。  
此选项还要求您提供 `--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.
```
现代引导模板可以有效地向 `--trust` 列表中的任何 AWS 账户授予 `--cloudformation-execution-policies` 隐含的权限。默认情况下，这会扩展对引导账户中任何资源的读取和写入权限。请务必使用您熟悉的策略和可信账户来[配置引导堆栈](bootstrapping-customizing.md)。
 *默认值*：`[]`<a name="ref-cli-cmd-bootstrap-options-trust-for-lookup"></a>

 `--trust-for-lookup <ARRAY>`   
应信任的 AWS 账户 ID，以便在此环境中查找值。  
使用此选项可以向账户授予合成堆栈的权限（这些堆栈将部署到环境中），而无需实际向其授予直接部署这些堆栈的权限。  
您可以在单个命令中多次提供此选项。  
此选项仅适用于现代引导。  
 *默认值*：`[]`

## 示例
<a name="ref-cli-cmd-bootstrap-examples"></a>

### 引导 prod 配置文件中指定的 AWS 环境
<a name="ref-cli-cmd-bootstrap-examples-1"></a>

```
$ cdk bootstrap --profile prod
```

### 将引导堆栈部署到环境 foo 和 bar
<a name="ref-cli-cmd-bootstrap-examples-2"></a>

```
$ cdk bootstrap --app='node bin/main.js' foo bar
```

### 导出引导模板以进行自定义
<a name="ref-cli-cmd-bootstrap-examples-3"></a>

如果引导模板无法满足您的特定要求，可以对其进行自定义以满足您的需求。

您可以使用 AWS CloudFormation 导出引导模板、对其进行修改并进行部署。以下是导出现有模板的示例：

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

您也可以让 CDK CLI 使用自定义模板。以下是示例：

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

### 使用权限边界进行引导。然后删除该权限边界
<a name="ref-cli-cmd-bootstrap-examples-4"></a>

要使用自定义权限边界进行引导，我们运行以下命令：

```
$ cdk bootstrap --custom-permissions-boundary my-permissions-boundary
```

要删除权限边界，我们运行以下命令：

```
$ cdk bootstrap --no-previous-parameters
```

### 使用限定符来区分为开发环境创建的资源
<a name="ref-cli-cmd-bootstrap-examples-5"></a>

```
$ cdk bootstrap --qualifier dev2024
```