這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 部署 AWS CDK 應用程式 AWS 雲端開發套件 (AWS CDK) 部署是佈建基礎設施的程序 AWS。 ## AWS CDK 部署的運作方式 AWS CDK 利用 AWS CloudFormation 服務來執行部署。部署之前，您會合成 CDK 堆疊。這會為應用程式中的每個 CDK 堆疊建立 CloudFormation 範本和部署成品。部署是從本機開發機器或從*持續整合和持續交付 (CI/CD)* 環境啟動。在部署期間，資產會上傳至引導的資源，而 CloudFormation 範本會提交至 CloudFormation 來佈建您的 AWS 資源。 若要讓部署成功，需要下列項目： + AWS CDK 命令列界面 (AWS CDK CLI) 必須具備有效的許可。 + 必須引導 AWS 環境。 + AWS CDK 必須知道要上傳資產的引導資源。 ## CDK 部署的先決條件 您必須先完成下列操作，才能部署 AWS CDK 應用程式： + 設定 CDK CLI 的安全登入資料。 + 引導您的 AWS 環境。 + 為每個 CDK 堆疊設定 AWS 環境。 + 開發您的 CDK 應用程式。 **設定安全登入資料** 若要使用 CDK CLI 與 互動 AWS，您必須在本機電腦上設定安全登入資料。如需說明，請參閱[設定 AWS CDK CLI 的安全登入資料](configure-access.md)。 **引導您的 AWS 環境** 部署一律與一或多個 AWS [環境](environments.md)相關聯。您必須先[引導](bootstrapping.md)環境，才能部署環境。引導會在您的環境中佈建資源，讓 CDK 用來執行和管理部署。這些資源包括 Amazon Simple Storage Service (Amazon S3) 儲存貯體和 Amazon Elastic Container Registry (Amazon ECR) 儲存庫，用於存放和管理[資產](assets.md)。這些資源也包含 AWS Identity and Access Management (IAM) 角色，用於在開發和部署期間提供許可。 我們建議您使用 AWS CDK Command Line Interface (AWS CDK CLI) `cdk bootstrap`命令來引導您的環境。您可以視需要自訂引導或在環境中手動建立這些資源。如需說明，請參閱[引導您的環境以搭配 AWS CDK 使用](bootstrapping-env.md)。 **設定 AWS 環境** 每個 CDK 堆疊都必須與環境建立關聯，以判斷堆疊的部署位置。如需說明，請參閱[設定環境以搭配 AWS CDK 使用](configure-env.md)。 **開發您的 CDK 應用程式** 在 CDK [專案](projects.md)中，您可以建立和開發 CDK 應用程式。在您的應用程式中，您可以建立一或多個 CDK [堆疊](stacks.md)。在堆疊中，您可以從 AWS 建構程式庫匯入和使用[建構](constructs.md)來定義基礎設施。您的 CDK 應用程式必須至少包含一個堆疊，才能部署。 ## CDK 應用程式合成 若要執行合成，建議您使用 CDK CLI `cdk synth`命令。`cdk deploy` 命令也會在啟動部署之前執行合成。不過，透過使用 `cdk synth`，您可以在啟動部署之前驗證 CDK 應用程式並擷取錯誤。 合成行為取決於您為 CDK [堆疊設定的堆疊合成器](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html#stack-synthesizers)。如果您未設定合成器，` [DefaultStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html) `則會使用 。您也可以設定和自訂合成以符合您的需求。如需說明，請參閱[設定和執行 CDK 堆疊合成](configure-synth.md)。 為了讓您的合成 CloudFormation 範本成功部署到您的環境中，它必須與環境的引導方式相容。例如，您的 CloudFormation 範本必須指定要部署資產的正確 Amazon S3 儲存貯體。如果您使用預設方法引導您的環境，預設堆疊合成器將會運作。如果您自訂 CDK 行為，例如自訂引導或合成，CDK 部署行為可能會有所不同。 **應用程式生命週期** 當您執行合成時，CDK 應用程式會執行下列階段，稱為*應用程式生命週期*： **建構 （或初始化）** 您的程式碼會執行個體化所有定義的建構，然後將它們連結在一起。在此階段中，所有建構模組 （應用程式、堆疊及其子建構模組） 都會執行個體化，並執行建構模組鏈。您大部分的應用程式程式碼都會在此階段執行。 **準備** 所有已實作 `prepare`方法的建構都參與最後一輪修改，以設定其最終狀態。準備階段會自動發生。身為使用者，您看不到此階段的任何意見回饋。很少需要使用「準備」勾點，通常不建議。在此階段中變更建構樹時請特別小心，因為操作順序可能會影響行為。 在此階段，建置建構樹之後，您設定的任何[層面](aspects.md)也會套用。 **驗證** 所有已實作 `validate`方法的建構可以自行驗證，以確保其處於將正確部署的狀態。您會在此階段收到任何驗證失敗的通知。一般而言，我們建議您盡快執行驗證 （通常是在您取得一些輸入時立即執行），並儘早擲出例外狀況。儘早執行驗證可改善可靠性，因為堆疊追蹤會更準確，並確保您的程式碼可以繼續安全地執行。 **合成** 這是執行 CDK 應用程式的最後階段。它由呼叫 觸發`app.synth()`，它會周遊建構樹，並調用所有建構上的 `synthesize`方法。實作 的建構`synthesize`可以參與合成，並為產生的雲端組件產生部署成品。這些成品包括 CloudFormation 範本、 AWS Lambda 應用程式套件、檔案和 Docker 影像資產，以及其他部署成品。在大多數情況下，您不需要實作 `synthesize`方法。 **執行您的應用程式** CDK CLI 需要知道如何執行您的 CDK 應用程式。如果您使用 `cdk init`命令從範本建立專案，則應用程式的 `cdk.json` 檔案會包含 `app`金鑰。此金鑰指定應用程式寫入語言的必要命令。如果您的語言需要編譯，命令列會在自動執行應用程式之前執行此步驟。 **Example** ``` { "app": "npx ts-node --prefer-ts-exts bin/my-app.ts" } ``` ``` { "app": "node bin/my-app.js" } ``` ``` { "app": "python app.py" } ``` ``` { "app": "mvn -e -q compile exec:java" } ``` ``` { "app": "dotnet run -p src/MyApp/MyApp.csproj" } ``` ``` { "app": "go mod download && go run my-app.go" } ``` 如果您未使用 CDK CLI 建立專案，或想要覆寫 中提供的命令列`cdk.json`，您可以在執行`cdk`命令時提供 ` --app `選項。 ``` $ cdk --app '' ... ``` 命令的 ``部分指出執行 CDK 應用程式時應執行的命令。使用如下所示的引號，因為這類命令包含空格。`` 是類似 `synth`或 的子命令`deploy`，可告訴 CDK CLI 您想要如何使用您的應用程式。請依照此執行該子命令所需的任何其他選項。 CDK CLI 也可以直接與已合成的雲端組件互動。若要這樣做，請傳遞雲端組件存放在 中的目錄`--app`。下列範例列出存放在 下的雲端組件中定義的堆疊`./my-cloud-assembly`。 ``` $ cdk --app <./my-cloud-assembly> ls ``` **雲端組件** 對 的呼叫`app.synth()`會指示 AWS CDK 從應用程式合成雲端組件。一般而言，您不會直接與雲端組件互動。這些檔案包含將應用程式部署至雲端環境所需的一切。例如，它包含應用程式中每個堆疊的 AWS CloudFormation 範本。它還包含您在應用程式中參考的任何檔案資產或 Docker 映像的副本。 如需如何格式化[雲端組件的詳細資訊，請參閱雲端組件規格](https://github.com/aws/aws-cdk-cli/blob/main/packages/%40aws-cdk/cloud-assembly-schema/README.md)。 若要與 AWS CDK 應用程式建立的雲端組件互動，您通常會使用 AWS CDK CLI。不過，任何可以讀取雲端組件格式的工具都可以用來部署您的應用程式。 ## 部署您的應用程式 若要部署應用程式，建議您使用 CDK CLI `cdk deploy`命令啟動部署或設定自動化部署。 當您執行 時`cdk deploy`，CDK CLI 會啟動 `cdk synth`以準備部署。下圖說明部署內容中的應用程式生命週期： ![ CDK 應用程式生命週期的流程圖。](http://docs.aws.amazon.com/zh_tw/cdk/v2/guide/images/app-lifecycle_cdk-flowchart.png) 在部署期間，CDK CLI 會採用合成產生的雲端組件，並將其部署到 AWS 環境。資產會上傳至 Amazon S3 和 Amazon ECR，而 CloudFormation 範本會提交至 AWS CloudFormation 進行部署。 在 AWS CloudFormation 部署階段開始時，您的 CDK 應用程式已完成執行並結束。這具有以下含義： + CDK 應用程式無法回應部署期間發生的事件，例如正在建立的資源或整個部署完成。若要在部署階段執行程式碼，您必須將其插入 AWS CloudFormation 範本做為[自訂資源](cfn-layer.md#develop-customize-custom)。如需將自訂資源新增至應用程式的詳細資訊，請參閱 [AWS CloudFormation 模組](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudformation-readme.html)或[自訂資源](https://github.com/aws-samples/aws-cdk-examples/tree/master/typescript/custom-resource/)範例。您也可以設定 [Triggers](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.triggers-readme.html) 模組在部署期間執行程式碼。 + CDK 應用程式可能需要使用執行時無法得知的值。例如，如果 AWS CDK 應用程式使用自動產生的名稱定義 Amazon S3 儲存貯體，而您擷取 `bucket.bucketName`(Python：`bucket_name`) 屬性，則該值不是已部署儲存貯體的名稱。反之，您會取得`Token`值。若要判斷特定值是否可用，請呼叫 `cdk.isUnresolved(value)`(Python：`is_unresolved`)。如需詳細資訊[，請參閱權杖和 AWS CDK](tokens.md)。 **部署許可** 必須先建立許可，才能執行部署。下圖說明使用預設引導程序和堆疊合成器時，預設部署期間使用的許可： ![預設 CDK 部署程序的流程圖。](http://docs.aws.amazon.com/zh_tw/cdk/v2/guide/images/default-deploy-process_cdk_flowchart.png) **演員啟動部署** 部署是由*演員*使用 CDK CLI 啟動。演員可以是個人，也可以是 AWS CodePipeline 等服務。 如有必要，CDK CLI 會在您執行 `cdk synth`時執行`cdk deploy`。在合成期間， AWS 身分會假設`LookupRole`在 AWS 環境中執行內容查詢。 **已建立許可** 首先，演員的安全登入資料用於對 進行身分驗證， AWS 並取得程序中的第一個 IAM 身分。對於人類執行者，如何設定和取得安全登入資料取決於您或您的組織管理使用者的方式。如需詳細資訊，請參閱[設定 AWS CDK CLI 的安全登入資料](configure-access.md)。對於 CodePipeline 等服務執行者，會擔任並使用 IAM 執行角色。 接著，在引導期間在您的 AWS 環境中建立的 IAM 角色會用來建立許可，以執行部署所需的動作。如需這些角色及其授予許可的詳細資訊，請參閱[引導期間建立的 IAM 角色](bootstrapping-env.md#bootstrapping-env-roles)。此程序包括下列項目： + AWS 身分會擔任`DeploymentActionRole`角色並將`CloudFormationExecutionRole`角色傳遞給 CloudFormation，確保 CloudFormation 在您的 AWS 環境中執行任何動作時，會擔任該角色。 `DeploymentActionRole`會授予許可，以在您的環境中執行部署，並`CloudFormationExecutionRole`決定 CloudFormation 可執行的動作。 + AWS 身分假設 `FilePublishingRole`，這會決定可以在引導期間建立的 Amazon S3 儲存貯體上執行的動作。 + AWS 身分假設 `ImagePublishingRole`，這會決定可以在引導期間建立的 Amazon ECR 儲存庫上執行的動作。 + 如有必要， AWS 身分會假設在 AWS 環境中`LookupRole`執行內容查詢。此動作也可能在範本合成期間執行。 **部署已執行** 在部署期間，CDK CLI 會讀取引導版本參數以確認引導版本編號。 AWS CloudFormation 也會在部署時間讀取此參數以確認。如果部署工作流程中的許可有效，則會執行部署。資產會上傳至引導的資源，並使用 CloudFormation服務做為 CloudFormation 堆疊來部署合成時產生的 CloudFormation 範本，以佈建您的資源。