AWS CDK CLI 参考

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

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

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

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

AWS Cloud Development Kit (AWS CDK) 命令行界面 (AWS CDK CLI)，也称为 CDK Toolkit，是与您的 AWS CDK 应用程序交互的主要工具。它执行您的应用程序，查询您定义的应用程序模型，并生成和部署由生成的 AWS CloudFormation 模板。 AWS CDK它还提供了其他可用于创建和处理 AWS CDK 项目的功能。本主题包含有关 CDK 的常见用例的信息 CLI.

CDK CLI 与 Node Package Manager 一起安装。大多数情况下，我们建议在全局范围内安装。

npm install -g aws-cdk             # install latest version
npm install -g aws-cdk@X.YY.Z      # install specific version

CDK CLI 命令

全部 CDK CLI 命令以开头cdk，后面是子命令（listsynthesize、deploy、等）。一些子命令具有等效的简短版本（ls、synth 等）。选项和参数按任意顺序跟在子命令之后。

有关所有子命令、选项和参数的说明，请参阅 AWS CDK CLI   命令参考。

指定选项及其值

命令行选项以两个连字符 (--) 开头。一些常用的选项具有以单个连字符开头的单字母同义词（例如，--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 中打[array]字的 CLI 救命。例如：

cdk bootstrap --tags costCenter=0123 --tags responsibleParty=jdoe

内置帮助

CDK CLI 已集成帮助。您可以通过发出以下命令来查看有关实用程序的一般帮助和所提供的子命令列表：

cdk --help

要查看特定子命令（例如 deploy）的帮助，请在 --help 标志之前指定该子命令。

cdk deploy --help

显示 CDK 版本的问题 cdk version CLI。 在请求支持时提供此信息。

版本报告

为了深入了解 AWS CDK 是如何使用的， AWS CDK 应用程序使用的构造是通过使用标识为AWS::CDK::Metadata的资源来收集和报告的。要了解更多信息，请参阅 配置 AWS CDK 使用情况数据报告。

使用进行身份验证 AWS

您可以通过不同的方式配置对 AWS 资源的编程访问权限，具体取决于环境和可用的 AWS 访问权限。

选择您的身份验证方法并将其配置为 CDK CLI，请参阅 为配置安全证书 AWS CDK CLI。

对于在本地开发的新用户，如果雇主没有向他们提供身份验证方法，推荐的方法是设置 AWS IAM Identity Center。此方法包括安装 AWS CLI 以便于配置和定期登录 AWS 访问门户。如果您选择此方法，则在完成AWS SDKs 和工具参考指南中的 IAM Identity Center 身份验证程序后，您的环境应包含以下元素：

启动 AWS 访问门户会话

在访问之前 AWS 服务，您需要为 CDK 开 AWS 启有效的访问门户会话 CLI 使用 IAM 身份中心身份验证来解析证书。根据您配置的会话时长，您的访问权限最终将过期，CDK CLI 将遇到身份验证错误。在中运行以下命令登录 AWS CLI AWS 访问门户。

aws sso login

如果 SSO 令牌提供程序配置使用命名配置文件而不是默认配置文件，则命令为 aws sso login --profile NAME。使用 --profile 选项或 AWS_PROFILE 环境变量发出 cdk 命令时，也应指定此配置文件。

要测试是否已有活动会话，请运行以下 AWS CLI 命令。

aws sts get-caller-identity

对此命令的响应应该报告共享 config 文件中配置的 IAM Identity Center 账户和权限集。

指定区域和其他配置

CDK CLI 需要知道您要部署到的 AWS 区域以及如何进行身份验证 AWS。这是部署操作以及合成期间检索上下文值所必需的。您的账户和区域共同构成了环境。

您可以使用环境变量或在配置文件中指定区域。这些变量和文件与其他 AWS 工具（例如和各种）使用的变量 AWS CLI 和文件相同 AWS SDKs。CDK CLI 按以下顺序查找此信息。

除了在该[default]部分中指定 AWS 身份验证和区域外，您还可以添加一个或多个[profile NAME]部分，其中NAME是配置文件的名称。有关命名配置文件的更多信息，请参阅《工具参考指南》和《工具参考指南》中的共享配置AWS SDKs 和凭据文件。

标准 AWS config文件位于 ~/.aws/config (macOS/Linux) 或 %USERPROFILE%\.aws\config (Windows)。有关详细信息和其他位置，请参阅《工具参考指南》和《工具参考指南》中的共享配置AWS SDKs 和凭据文件的位置

合成过程中会使用您在 AWS CDK 应用程序中使用堆栈env属性指定的环境。它用于生成特定于环境的 AWS CloudFormation 模板，在部署期间，它会覆盖通过上述方法之一指定的账户或区域。有关更多信息，请参阅 的环境 AWS CDK。

您可以选择使用 --role-arn（或 -r）选项来指定应该用于部署的 IAM 角色的 ARN。此角色必须由所使用的 AWS 账户担任。

指定应用程序命令

CDK 的许多功能 CLI 需要合成一个或多个 AWS CloudFormation 模板，这反过来又需要运行您的应用程序。 AWS CDK 支持用多种语言编写的程序。因此，它使用配置选项来指定运行应用程序所需的确切命令。可通过以下两种方式指定此选项。

首先，也是最常见的，可以使用文件 cdk.json 中的 app 密钥进行指定。它位于 AWS CDK 项目的主目录中。CDK CLI 在使用创建新项目时提供了相应的命令cdk init。例如，以下是cdk.json来自一个新 TypeScript 项目的内容。

{
  "app": "npx ts-node bin/hello-cdk.ts"
}

CDK CLI 尝试运行应用程序时，会在当前工作目录cdk.json中查找。因此，你可以在项目的主目录中打开一个 shell 来发布 CDK CLI 命令。

CDK CLI 如果找不到应用程序密钥，还会在~/.cdk.json（即你的主目录中）中查找它./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

您也可以使用通配符来指定与模式 IDs 相匹配的内容。

您也可以使用 --all 选项来指定所有堆栈。

如果你的应用程序使用 CDK Pipelines，那么 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

引导您的环境 AWS

使用 CDK 部署堆栈需要配置特殊的专用 AWS CDK 资源。cdk bootstrap 命令会为您创建必要的资源。只有在部署需要这些专用资源的堆栈时，才需要引导。有关详细信息，请参阅AWS CDK 自力更生。

cdk bootstrap

如果在没有参数的情况下发出（如下所示），则 cdk bootstrap 命令会合成当前应用程序并引导其堆栈将部署到的环境。如果应用程序包含与环境无关的堆栈（未明确指定环境），则会引导默认账户和区域，或者使用 --profile 指定的环境。

在应用程序之外，您必须明确指定要引导的环境。您也可以这样做来引导未在您的应用程序或本地 AWS 配置文件中指定的环境。您必须为指定的账户和区域配置凭证（例如，在 ~/.aws/credentials 中）。您可以指定包含所需凭证的配置文件。

cdk bootstrap ACCOUNT-NUMBER/REGION # e.g.
cdk bootstrap 1111111111/us-east-1
cdk bootstrap --profile test 1111111111/us-east-1

您可能会因为在引导资源中 AWS CDK 存储的内容而产生 AWS 费用。此外，如果您使用 -bootstrap-customer-key，则会创建 Amazon KMS 密钥，这也会导致每个环境都产生费用。

创建新应用程序

要创建新应用程序，请为其创建一个目录，然后在该目录内发出 cdk init。

mkdir my-cdk-app
cd my-cdk-app
cdk init TEMPLATE --language LANGUAGE

支持的语言 (LANGUAGE) 有：

TEMPLATE是一个可选的模板。如果所需的模板是 app（默认值），则可以省略它。可用的模板包括：

模板使用项目文件夹的名称来生成新应用程序中的文件和类的名称。

列出堆栈

要查看 AWS CDK 应用程序 IDs 中的堆栈列表，请输入以下等效命令之一：

cdk list
cdk ls

如果你的应用程序包含 CDK Pipelines 堆栈，那么 CDK CLI 根据堆栈名称在管道层次结构中的位置将堆栈名称显示为路径。（例如 PipelineStack、PipelineStack/Prod 和 PipelineStack/Prod/MyService。）

如果您的应用程序包含许多堆栈，则可以指定要列出的堆栈 IDs 的全部或部分堆栈。有关更多信息，请参阅 指定堆栈。

添加--long标志以查看有关堆栈的更多信息，包括堆栈名称及其环境（AWS 账户和区域）。

合成堆栈

该cdk synthesize命令（几乎总是缩写synth）将应用程序中定义的堆栈合成一个 CloudFormation 模板。

cdk synth         # if app contains only one stack
cdk synth MyStack
cdk synth Stack1 Stack2
cdk synth "*"     # all stacks in app

有关所有可用选项，请参阅 cdk synth --help。以下部分介绍了一些最常用的选项。

指定上下文值

使用 --context 或 -c 选项将运行时上下文值传递给 CDK 应用程序。

# specify a single context value
cdk synth --context key=value MyStack

# specify multiple context values (any number)
cdk synth --context key1=value1 --context key2=value2 MyStack

部署多个堆栈时，指定的上下文值通常会传递给所有堆栈。如果需要，可以通过在上下文值前面加上堆栈名称来为每个堆栈指定不同的值。

# different context values for each stack
cdk synth --context Stack1:key=value Stack2:key=value Stack1 Stack2

指定显示格式

默认情况下，合成后的模板以 YAML 格式显示。添加 --json 标志可改为以 JSON 格式显示。

cdk synth --json MyStack

指定输出目录

添加 --output (-o) 选项，将合成后的模板写入 cdk.out 以外的目录。

cdk synth --output=~/templates

部署堆栈

cdk deploy子命令将一个或多个指定的堆栈部署到您的账户。 AWS

cdk deploy        # if app contains only one stack
cdk deploy MyStack
cdk deploy Stack1 Stack2
cdk deploy "*"    # all stacks in app

有关所有可用选项，请参阅 cdk deploy --help。以下部分介绍了一些最有用的选项。

跳过合成

cdk deploy 命令通常会在部署之前合成应用程序的堆栈，以确保部署反映应用程序的最新版本。如果您知道自上次运行 cdk synth 以来没有更改过代码，则可以在部署时取消冗余合成步骤。为此，请在 --app 选项中指定项目的 cdk.out 目录。

cdk deploy --app cdk.out StackOne StackTwo

禁用回滚

AWS CloudFormation 能够回滚更改，从而实现原子部署。这意味着这些部署要么整体成功，要么整体失败。 AWS CDK 继承了此功能，因为它可以合成和部署 AWS CloudFormation 模板。

回滚可确保资源始终处于一致状态，这对于生产堆栈至关重要。但是，当您仍在开发基础设施时，有些故障是不可避免的，而回滚失败的部署可能会减慢速度。

出于这个原因，CDK CLI 允许您通过在cdk deploy命令中添加--no-rollback来禁用回滚。使用此标志时，失败的部署不会回滚。相反，在失败资源之前部署的资源会保留在原处，而下一次部署则从失败资源开始。等待部署的时间会更少，开发基础设施的时间会更多。

热交换

使用带的--hotswap标志cdk deploy尝试直接更新您的 AWS 资源，而不是生成 AWS CloudFormation 更改集并进行部署。如果无法进行热交换，则 AWS CloudFormation 部署将回退到部署。

目前，热交换支持 Lambda 函数、Step Functions 状态机和 Amazon ECS 容器映像。--hotswap 标志还会禁用回滚（即 --no-rollback）。

监视模式

CDK CLI的监视模式（cdk deploy --watch或cdk watch简称）会持续监视您的 CDK 应用程序的源文件和资产是否有更改。当检测到更改时，该模式会立即部署指定的堆栈。

默认情况下，这些部署使用 --hotswap 标志，该标志可快速跟踪对 Lambda 函数的更改的部署。 AWS CloudFormation 如果您更改了基础架构配置，它也会回退到通过部署。要cdk watch始终执行完整 AWS CloudFormation 部署，请将--no-hotswap标志添加到cdk watch。

cdk watch 在已执行部署时所做的任何更改都将合并到一个部署中，该部署会在进行中的部署完成后立即开始。

监视模式使用项目的 "watch" 中的 cdk.json 键来确定要监控哪些文件。默认情况下，这些文件是应用程序文件和资产，但可以通过修改 "watch" 键中的 "include" 和 "exclude" 条目来更改这些文件和资产。以下 cdk.json 文件显示了这些条目的示例。

{
  "app": "mvn -e -q compile exec:java",
  "watch": {
    "include": "src/main/**",
    "exclude": "target/*"
  }
}

cdk watch 在合成之前执行 cdk.json 中的 "build" 命令来构建应用程序。如果部署需要任何命令来构建或打包 Lambda 代码（或不在 CDK 应用程序中的任何其他内容），则可在此处添加。

Git 样式的通配符（* 和 **）可用于 "watch" 和 "build" 键。每个路径都是相对于 cdk.json 的父目录解释的。include 的默认值为 **/*，表示项目根目录中的所有文件和目录。exclude 是可选的。

指定 AWS CloudFormation 参数

CDK CLI 支持在部署时指定 AWS CloudFormation 参数。您可以在命令行上的 --parameters 标志后面提供这些信息。

cdk deploy MyStack --parameters uploadBucketName=UploadBucket

要定义多个参数，请使用多个 --parameters 标志。

cdk deploy MyStack --parameters uploadBucketName=UpBucket --parameters downloadBucketName=DownBucket

如果要部署多个堆栈，则可以为每个堆栈的每个参数指定不同的值。为此，请在参数名称前加上堆栈名称和冒号。否则，将相同的值传递给所有堆栈。

cdk deploy MyStack YourStack --parameters MyStack:uploadBucketName=UploadBucket --parameters YourStack:uploadBucketName=UpBucket

默认情况下， AWS CDK 会保留先前部署中的参数值，如果未明确指定，则在以后的部署中使用这些值。使用 --no-previous-parameters 标志可要求指定所有参数。

指定输出文件

如果您的堆栈声明了 AWS CloudFormation 输出，则这些输出通常会在部署结束时显示在屏幕上。要将输出写入 JSON 格式的文件中，请使用 --outputs-file 标志。

cdk deploy --outputs-file outputs.json MyStack

批准安全相关的更改

为了保护您免受影响安全状况的意外更改的影响，CDK CLI 在部署与安全相关的更改之前，会提示您批准这些更改。您可以指定需要批准的更改级别：

cdk deploy --require-approval LEVEL

LEVEL 的值可以是以下值之一：

也可以在 cdk.json 文件中配置该设置。

{
  "app": "...",
  "requireApproval": "never"
}

比较堆栈

该cdk diff命令将应用程序中定义的堆栈（及其依赖项）的当前版本与已部署的版本或已保存的 AWS CloudFormation 模板进行比较，并显示更改列表。

Stack HelloCdkStack
IAM Statement Changes
┌───┬──────────────────────────────┬────────┬──────────────────────────────┬──────────────────────────────┬───────────┐
│   │ Resource                     │ Effect │ Action                       │ Principal                    │ Condition │
├───┼──────────────────────────────┼────────┼──────────────────────────────┼──────────────────────────────┼───────────┤
│ + │ ${Custom::S3AutoDeleteObject │ Allow  │ sts:AssumeRole               │ Service:lambda.amazonaws.com │           │
│   │ sCustomResourceProvider/Role │        │                              │                              │           │
│   │ .Arn}                        │        │                              │                              │           │
├───┼──────────────────────────────┼────────┼──────────────────────────────┼──────────────────────────────┼───────────┤
│ + │ ${MyFirstBucket.Arn}         │ Allow  │ s3:DeleteObject*             │ AWS:${Custom::S3AutoDeleteOb │           │
│   │ ${MyFirstBucket.Arn}/*       │        │ s3:GetBucket*                │ jectsCustomResourceProvider/ │           │
│   │                              │        │ s3:GetObject*                │ Role.Arn}                    │           │
│   │                              │        │ s3:List*                     │                              │           │
└───┴──────────────────────────────┴────────┴──────────────────────────────┴──────────────────────────────┴───────────┘
IAM Policy Changes
┌───┬────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────┐
│   │ Resource                                               │ Managed Policy ARN                                     │
├───┼────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ + │ ${Custom::S3AutoDeleteObjectsCustomResourceProvider/Ro │ {"Fn::Sub":"arn:${AWS::Partition}:iam::aws:policy/serv │
│   │ le}                                                    │ ice-role/AWSLambdaBasicExecutionRole"}                 │
└───┴────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────┘
(NOTE: There may be security-related changes not in this list. See https://github.com/aws/aws-cdk/issues/1299)

Parameters
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3Bucket AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3BucketBF7A7F3F: {"Type":"String","Description":"S3 bucket for asset \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""}
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3VersionKey AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3VersionKeyFAF93626: {"Type":"String","Description":"S3 key for asset version \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""}
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/ArtifactHash AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392ArtifactHashE56CD69A: {"Type":"String","Description":"Artifact hash for asset \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""}

Resources
[+] AWS::S3::BucketPolicy MyFirstBucket/Policy MyFirstBucketPolicy3243DEFD
[+] Custom::S3AutoDeleteObjects MyFirstBucket/AutoDeleteObjectsCustomResource MyFirstBucketAutoDeleteObjectsCustomResourceC52FCF6E
[+] AWS::IAM::Role Custom::S3AutoDeleteObjectsCustomResourceProvider/Role CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092
[+] AWS::Lambda::Function Custom::S3AutoDeleteObjectsCustomResourceProvider/Handler CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184F
[~] AWS::S3::Bucket MyFirstBucket MyFirstBucketB8884501
 ├─ [~] DeletionPolicy
 │   ├─ [-] Retain
 │   └─ [+] Delete
 └─ [~] UpdateReplacePolicy
     ├─ [-] Retain
     └─ [+] Delete

要将应用程序的堆栈与现有部署进行比较，请执行以下操作：

cdk diff MyStack

要将应用的堆栈与已保存的 CloudFormation 模板进行比较，请执行以下操作：

cdk diff --template ~/stacks/MyStack.old MyStack

将现有资源导入到堆栈中

您可以使用cdk import命令将特定 AWS CDK 堆栈的资源置于 CloudFormation 的管理之下。如果您要迁移到堆栈 AWS CDK，或者要在堆栈之间移动资源或更改其逻辑 ID，则此功能非常有用。cdk import使用 CloudFormation 资源导入。请参阅可在此处导入的资源列表。

要将现有资源导入 AWS CDK 堆栈，请执行以下步骤：

此功能目前不支持将资源导入到嵌套堆栈中。

配置 (cdk.json)

许多 CDK 的默认值 CLI 命令行标志可以存储在项目cdk.json文件中，也可以存储在用户目录.cdk.json的文件中。以下是按字母顺序对支持的配置设置的引用。