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

AWS CDK CLI 参考

AWS Cloud Development Kit (AWS CDK) 命令行界面（AWS CDK CLI）也称为 CDK Toolkit，是与 AWS CDK 应用程序进行交互的主要工具。它执行您的应用程序，查询您定义的应用程序模型，并生成和部署由 AWS CDK 生成的 AWS CloudFormation 模板。它还提供了其他可用于创建和使用 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 开头，后跟子命令（list、synthesize、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 CLI 帮助中注明这些选项具有 [array] 类型。例如：

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

内置帮助

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

cdk --help

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

cdk deploy --help

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

版本报告

为了深入了解如何使用 AWS CDK，通过使用标识为 AWS::CDK::Metadata 的资源来收集和报告 AWS CDK 应用程序使用的构造。此资源已添加到 AWS CloudFormation 模板中，可以轻松查看。此信息还可供 AWS 使用，以便使用存在已知安全性或可靠性问题的构造来识别堆栈。它还可用于与用户联系以提供重要信息。

默认情况下，AWS CDK 会报告堆栈中使用的以下 NPM 模块中的构造的使用情况：

AWS::CDK::Metadata 资源看起来如下所示。

CDKMetadata:
  Type: "AWS::CDK::Metadata"
  Properties:
    Analytics: "v2:deflate64:H4sIAND9SGAAAzXKSw5AMBAA0L1b2PdzBYnEAdio3RglglY60zQi7u6TWL/XKmNUlxeQSOKwaPTBqrNhwEWU3hGHiCzK0dWWfAxoL/Fd8mvk+QkS/0X6BdjnCdgmOOQKWz+AqqLDt2Y3YMnLYWwAAAA="

Analytics 属性是堆栈中构造的 gzip、base64 编码、前缀编码列表。

选择退出版本报告

您可以通过使用 CDK CLI 或配置项目的 cdk.json 文件来选择退出版本报告。

使用 AWS 进行身份验证

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

要选择您的身份验证方法并针对 CDK CLI 进行配置，请参阅为 AWS CDKCLI 配置安全凭证。

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

开始 AWS 访问门户会话

在访问 AWS 服务 之前，您需要有活动的 AWS 访问门户会话，以便 CDK CLI 使用 IAM Identity Center 身份验证来解析凭证。根据配置的会话时长，访问权限最终将过期，并且 CDK CLI 将遇到身份验证错误。要登录 AWS 访问门户，请在 AWS CLI 中运行以下命令。

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）以及各种 AWS CLI SDK 使用的变量和文件相同。CDK CLI 会按以下顺序查找此信息。

除了在 [default] 部分中指定 AWS 身份验证和区域外，您还可以添加一个或多个 [profile NAME] 部分，其中 NAME 是配置文件的名称。有关更多信息和命名配置文件，请参阅《AWS SDKs and Tools Reference Guide》中的 Shared config and credentials files。

标准 AWS config 文件位于 ~/.aws/config（macOS/Linux）或 %USERPROFILE%\.aws\config（Windows）。有关详细信息和备用位置，请参阅《AWS SDKs and Tools Reference Guide》中的 Location of the shared config and credentials files。

合成过程中会使用您在 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 init 创建新项目时，CDK CLI 会提供相应的命令。例如，以下是来自全新 TypeScript 项目的 cdk.json。

{
  "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 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 应用程序中堆栈的 ID 列表，请输入以下等效命令之一：

cdk list
cdk ls

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

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

添加 --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 部署，请在 cdk watch 中添加 --no-hotswap 标志。

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 文件中。以下是按字母顺序对支持的配置设置的引用。