这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS CDK CLI 参考文档 AWS 云开发套件 (AWS CDK) 命令行界面 (AWS CDK CLI)，也称为 CDK 工具包，是与 CDK 应用程序 AWS 交互的主要工具。它执行您的应用程序，查询您定义的应用程序模型，并生成和部署 CDK 生成的 AWS CloudFormation 模板。 AWS 它还提供了其他对创建和处理 AWS CDK 项目有用的功能。本主题包含有关 CDK CLI 常见使用案例的信息。 CDK CLI 与节点程序包管理器一起安装。大多数情况下，我们建议在全局范围内安装。 ``` npm install -g aws-cdk # install latest version npm install -g aws-cdk@X.YY.Z # install specific version ``` **提示** 如果您经常使用多个版本的 AWS CDK，请考虑在单个 CDK 项目中安装匹配版本的 CDK CLI。为此，请在 `npm install` 命令中省略 `-g`。然后使用 `npx aws-cdk` 来调用它。如果存在本地版本，则运行本地版本；如果不存在，则回退到全局版本。 ## CDK CLI 命令 所有 CDK CLI 命令都以 `list` 开头，后跟子命令（`cdk`、`synthesize`、`deploy` 等）。一些子命令具有等效的简短版本（`ls`、`synth` 等）。选项和参数按任意顺序跟在子命令之后。 有关所有子命令、选项和参数的说明，请参阅 [AWS CDK CLI 命令参考](ref-cli-cmd.md)。 ## 指定选项及其值 命令行选项以两个连字符（`--`）开头。一些常用的选项具有以单个连字符开头的单字母同义词（例如，`--app` 具有同义词 `-a`）。CDK CLI 命令中选项的顺序并不重要。 所有选项都接受一个值，该值必须跟在选项名称之后。该值可以用空格或等号 `=` 与名称隔开。以下两个选项是等效的。 ``` --toolkit-stack-name MyBootstrapStack --toolkit-stack-name=MyBootstrapStack ``` 有些选项是标志（布尔值）。您可以指定 `true` 或 `false` 作为它们的值。如果您未提供值，则该值被认为是 `true`。您还可以在选项名称前加上前缀 `no-` 来表示 `false`。 ``` # sets staging flag to true --staging --staging=true --staging true # sets staging flag to false --no-staging --staging=false --staging false ``` 您可以多次指定几个选项（即 `--context`、`--parameters`、`--plugin`、`--tags` 和 `--trust`）以指定多个值。在 CDK CLI 帮助中注明这些选项具有 `[array]` 类型。例如： ``` cdk bootstrap --tags costCenter=0123 --tags responsibleParty=jdoe ``` ## Built-in 帮帮我 CDK CLI 集成了帮助。您可以通过发出以下命令来查看有关实用程序的一般帮助和所提供的子命令列表： ``` cdk --help ``` 要查看特定子命令（例如 `deploy`）的帮助，请在 `--help` 标志之前指定该子命令。 ``` cdk deploy --help ``` 发出 `cdk version` 以显示 CDK CLI 的版本。在请求支持时提供此信息。 ## 版本报告 为了深入了解 AWS CDK 的使用方式，使用标识为的资源收集和报告 AWS CDK 应用程序使用的结构。` AWS::CDK::Metadata`要了解更多信息，请参阅[配置 AWS CDK 使用情况数据报告](usage-data.md)。 ## 使用进行身份验证 AWS 您可以通过不同的方式配置对 AWS 资源的编程访问，具体取决于环境和可用的 AWS 访问权限。 要选择身份验证方法并将其配置为 CDK CLI，请参阅[为 CDK CLI 配置安全证书。 AWS](configure-access.md) 对于在本地开发的新用户，如果雇主没有提供身份验证方法，推荐的方法是设置 AWS IAM 身份中心。此方法包括安装 AWS CLI 以简化配置和定期登录 AWS 访问门户。如果您选择此方法，则在完成《软件开发工具包和* AWS 工具参考指南*》[中的 IAM 身份中心身份验证](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html)过程后，您的环境应包含以下元素： + C AWS LI，用于在运行应用程序之前启动 AWS 访问门户会话。 + 一个[共享 AWS 配置文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)，`[default]`其配置文件包含一组可从 AWS CDK 引用的配置值。要查找此文件的位置，请参阅《软件开发工具包和* AWS 工具参考指南*》[中的共享文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)的位置。 + 共享的 `config` 文件设置 [region](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html) 设置。这会设置 AWS CDK 和 CDK CLI 用于 AWS 请求的默认 AWS 区域。 + 在向 AWS发送请求之前，CDK CLI 使用该配置文件的 [SSO 令牌提供程序配置](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile)来获取凭证。该`sso_role_name`值是与 IAM 身份中心权限集相关的 IAM 角色，应允许访问您的应用程序中使用的 AWS 服务。 以下示例 `config` 文件展示了使用 SSO 令牌提供程序配置来设置的默认配置文件。配置文件的 `sso_session` 设置是指所指定的 [`sso-session` 部分](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session)。该`sso-session`部分包含启动 AWS 访问门户会话的设置。 ``` [default] sso_session = sso_account_id = <111122223333> sso_role_name = region = output = [sso-session ] sso_region = sso_start_url = sso_registration_scopes = sso:account:access ``` ### 开始一个 AWS 访问门户会话 在访问 AWS 服务之前，您需要一个有效的 AWS 访问门户会话，让 CDK CLI 使用 IAM 身份中心身份验证来解析证书。根据配置的会话时长，访问权限最终将过期，并且 CDK CLI 将遇到身份验证错误。在 AWS CLI 中运行以下命令登录 AWS 访问门户。 ``` aws sso login ``` 如果 SSO 令牌提供程序配置使用命名配置文件而不是默认配置文件，则命令为 `aws sso login --profile `。使用 `--profile` 选项或 `AWS_PROFILE` 环境变量发出 `cdk` 命令时，也应指定此配置文件。 要测试您是否已经有活动会话，请运行以下 AWS CLI 命令。 ``` aws sts get-caller-identity ``` 对此命令的响应应该报告共享 `config` 文件中配置的 IAM Identity Center 账户和权限集。 **注意** 如果您已经拥有活跃的 AWS 访问门户会话并正在运行`aws sso login`，则无需提供证书。 登录过程可能会提示您允许 AWS CLI 访问您的数据。由于 AWS CLI 建立在 Python 开发工具包之上，因此权限消息可能包含`botocore`名称的变体。 ## 指定区域和其他配置 CDK CLI 需要知道您要部署到的 AWS 区域以及如何进行 AWS身份验证。这是部署操作以及合成期间检索上下文值所必需的。您的账户和区域共同构成了*环境*。 您可以使用环境变量或在配置文件中指定区域。这些变量和文件与 AWS CLI 和各种 AWS SDK 等其他 AWS 工具使用的变量和文件相同。CDK CLI 会按以下顺序查找此信息。 + `AWS_DEFAULT_REGION` 环境变量。 + 在标准 AWS `config`文件中定义并使用`cdk`命令`--profile`选项指定的命名配置文件。 + 标准 AWS `config`文件的`[default]`部分。 除了在该`[default]`部分中指定 AWS 身份验证和区域外，您还可以添加一个或多个`[profile ]`部分，其中``是配置文件的名称。有关命名配置文件的更多信息，请参阅《* AWS 软件开发工具包和工具参考指南*》[中的](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)共享配置和凭据文件。 标准 AWS `config`文件位于 `~/.aws/config` (macOS/Linux) 或 `%USERPROFILE%\.aws\config` (Windows)。有关详细信息和备用[位置，请参阅《* AWS 软件开发工具包和工具参考指南*》](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)中的共享配置和凭证文件的位置 合成过程中会使用您在 AWS CDK 应用程序中使用堆栈的`env`属性指定的环境。它用于生成特定环境的 AWS CloudFormation 模板，在部署期间，它会覆盖由上述方法之一指定的账户或区域。有关更多信息，请参阅 AWS CDK [ 的](environments.md)环境。 **注意** AWS CDK 使用与其他 AWS 工具和 SDK（包括[AWS 命令行界面）相同的源文件中的证书。](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)但是， AWS CDK 的行为可能与这些工具略有不同。它使用 AWS 软件开发工具包 JavaScript 进行幕后操作。有关为的 AWS 软件开发工具包设置凭证的完整详细信息 JavaScript，请参阅[设置证书](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials.html)。 您可以选择使用 `--role-arn`（或 `-r`）选项来指定应该用于部署的 IAM 角色的 ARN。此角色必须由所使用的 AWS 账户担任。 ## 指定应用程序命令 CDK CLI 的许多功能需要合成一个或多个 AWS CloudFormation 模板，这反过来又需要运行您的应用程序。 AWS CDK 支持以多种语言编写的程序。因此，它使用配置选项来指定运行应用程序所需的确切命令。可通过以下两种方式指定此选项。 首先，也是最常见的，可以使用文件 `cdk.json` 中的 `app` 密钥进行指定。它位于您的 AWS CDK 项目的主目录中。使用 `cdk init` 创建新项目时，CDK CLI 会提供相应的命令。例如，这是`cdk.json`来自一个新 TypeScript 项目的内容。 ``` { "app": "npx ts-node bin/hello-cdk.ts" } ``` 尝试运行应用程序时，CDK CLI 会在当前工作目录中查找 `cdk.json`。因此，您可以在项目的主目录中保持 Shell 打开状态以发出 CDK CLI 命令。 如果在 `./cdk.json` 中找不到应用程序密钥，CDK CLI 还会在 `~/.cdk.json`（即在主目录中）中查找该密钥。如果您通常使用相同语言的 CDK 代码，则在此处添加应用程序命令会很有用。 如果您位于其他目录中，或者要使用 `cdk.json` 之外的命令运行应用程序，请使用 `--app`（或 `-a`）选项进行指定。 ``` cdk --app "npx ts-node bin/hello-cdk.ts" ls ``` 部署时，您还可以将包含合成云程序集（例如 `cdk.out`）的目录指定为 `--app` 的值。指定的堆栈是从此目录部署的；应用程序不是合成的。 ## 指定堆栈 许多 CDK CLI 命令（例如 `cdk deploy`）都适用于应用程序中定义的堆栈。如果应用程序只包含一个堆栈，则当您未明确指定堆栈时，CDK CLI 会假设您指的是该堆栈。 否则，您必须指定要使用的堆栈。您可以通过在命令行上按 ID 单独指定所需的堆栈来实现此目的。请注意，ID 是实例化堆栈时第二个参数指定的值。 ``` cdk synth PipelineStack LambdaStack ``` 您也可以使用通配符来指定与模式匹配的 ID。 + `?` 匹配任何单个字符 + `*` 匹配任意数量的字符（`*` 单独匹配所有堆栈） + `**` 匹配层次结构中的所有内容 您也可以使用 `--all` 选项来指定所有堆栈。 如果应用程序使用 [CDK 管线](cdk-pipeline.md)，则 CDK CLI 会将堆栈和阶段理解为一个层次结构。此外，`--all` 选项和 `*` 通配符仅匹配顶级堆栈。要匹配所有堆栈，请使用 `**`。也可以使用 `**` 来表示特定层次结构下的所有堆栈。 使用通配符时，请用引号将模式括起来，或者使用 `\` 转义通配符。如果不这样做，Shell 可能会尝试将模式扩展为当前目录中的文件名。在最好的情况下，后果只是您未达到预期成果；但在最坏的情况下，您可能部署原本不打算部署的堆栈。在 Windows 上，这并不是绝对必要的，因为 `cmd.exe` 不会扩展通配符，但还是不错的做法。 ``` cdk synth "*Stack" # PipelineStack, LambdaStack, etc. cdk synth 'Stack?' # StackA, StackB, Stack1, etc. cdk synth \* # All stacks in the app, or all top-level stacks in a CDK Pipelines app cdk synth '**' # All stacks in a CDK Pipelines app cdk synth 'PipelineStack/Prod/**' # All stacks in Prod stage in a CDK Pipelines app ``` **注意** 您指定堆栈的顺序不一定是处理堆栈的顺序。CDK CLI 在决定处理堆栈的顺序时会考虑堆栈之间的依赖关系。例如，假设一个堆栈使用另一个堆栈生成的值（例如第二个堆栈中定义的资源的 ARN）。在这种情况下，由于这种依赖关系，第二个堆栈会先于第一个堆栈合成。您可以使用堆栈的 ` [addDependency()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#addwbrdependencytarget-reason) ` 方法在堆栈之间手动添加依赖关系。 ## 引导你的 AWS 环境 使用 CDK 部署堆栈需要配置特殊的专用 AWS CDK 资源。`cdk bootstrap` 命令会为您创建必要的资源。只有在部署需要这些专用资源的堆栈时，才需要引导。有关详细信息，请参阅 [AWS CDK 引导](bootstrapping.md)。 ``` cdk bootstrap ``` 如果在没有参数的情况下发出（如下所示），则 `cdk bootstrap` 命令会合成当前应用程序并引导其堆栈将部署到的环境。如果应用程序包含与环境无关的堆栈（未明确指定环境），则会引导默认账户和区域，或者使用 `--profile` 指定的环境。 在应用程序之外，您必须明确指定要引导的环境。您也可以这样做来引导应用程序或本地 AWS 配置文件中未指定的环境。您必须为指定的账户和区域配置凭证（例如，在 `~/.aws/credentials` 中）。您可以指定包含所需凭证的配置文件。 ``` cdk bootstrap / # e.g. cdk bootstrap 1111111111/us-east-1 cdk bootstrap --profile test 1111111111/us-east-1 ``` **重要** 部署此类堆栈的每个环境（account/region 组合）都必须单独启动。 您可能会因 AWS CDK 在引导资源中存储的内容而产生 AWS 费用。此外，如果您使用`--bootstrap-customer-key`，将创建 AWS KMS 密钥，这也会对每个环境产生费用。 **注意** 默认情况下，早期版本的引导模板会创建 KMS 密钥。为避免产生费用，请使用 `--no-bootstrap-customer-key` 重新引导。 **注意** CDK CLI v2 不支持 CDK v1 中默认使用的原始引导模板（称为旧版模板）。 **重要** 现代引导模板有效地向`--trust`列表中的任何 AWS 账户授`--cloudformation-execution-policies`予了隐含的权限。默认情况下，这会扩展对引导账户中任何资源的读取和写入权限。请务必使用您熟悉的策略和可信账户来[配置引导堆栈](bootstrapping-customizing.md)。 ## 创建新应用程序 要创建新应用程序，请为其创建一个目录，然后在该目录内发出 `cdk init`。 ``` mkdir my-cdk-app cd my-cdk-app cdk init