這是 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 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 commands

全部 CDK CLI 命令以 開頭cdk，後面接著子命令 synthesize（list、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、--trust、--tags、 --parameters --plugin和 ，以指定多個值。這些會註明為在 中具有 [array] 類型 CDK CLI 說明。例如：

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 會使用識別為 的資源進行收集和報告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 屬性是堆疊中建構的 gziped、base64 編碼、字首編碼清單。

選擇退出版本報告

您可以使用 選擇退出版本報告 CDK CLI 或透過設定專案cdk.json的檔案。

使用 進行身分驗證 AWS

視環境和您可用的存取權而定，您可以透過不同方式設定 AWS 資源的程式設計 AWS 存取。

選擇您的身分驗證方法，並為 設定 CDK CLI，請參閱設定安全登入資料 AWS CDKCLI。

對於未由其雇主提供身分驗證方法的本機開發新使用者，建議方法是設定 AWS IAM Identity Center。此方法包括安裝 AWS CLI 以方便設定，以及定期登入 AWS 存取入口網站。如果您選擇此方法，您的環境應在完成 AWS SDKs和 工具參考指南 中的IAM身分中心身分驗證程序後包含下列元素：

啟動 AWS 存取入口網站工作階段

在存取 之前 AWS 服務，您需要 的作用中 AWS 存取入口網站工作階段 CDK CLI 使用 IAM Identity Center 身分驗證來解析憑證。視您設定的工作階段長度而定，您的存取權最終會過期，而 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 支援以各種語言撰寫的程式。因此，它使用組態選項來指定執行應用程式所需的確切命令。此選項可以透過兩種方式指定。

首先，而且最常用，它可以使用檔案 中的 app 金鑰來指定cdk.json。這是在您 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管道 ，則 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，則會建立AWSKMS金鑰，這也會產生每個環境的費用。

建立新的應用程式

若要建立新應用程式，請為其建立目錄，然後在目錄中發行 cdk init。

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

支援的語言 （LANGUAGE） 為：

TEMPLATE 是選用的範本。如果所需的範本是應用程式 ，則預設可以省略它。可用的範本包括：

範本會使用專案資料夾的名稱，為新應用程式中的檔案和類別產生名稱。

列出堆疊

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

cdk list
cdk ls

如果您的應用程式包含CDK管道堆疊，則 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 範本。

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

因此， CDKCLI 可讓您將 新增至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 會從 執行 "build"命令cdk.json，以在合成之前建置您的應用程式。如果您的部署需要任何命令來建置或封裝 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

核准安全相關變更

為了保護您免受影響您安全狀態的意外變更， 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命令，為 CloudFormation 特定 AWS CDK 堆疊在 管理下提供資源。如果您正在遷移至 AWS CDK，或在堆疊之間移動資源或變更其邏輯 ID，這會很有用。 cdk import會使用 CloudFormation 資源匯入 。請參閱此處可匯入的資源清單 。

若要將現有資源匯入 AWS CDK 堆疊，請遵循下列步驟：

此功能目前不支援將資源匯入巢狀堆疊。

組態 （cdk.json）

許多 的預設值 CDK CLI 命令列旗標可以存放在專案的cdk.json檔案中，或使用者目錄中的.cdk.json檔案中。以下是所支援組態設定的字母參考。