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

CDKCLI 命令

所有 CDK CLI命令都以 開頭cdk，後面接著子命令 (list、deploy、 synthesize等）。某些子命令具有較短的 版本 (synth、 ls等），相當於 。選項和引數會依任何順序遵循 子命令。

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

指定選項及其值

命令列選項以兩個連字號 (--) 開頭。有些常用選項具有以單一連字號開頭的單一字母同義詞 （例如， --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和 ，以指定多個值。這些會在 CDK CLI說明中註明為具有 [array]類型。例如：

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 CDKCLI。

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

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

在存取 之前 AWS 服務，您需要有效的 AWS 存取入口網站工作階段CLI，CDK 才能使用 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 cdk.json會在目前的工作目錄中CLI尋找 。因此，您可以在專案的主目錄中保持 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，則會建立 AWS KMS 金鑰，這也會產生每個環境的費用。

建立新的應用程式

若要建立新的應用程式，請為其建立目錄，然後在目錄中發出 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顯示為路徑。（例如，、 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 範本。

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

因此，CDK CLI可讓您透過將 --no-rollback新增至cdk deploy命令來停用轉返。使用此旗標時，不會復原失敗的部署。相反地，在失敗資源之前部署的資源會保留在原地，而下一個部署會從失敗的資源開始。您將花更少的時間等待部署，以及更多的時間開發基礎設施。

熱交換

使用 --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

核准安全相關變更

為了保護您免受影響安全狀態的意外變更，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 檔案中。以下是支援的組態設定的字母參考。