這是 AWS CDK v2 開發人員指南。較舊的 CDK V1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS CDK參考CLI

命 AWS Cloud Development Kit (AWS CDK) 令列介面 (AWS CDK CLI) 也稱為 CDKToolkit，是與 AWS CDK 應用程式互動的主要工具。它會執行您的應用程式、詢問您定義的應用程式模型，以及產生和部 AWS CloudFormation 署由. AWS CDK它還提供了其他有用於創建和使用 AWS CDK 項目的功能。本主題包含的常見使用案例的相關資訊CDKCLI。

會隨「節點 Package 管理員」CDK CLI 一起安裝。在大多數情況下，我們建議在全球範圍內安裝。

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

CDKCLI命令

所有CDKCLI指令都以開頭cdk，後面接著一個子指令 (listsynthesize、deploy、等等)。一些子命令有一個較短的版本（等等）lssynth，這是等價的。選項和引數以任何順序跟隨子命令。

如需所有子指令、選項和引數的描述，請參閱AWS CDKCLI指令參考。

指定選項及其值

指令行選項以兩個連字號 (--) 開頭。某些常用選項具有以單一連字號開頭的單一字母同義字 (例如，--app具有同-a義字)。CDKCLI命令中的選項順序並不重要。

所有選項都接受值，該值必須在選項名稱之後。該值可以通過空格或等號與名稱分隔=。以下兩個選項是相同的。

--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、、、和，以指定多個值。這些被註意為在CDKCLI幫助中[array]輸入。例如：

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

內建說明

CDKCLI已經集成了幫助。您可以通過發出以下命令來查看有關該實用程序的一般幫助以及提供的子命令列表：

cdk --help

例deploy如，若要查看特定子指令的說明，請在--help旗標前指定該指令。

cdk deploy --help

顯示cdk version的版本的問題CDKCLI。請求支援時提供此資訊。

版本報告

若要深入瞭解如何使 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 編碼的前綴編碼列表。

若要選擇退出版本報告，請使用下列其中一種方法：

使用驗證 AWS

您可以透過不同的方式設定 AWS 資源的程式設計存取，具體取決於環境和您可用的 AWS 存取權限。

若要選擇驗證方法並對其進行配置 CDKCLI，請參閱設定安全登入資料 AWS CDKCLI。

對於在本地開發的新用戶，誰沒有給他們的雇主認證的方法，推薦的方法是設置 AWS IAM Identity Center。此方法包括安裝以便 AWS CLI 於設定，以及定期登入 AWS 存取入口網站。如果您選擇此方法，則在您完成《AWS SDKs和工具參考指南》中的 IAMIdentity Center 驗證程序後，您的環境應包含下列元素：

啟動 AWS 存取入口網站會話

在存取之前 AWS 服務，您需要使用中存 AWS 取入口網站工作階段，CDKCLI才能使用 IAM Identity Center 驗證來解析認證。根據您配置的會話長度，您的訪問最終將過期，並且CDKCLI將遇到身份驗證錯誤。在中執行下列命令 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 帳戶和權限集。

指定地區和其他配置

CDKCLI需要知道您要部署到的 AWS 區域以及如何進行驗證 AWS。這是部署作業和在合成期間擷取內容值所需的。您的帳戶和區域共同構成了環境。

區域可以使用環境變量或在配置文件中指定。這些與其他 AWS 工具 (例如和各種工具) 所使用的變數 AWS CLI 和檔案相同 AWS SDKs。會依下列順序CDKCLI尋找此資訊。

除了在該[default]部分中指定 AWS 身份驗證和區域外，您還可以添加一個或多個[profile NAME]部分，其中 NAME 是設定檔的名稱。如需有關命名設定檔的詳細資訊，請參閱《工具參考指南》中的共用設定AWS SDKs和認證檔案。

標準 AWS config檔案位於 ~/.aws/config (MacOS /Linux) 或 %USERPROFILE%\.aws\config (視窗)。如需詳細資訊和替代位置，請參閱《工具參考指南》中的共用設定AWS SDKs和認證檔案的位置。

您在應用 AWS CDK 程序中通過使用堆棧的env屬性指定的環境將在合成過程中使用。它是用來產生環境特定的 AWS CloudFormation 範本，而在部署期間，它會覆寫上述方法之一所指定的帳戶或區域。如需詳細資訊，請參閱適用的環境 AWS CDK。

您可以選擇性地使用 --role-arn (或-r) 選項來指定應用於部署的IAM角色。ARN此角色必須由正在使用的 AWS 帳戶確定。

指定應用程式命令

許多功能都CDKCLI需要合成一個或多個 AWS CloudFormation 模板，這反過來又需要運行您的應用程序。 AWS CDK 支持以各種語言編寫的程序。因此，它使用配置選項來指定運行應用程序所需的確切命令。您可以透過兩種方式指定此選項。

首先，也是最常見的，它可以使用文件中的app密鑰來指定cdk.json。這是在你的 AWS CDK 項目的主目錄。使用建立新專案時，會CDKCLI提供適當的指令cdk init。例如，這是cdk.json來自一個新 TypeScript 項目。

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

嘗試運行您的應用程序時，會在當前工作目錄cdk.json中查CDKCLI找。因此，您可能會在項目的主目錄中保持 shell 打開以發出CDKCLI命令。

如果在中找不到應用程序密鑰，CDKCLI還會查找應用程序密鑰~/.cdk.json（即在您的主目錄中）./cdk.json。如果您通常使用相同語言的程式CDK碼，則在此處新增 app 指令會很有用。

如果您位於其他目錄中，或是要使用中指令以外的指令執行應用程式cdk.json，請使用 --app (或-a) 選項來指定它。

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

部署時，您也可以指定包含合成雲端組件的目錄，例如cdk.out，作為的--app值。指定的堆疊會從此目錄部署；應用程式不會合成。

指定堆疊

許多CDKCLI命令（例如cdk deploy）都適用於應用程序中定義的堆棧。如果您的應用程序只包含一個堆棧，則CDKCLI假設您的意思是，如果您沒有明確指定堆棧。

否則，您必須指定要使用的一個或多個堆疊。您可以通過在命令行上單獨指定 ID 所需的堆棧來完成此操作。回想一下，ID 是當你實例化堆棧的第二個參數指定的值。

cdk synth PipelineStack LambdaStack

您也可以使用萬用字元來指IDs定符合模式。

您也可以使用此選--all項來指定所有堆疊。

如果您的應用程序使用CDK管道，則會將您的堆棧和階段CDKCLI理解為層次結構。此外，--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命令將合成當前應用程序並啟動其堆棧將部署到的環境。如果應用程序包含與環境無關的堆棧（未明確指定環境），則默認帳戶和 Region 將被引導，或者使用. --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，則會建立AWSKMS金鑰，這也會產生每個環境的費用。

建立新的應用程式

要創建一個新的應用程序，為它創建一個目錄，然後，在目錄內，問題cdk init。

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

支持的語言（LANGUAGE) 是：

TEMPLATE 是一個可選的模板。如果所需的模板是 app，默認情況下，您可以省略它。可用的範本包括：

模板使用項目文件夾的名稱來生成新應用程序中的文件和類的名稱。

列出堆疊

若要查看應用程式中堆疊IDs的清單， AWS CDK 請輸入下列其中一個對等命令：

cdk list
cdk ls

如果您的應用程式包含 P CDKip eline 堆疊，則CDKCLI會根據堆疊在管線階層中的位置將堆疊名稱顯示為路徑。(例如，PipelineStackPipelineStack/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 範本。

回復可確保您的資源始終處於一致的狀態，這對於生產堆疊至關重要。不過，當您仍在開發基礎結構時，有些失敗是不可避免的，而復原失敗的部署可能會拖慢您的速度。

因此，CDKCLI可讓您透過新增--no-rollback至您的cdk deploy命令來停用復原。使用此旗標時，不會復原失敗的部署。相反地，在失敗資源之前部署的資源會保留在原位，而下一次部署會從失敗的資源開始。您將花費更少的時間等待部署和更多的時間開發您的基礎架構。

熱插拔

使用--hotswap旗標與可cdk deploy嘗試直接更新您的 AWS 資源，而不是產生 AWS CloudFormation 變更集並部署它。如果無法進行熱交換， AWS CloudFormation 部署會退回部署。

目前熱交換支援 Lambda 函數、Step Functions 狀態機器和 Amazon ECS 容器映像。該--hotswap標誌還禁用回滾（即暗示--no-rollback）。

手錶模式

CDKCLI的手錶模式（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從執行"build"命令cdk.json以在合成之前構建您的應用程序。如果您的部署需要任何命令來建置或封裝 Lambda 程式碼 (或CDK應用程式中沒有的其他任何項目)，請在此處新增。

Git 樣式萬用字元 (*和**) 都可以在和金鑰中使用。"watch" "build"每個路徑都會相對於的父目錄進行解譯cdk.json。的預設值include是**/*，表示專案根目錄中的所有檔案和目錄。 exclude是可選的。

指定 AWS CloudFormation 參數

CDKCLI支援在部署時指定 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

核准與安全性相關的變更

為了保護您不受影響安全狀態的意外變更，在部署安全性相關變更之前，會CDKCLI提示您核准安全性相關變更。您可以指定需要核准的變更層次：

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）

許多CDKCLI指令行旗標的預設值可以儲存在專cdk.json案的檔案或使用者目錄中的.cdk.json檔案中。以下是支援的組態設定的字母參照。