這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS CDK CLI 參考 AWS 雲端開發套件 (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 ``` **提示** 如果您定期使用多個版本的 AWS CDK，請考慮在個別 CDK 專案中安裝相符的 CDK CLI 版本。若要這樣做，`-g`請省略 `npm install`命令中的 。然後使用 `npx aws-cdk` 來叫用它。如果存在本機版本，這會執行本機版本，如果不存在，則會回復為全域版本。 ## CDK CLI 命令 所有 CDK CLI 命令都以 開頭`cdk`，後面接著子命令 (`list`、`deploy`、 `synthesize`等）。有些子命令具有相當於 的較短版本 `ls`(`synth`、 等）。選項和引數會依任何順序遵循 子命令。 如需所有子命令、選項和引數的說明，請參閱 [AWS CDK CLI 命令參考](ref-cli-cmd.md)。 ## 指定選項及其值 命令列選項以兩個連字號 () 開頭`--`。有些常用選項具有以單一連字號開頭的單一字母同義詞 （例如， `--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 CLI 版本`cdk version`的問題。在請求支援時提供此資訊。 ## 版本報告 為了深入了解 AWS CDK 的使用方式， AWS CDK 應用程式所使用的建構會使用識別為 的資源進行收集和報告` AWS::CDK::Metadata`。若要進一步了解，請參閱[設定 AWS CDK 用量資料報告](usage-data.md)。 ## 使用 進行身分驗證 AWS 您可以透過不同方式設定 AWS 資源的程式設計存取，具體取決於環境和您可用的 AWS 存取。 若要選擇您的身分驗證方法並為 CDK CLI 設定，請參閱[設定 AWS CDK CLI 的安全登入資料](configure-access.md)。 對於未獲得其雇主身分驗證方法的本機開發新使用者，建議的方法為設定 AWS IAM Identity Center。此方法包括安裝 AWS CLI 以簡化組態，以及定期登入 AWS 存取入口網站。如果您選擇此方法，您的環境應該在您完成 * AWS SDKs和工具參考指南*中的 [IAM Identity Center 身分驗證](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html)程序後包含下列元素： + AWS CLI，您用來在執行應用程式之前啟動 AWS 存取入口網站工作階段。 + [共用 AWS 組態檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)，其`[default]`設定檔具有一組可從 AWS CDK 參考的組態值。若要尋找此檔案的位置，請參閱 * AWS SDKs和工具參考指南*中的[共用檔案的位置](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)。 + 共用`config`檔案會設定[區域](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)設定。這會設定 AWS CDK 和 CDK CLI 用於 AWS 請求的預設 AWS 區域。 + CDK CLI 會使用設定檔的 [SSO 字符提供者組態](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile)，在傳送請求至 之前取得憑證 AWS。此`sso_role_name`值是連接至 IAM Identity Center 許可集的 IAM 角色，應允許存取您應用程式中使用 AWS 的服務。 下列範例`config`檔案顯示使用 SSO 權杖提供者組態設定的預設設定檔。設定檔`sso_session`的設定是指具名[`sso-session`區段](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session)。`sso-session` 區段包含啟動 AWS 存取入口網站工作階段的設定。 ``` [default] sso_session = sso_account_id = <111122223333> sso_role_name = region = output = [sso-session ] sso_region = sso_start_url = sso_registration_scopes = sso:account:access ``` ### 啟動 AWS 存取入口網站工作階段 存取 AWS 服務之前，您需要作用中的 AWS 存取入口網站工作階段，CDK CLI 才能使用 IAM Identity Center 身分驗證來解析登入資料。視您設定的工作階段長度而定，您的存取最終會過期，而 CDK CLI 將遇到身分驗證錯誤。在 CLI AWS 中執行下列命令以登入 AWS 存取入口網站。 ``` aws sso login ``` 如果您的 SSO 字符提供者組態使用具名描述檔而非預設描述檔，則命令為 `aws sso login --profile `。使用 `--profile`選項或 `AWS_PROFILE`環境變數發出`cdk`命令時，也請指定此設定檔。 若要測試您是否已經有作用中的工作階段，請執行下列 CLI AWS 命令。 ``` aws sts get-caller-identity ``` 對此命令的回應，應報告共用 `config` 檔案中設定的 IAM Identity Center 帳戶和許可集合。 **注意** 如果您已有作用中的 AWS 存取入口網站工作階段並執行 `aws sso login`，則不需要提供登入資料。 登入程序可能會提示您允許 CLI AWS 存取您的資料。由於 AWS CLI 建置在適用於 Python 的 SDK 之上，因此許可訊息可能包含`botocore`名稱的變化。 ## 指定區域和其他組態 CDK CLI 需要知道您要部署到 AWS 的區域，以及如何進行身分驗證 AWS。部署操作和在合成期間擷取內容值時需要此值。您的帳戶和區域共同構成*環境*。 可以使用環境變數或在組態檔案中指定區域。這些是 CLI AWS 和 AWS SDKs 等其他 AWS 工具所使用的相同變數和檔案。CDK CLI 會依下列順序尋找此資訊。 + `AWS_DEFAULT_REGION` 環境變數。 + 標準 AWS `config`檔案中定義的具名設定檔，並使用 `cdk` 命令上的 `--profile`選項指定。 + 標準 AWS `config`檔案的 `[default]`區段。 除了在 `[default]`區段中指定 AWS 身分驗證和區域之外，您也可以新增一或多個`[profile ]`區段，其中 ``是設定檔的名稱。如需具名設定檔的詳細資訊，請參閱 * AWS SDKs * [和工具參考指南中的共用組態和登入資料檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。 標準 AWS `config`檔案位於 `~/.aws/config`(macOS/Linux) 或 `%USERPROFILE%\.aws\config`(Windows)。如需詳細資訊和替代位置，請參閱 * AWS SDKs * [和工具參考指南中的共用組態和登入資料檔案的位置](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) 您在 AWS CDK 應用程式中使用堆疊`env`屬性指定的環境會在合成期間使用。它用於產生環境特定的 AWS CloudFormation 範本，在部署期間，它會覆寫上述方法之一指定的帳戶或區域。如需詳細資訊，請參閱 [AWS CDK 的環境](environments.md)。 **注意** AWS CDK 使用與其他 AWS 工具和 SDKs 相同的來源檔案的登入資料，包括 [AWS 命令列界面](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)。不過， AWS CDK 的行為可能與這些工具稍有不同。它在幕後使用適用於 JavaScript 的 AWS SDK。如需設定適用於 JavaScript 的 AWS SDK 登入資料的完整詳細資訊，請參閱[設定登入資料](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials.html)。 您可以選擇性地使用 `--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-pipeline.md)，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 ``` **注意** 您指定堆疊的順序不一定是處理堆疊的順序。在決定處理堆疊的順序時，CDK CLI 會考慮堆疊之間的相依性。例如，假設一個堆疊使用另一個堆疊產生的值 （例如第二個堆疊中定義的資源 ARN)。在此情況下，由於此相依性，第二個堆疊會在第一個堆疊之前合成。您可以使用堆疊的 ` [addDependency()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#addwbrdependencytarget-reason) `方法，在堆疊之間手動新增相依性。 ## 引導您的 AWS 環境 使用 CDK 部署堆疊需要佈建特殊的專用 AWS CDK 資源。`cdk bootstrap` 命令會為您建立必要的資源。只有在部署需要這些專用資源的堆疊時，才需要引導。如需詳細資訊，請參閱 [AWS CDK 引導](bootstrapping.md)。 ``` cdk bootstrap ``` 如果在沒有引數的情況下發出，如下所示，`cdk bootstrap`命令會合成目前的應用程式，並引導其堆疊將部署到的環境。如果應用程式包含與環境無關的堆疊，但未明確指定環境、預設帳戶和區域已引導，或使用 指定的環境`--profile`。 在應用程式外部，您必須明確指定要引導的環境。您也可以這樣做來引導未在應用程式或本機 AWS 設定檔中指定的環境。必須針對指定的帳戶和區域設定登入資料 （例如，在 中`~/.aws/credentials`)。您可以指定包含所需登入資料的設定檔。 ``` cdk bootstrap / # e.g. cdk bootstrap 1111111111/us-east-1 cdk bootstrap --profile test 1111111111/us-east-1 ``` **重要** 您部署這類堆疊的每個環境 （帳戶/區域組合） 必須分別引導。 您可能會因為 AWS CDK 在引導的資源中存放的內容而產生 AWS 費用。此外，如果您使用 `--bootstrap-customer-key`，將會建立 AWS KMS 金鑰，這也會產生每個環境的費用。 **注意** 早期版本的引導範本預設會建立 KMS 金鑰。為了避免產生費用，請使用 重新引導`--no-bootstrap-customer-key`。 **注意** CDK CLI v2 不支援原始引導範本，稱為舊版範本，預設會與 CDK v1 搭配使用。 **重要** 現代引導範本會有效地將 隱含的許可授予`--trust`清單中`--cloudformation-execution-policies`的任何 AWS 帳戶。根據預設，這會擴展讀取和寫入引導帳戶中任何資源的許可。請務必使用您熟悉的政策和信任帳戶來[設定引導堆疊](bootstrapping-customizing.md)。 ## 建立新的應用程式 若要建立新的應用程式，請為其建立目錄，然後在目錄中發出 `cdk init`。 ``` mkdir my-cdk-app cd my-cdk-app cdk init