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

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

AWS CDK 工具包（cdk命令）

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

该 AWS CDK 工具包与 Node Package Manager 一起安装。在大多数情况下，我们建议在全球范围内进行安装。

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

工具包命令

所有 CDK Toolkit 命令都以开头cdk，后面是子命令（listsynthesize、deploy、等）。有些子命令具有等效的较短版本（lssynth、等）。选项和参数按任意顺序跟在子命令之后。

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

指定选项及其值

命令行选项以两个连字符 () -- 开头。一些常用的选项具有以单个连字符开头的单字母同义词（例如，--app具有同义词）。-a AWS CDK Toolkit 命令中选项的顺序并不重要。

所有选项都接受一个值，该值必须位于选项名称之后。该值可以用空格或等号=与名称分隔。以下两个选项是等效的。

--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 Toolkit 帮助中注明这些内容是有[array]键入的。例如：

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

内置帮助

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

cdk --help

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

cdk deploy --help

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

版本报告

为了深入了解 AWS CDK 是如何使用的， AWS CDK 应用程序使用的构造是通过使用标识为AWS::CDK::Metadata的资源来收集和报告的。此资源已添加到 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 编码、前缀编码列表。

要选择退出版本报告，请使用以下方法之一：

使用进行身份验证 AWS

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

要选择您的身份验证方法并针对 CDK Toolkit 进行配置，请参阅 AWS SDK 和工具参考指南中的身份验证和访问权限。

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

启动 AWS 访问门户会话

在访问之前 AWS 服务，您需要对 CDK Toolkit 进行有效的 AWS 访问门户会话，才能使用 IAM Identity Center 身份验证来解析证书。根据您配置的会话时长，您的访问权限最终将过期，CDK Toolkit 将遇到身份验证错误。在中运行以下命令登录 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 Toolkit 需要知道您要部署到的 AWS 区域以及如何进行 AWS身份验证。这是部署操作和合成期间检索上下文值所必需的。您的账户和地区共同构成了环境。

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

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

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

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

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

指定应用程序命令

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

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

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

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

如果找不到应用程序密钥，CDK Toolkit 还会在~/.cdk.json（即您的主目录中）中./cdk.json查找该密钥。如果您通常使用相同语言的 CDK 代码，则在此处添加 app 命令会很有用。

如果您位于其他目录中，或者要使用中以外的命令运行应用程序cdk.json，请使用--app（或-a）选项进行指定。

cdk --app "npx ts-node bin/hello-cdk.ts" ls

部署时，您还可以将包含合成云程序集的目录（例如）指定为的值。cdk.out --app指定的堆栈是从此目录部署的；应用程序不是合成的。

指定堆栈

许多 CDK Toolkit 命令（例如cdk deploy）都适用于应用程序中定义的堆栈。如果您的应用程序仅包含一个堆栈，那么如果您没有明确指定堆栈，CDK Toolkit 会假设您的意思是那个堆栈。

否则，您必须指定要使用的堆栈。为此，可以在命令行中按 ID 单独指定所需的堆栈。回想一下，ID 是实例化堆栈时第二个参数指定的值。

cdk synth PipelineStack LambdaStack

您也可以使用通配符来指定与模式匹配的 ID。

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

如果你的应用程序使用 CDK Pipelines，CDK 工具包会将你的堆栈和阶段理解为一个层次结构。此外，该--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命令会为您创建必要的资源。只有在部署需要这些专用资源的堆栈时，才需要引导。有关详细信息，请参阅 正在引导。

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，则会创建 AWS KMS 密钥，这也会对每个环境产生费用。

创建新应用程序

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

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

支持的语言（语言）有：

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

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

列出堆栈

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

cdk list
cdk ls

如果您的应用程序包含 CDK Pipelines 堆栈，CDK Toolkit 会根据堆栈名称在管道层次结构中的位置将堆栈名称显示为路径。（例如PipelineStackPipelineStack/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 模板。

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

因此，CDK Toolkit 允许您通过在命令中添加--no-rollback来禁用回滚功能。cdk deploy使用此标志，失败的部署不会被回滚。相反，在出现故障的资源之前部署的资源会保留在原处，而下一次部署则从出现故障的资源开始。等待部署的时间将大大减少，而将更多的时间花在开发基础架构上。

热交换

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

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

观看模式

CDK Toolkit 的监视模式（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 参数

该 AWS CDK 工具包支持在部署时指定 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

与安全相关的更改

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

cdk deploy --require-approval 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 Toolkit 命令行标志的默认值可以存储在项目cdk.json.cdk.json文件中或用户目录的文件中。以下是按字母顺序对支持的配置设置的引用。