這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 引導您的環境以搭配 AWS CDK 使用 引導您的 AWS 環境，為 AWS 雲端開發套件 (AWS CDK) 堆疊部署做好準備。 + 如需環境的簡介，請參閱 [AWS CDK 的環境](environments.md)。 + 如需引導的簡介，請參閱 [AWS CDK 引導](bootstrapping.md)。 ## 如何引導您的環境 您可以使用 AWS CDK 命令列界面 (AWS CDK CLI) 或 preferred AWS CloudFormation 部署工具來引導您的環境。 **使用 CDK CLI** 您可以使用 CDK CLI `cdk bootstrap`命令來引導您的環境。如果您不需要大幅修改引導，建議您使用此方法。 **從任何工作目錄引導** 若要從任何工作目錄引導，請提供環境做為命令列引數引導。以下是範例： ``` $ cdk bootstrap ``` 如果您沒有 AWS 帳戶號碼，您可以從 AWS 管理主控台取得。您也可以使用下列 AWS CLI 命令來顯示您的預設帳戶資訊，包括您的帳號： ``` $ aws sts get-caller-identity ``` 如果您已在 AWS `config`和 `credentials` 檔案中命名設定檔，請使用 `--profile`選項來擷取特定設定檔的帳戶資訊。以下是範例： ``` $ aws sts get-caller-identity --profile ``` 若要顯示預設區域，請使用 `aws configure get`命令： ``` $ aws configure get region $ aws configure get region --profile ``` 提供 引數時，字`aws://`首是選用的。下列項目有效： ``` $ cdk bootstrap <123456789012/us-east-1> ``` 若要同時引導多個環境，請提供多個引數： ``` $ cdk bootstrap ``` **從 CDK 專案的父目錄引導** 您可以從包含 `cdk.json` 檔案的 CDK 專案的`cdk bootstrap`父目錄執行 。如果您不提供環境做為引數，CDK CLI 會從預設來源取得環境資訊，例如您的 `config`和 `credentials` 檔案，或為 CDK 堆疊指定的任何環境資訊。 當您從 CDK 專案的父目錄引導時，從命令列引數提供的環境會優先於其他來源。 若要引導 `config`和 `credentials` 檔案中指定的環境，請使用 `--profile`選項： ``` $ cdk bootstrap --profile ``` 如需 `cdk bootstrap`命令和支援選項的詳細資訊，請參閱 [cdk 引導](ref-cli-cmd-bootstrap.md)。 **使用 any AWS CloudFormation 工具** 您可以從 *aws-cdk-cli GitHub 儲存庫*複製[引導範本](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml)，或使用 `cdk bootstrap --show-template`命令取得範本。然後，使用 any AWS CloudFormation 工具將範本部署到您的環境中。 透過此方法，您可以使用 AWS CloudFormation StackSets 或 AWS Control Tower。您也可以使用 AWS CloudFormation 主控台或 AWS 命令列界面 (AWS CLI)。您可以在部署範本之前對其進行修改。此方法可能更靈活，且適用於大規模部署。 以下是使用 `--show-template`選項擷取引導範本並將其儲存至本機電腦的範例： **Example** ``` $ cdk bootstrap --show-template > bootstrap-template.yaml ``` 在 Windows 上，必須使用 PowerShell 來保留範本的編碼。 ``` powershell "cdk bootstrap --show-template | Out-File -encoding utf8 bootstrap-template.yaml" ``` 如果您的 AWS CloudFormation 範本輸出中出現 CDK 通知，請提供 `--no-notices`選項與 命令。 若要使用 CDK CLI 部署此範本，您可以執行下列動作： ``` $ cdk bootstrap --template ``` 以下是使用 AWS CLI 部署範本的範例： **Example** ``` aws cloudformation create-stack \ --stack-name CDKToolkit \ --template-body file://bootstrap-template.yaml \ --capabilities CAPABILITY_NAMED_IAM \ --region ``` ``` aws cloudformation create-stack ^ --stack-name CDKToolkit ^ --template-body file://bootstrap-template.yaml ^ --capabilities CAPABILITY_NAMED_IAM ^ --region ``` 如需有關使用 CloudFormation StackSets 引導多個環境的資訊，請參閱 * AWS 雲端操作與遷移部落格*中的[使用 CloudFormation StackSets 引導多個 AWS CDK AWS 帳戶](https://aws.amazon.com/blogs/mt/bootstrapping-multiple-aws-accounts-for-aws-cdk-using-cloudformation-stacksets/)。 ## 何時啟動您的環境 您必須先引導每個 AWS 環境，才能部署到環境。我們建議您主動引導您計劃使用的每個環境。您可以在計劃實際將 CDK 應用程式部署到環境之前執行此操作。透過主動引導您的環境，您可以防止潛在的未來問題，例如 Amazon S3 儲存貯體名稱衝突，或將 CDK 應用程式部署到尚未引導的環境。 可以多次引導環境。如果環境已啟動，將會視需要升級引導堆疊。否則，不會發生任何情況。 如果您嘗試將 CDK 堆疊部署到尚未引導的環境，您會看到如下錯誤： ``` $ cdk deploy ✨ Synthesis time: 2.02s ❌ Deployment failed: Error: BootstrapExampleStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html) ``` **更新您的引導堆疊** CDK 團隊會定期將引導範本更新為新版本。發生這種情況時，我們建議您更新引導堆疊。如果您尚未自訂引導程序，您可以依照最初引導環境所採取的相同步驟來更新引導堆疊。如需詳細資訊，請參閱[引導範本版本歷史記錄](#bootstrap-template-history)。 ## 引導期間建立的預設資源 **在引導期間建立的 IAM 角色** 根據預設，引導會在您的環境中佈建下列 AWS Identity and Access Management (IAM) 角色： + `CloudFormationExecutionRole` + `DeploymentActionRole` + `FilePublishingRole` + `ImagePublishingRole` + `LookupRole` `CloudFormationExecutionRole` 此 IAM 角色是 CloudFormation 服務角色，授予 CloudFormation 代表您執行堆疊部署的許可。此角色提供 CloudFormation 在您的帳戶中執行 AWS API 呼叫的許可，包括部署堆疊。 透過使用服務角色，為服務角色佈建的許可決定可在 CloudFormation 資源上執行的動作。如果沒有此服務角色，您使用 CDK CLI 提供的安全登入資料將決定允許 CloudFormation 執行的動作。 `DeploymentActionRole` 此 IAM 角色會授予在您的環境中執行部署的許可。在部署期間由 CDK CLI 擔任。 透過使用角色進行部署，您可以執行跨帳戶部署，因為不同帳戶中的 AWS 身分可以擔任該角色。 `FilePublishingRole` 此 IAM 角色授予許可，以對引導的 Amazon Simple Storage Service (Amazon S3) 儲存貯體執行動作，包括上傳和刪除資產。在部署期間由 CDK CLI 擔任。 `ImagePublishingRole` 此 IAM 角色授予許可，以對引導的 Amazon Elastic Container Registry (Amazon ECR) 儲存庫執行動作。在部署期間由 CDK CLI 擔任。 `LookupRole` 此 IAM 角色授予從 AWS 環境查詢[內容值](context.md)的`readOnly`許可。在執行範本合成和部署等任務時，CDK CLI 會擔任此角色。 **在引導期間建立的資源 IDs ** 部署預設引導範本時，會使用下列結構建立引導資源IDs：`cdk----`。 + **限定詞** – 九個字元的唯一字串值 `hnb659fds`。實際值沒有意義。 + **描述** – 資源的簡短描述。例如 `container-assets`。 + **帳戶 ID** – 環境 AWS 的帳戶 ID。 + **區域** – 環境 AWS 的區域。 以下是在引導期間建立的 Amazon S3 預備儲存貯體的實體 ID 範例：`cdk-hnb659fds-assets-012345678910-us-west-1`。 ## 引導環境時使用的許可 引導 AWS 環境時，執行引導的 IAM 身分必須至少具有下列許可： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:*", "ecr:*", "ssm:*", "s3:*", "iam:*" ], "Resource": "*" } ] } ``` 隨著時間的推移，引導堆疊，包括建立的資源和所需的許可，可能會變更。隨著未來的變更，您可能需要修改啟動環境所需的許可。 ## 自訂引導 如果預設引導範本不符合您的需求，您可以透過下列方式，在您的環境中自訂資源引導： + 使用命令列選項搭配 `cdk bootstrap`命令 – 此方法最適合透過命令列選項進行小而特定的變更。 + 修改預設引導範本並進行部署 – 此方法最適合進行複雜的變更，或者如果您想要完全控制引導期間佈建的資源組態。 如需自訂引導的詳細資訊，請參閱[自訂 AWS CDK 引導](bootstrapping-customizing.md)。 ## 使用 CDK 管道引導 如果您使用 CDK 管道部署到另一個帳戶的環境，則會收到如下的訊息： ``` Policy contains a statement with one or more invalid principals ``` 此錯誤訊息表示適當的 IAM 角色不存在於其他環境中。最可能的原因是環境尚未引導。引導環境，然後再試一次。 **保護您的引導堆疊免於刪除** 如果刪除引導堆疊，原本在環境中佈建以支援 CDK 部署 AWS 的資源也會遭到刪除。這會導致管道停止運作。如果發生這種情況，就沒有一般的復原解決方案。 環境開機後，請勿刪除並重新建立環境的開機堆疊。反之，請再次執行 `cdk bootstrap`命令，嘗試將引導堆疊更新為新版本。 為了防止意外刪除您的引導堆疊，建議您使用 `cdk bootstrap`命令提供 `--termination-protection`選項，以啟用終止保護。您可以在新的或現有的引導堆疊上啟用終止保護。如需啟用終止保護的指示，請參閱[啟用引導堆疊的終止保護](bootstrapping-customizing.md#bootstrapping-customizing-cli-protection)。 ## 引導範本版本歷史記錄 引導範本會進行版本控制，並隨著 AWS CDK 本身隨著時間演進。如果您提供自己的引導範本，請讓它與正式預設範本保持最新狀態。您想要確保您的範本繼續使用所有 CDK 功能。 **注意** 根據預設，引導範本的早期版本會在每個引導環境中建立 AWS KMS 金鑰。若要避免 KMS 金鑰的費用，請使用 重新引導這些環境`--no-bootstrap-customer-key`。目前的預設值不是 KMS 金鑰，這有助於避免這些費用。 本節包含每個版本所做的變更清單。 | 範本版本 | AWS CDK 版本 | 變更 | | --- | --- | --- | | **1** | 1.40.0 | 具有儲存貯體、金鑰、儲存庫和角色的範本初始版本。 | | **2** | 1.45.0 | 將資產發佈角色分割為單獨的檔案和映像發佈角色。 | | **3** | 1.46.0 | 新增`FileAssetKeyArn`匯出以能夠將解密許可新增至資產取用者。 | | **4** | 1.61.0 | AWS KMS 許可現在會透過 Amazon S3 隱含，且不再需要 `FileAssetKeyArn`。新增 `CdkBootstrapVersion` SSM 參數，以便在不知道堆疊名稱的情況下驗證引導堆疊版本。 | | **5** | 1.87.0 | 部署角色可以讀取 SSM 參數。 | | **6** | 1.108.0 | 新增與部署角色不同的查詢角色。 | | **6** | 1.109.0 | 將`aws-cdk:bootstrap-role`標籤連接至部署、檔案發佈和映像發佈角色。 | | **7** | 1.110.0 | 部署角色無法再直接讀取目標帳戶中的儲存貯體。（不過，此角色實際上是管理員，而且無論如何都可以使用其 AWS CloudFormation 許可讓儲存貯體可供讀取）。 | | **8** | 1.114.0 | 查詢角色具有目標環境的完整唯讀許可，也具有 `aws-cdk:bootstrap-role`標籤。 | | **9** | 2.1.0 | 修正常用加密 SCP 拒絕的 Amazon S3 資產上傳。 | | **10** | 2.4.0 | Amazon ECR ScanOnPush 現在預設為啟用。 | | **11** | 2.18.0 | 新增政策，允許 Lambda 從 Amazon ECR 儲存庫提取，使其在重新引導時存活。 | | **12** | 2.20.0 | 新增對實驗性 的支援`cdk import`。 | | **13** | 2.25.0 | 讓引導建立的 Amazon ECR 儲存庫中的容器映像不可變。 | | **14** | 2.34.0 | 根據預設，關閉儲存庫層級的 Amazon ECR 映像掃描，以允許不支援映像掃描的引導區域。 | | **15** | 2.60.0 | KMS 金鑰無法標記。 | | **16** | 2.69.0 | 解決 Security Hub 問題清單 [KMS.2。](https://docs.aws.amazon.com/securityhub/latest/userguide/kms-controls.html#kms-2) | | **17** | 2.72.0 | 解決 Security Hub 問題清單 [ECR.3。](https://docs.aws.amazon.com/securityhub/latest/userguide/ecr-controls.html#ecr-3) | | **18** | 2.80.0 | 還原對第 16 版所做的變更，因為它們不適用於所有分割區，因此不建議使用。 | | **19** | 2.106.1 | 還原對版本 18 所做的變更，其中 AccessControl 屬性已從範本中移除。([\$127964](https://github.com/aws/aws-cdk/issues/27964)) | | **20** | 2.119.0 | 將`ssm:GetParameters`動作新增至 AWS CloudFormation 部署 IAM 角色。如需詳細資訊，請參閱 [\$128336](https://github.com/aws/aws-cdk/pull/28336/files#diff-4fdac38426c4747aa17d515b01af4994d3d2f12c34f7b6655f24328259beb7bf)。 | | **21** | 2.149.0 | 將條件新增至檔案發佈角色。 | | **22** | 2.160.0 | 將`sts:TagSession`許可新增至引導 IAM 角色的信任政策。 | | **23** | 2.161.0 | 將 `cloudformation:RollbackStack`和 `cloudformation:ContinueUpdateRollback`許可新增至部署 IAM 角色的信任政策。這提供 `cdk rollback`命令的許可。 | | **24** | 2.165.0 | 將引導儲存貯體中非目前物件的保留天數從 365 天變更為 30 天。由於新`cdk gc`命令引入刪除引導儲存貯體中物件的功能，因此此新行為可確保已刪除的物件在引導儲存貯體中保留 30 天，而不是 365 天。如需此變更的詳細資訊，請參閱 `aws-cdk` PR [\$131949](https://github.com/aws/aws-cdk/pull/31949)。 | | **25** | 2.165.0 | 將支援新增至引導儲存貯體，以移除不完整的分段上傳。未完成的分段上傳將在 1 天後刪除。如需此變更的詳細資訊，請參閱 `aws-cdk` PR [\$131956](https://github.com/aws/aws-cdk/pull/31956)。 | | **26** | 2.1002.0 | 將兩個刪除相關政策 (`UpdateReplacePolicy` 和 `FileAssetsBucketEncryptionKey`) 資源`DeletionPolicy`新增至 。這些政策可確保在更新或刪除引導堆疊時，正確刪除舊的 AWS KMS 金鑰資源。如需此變更的詳細資訊，請參閱 `aws-cdk-cli` PR [\$1100](https://github.com/aws/aws-cdk-cli/pull/100)。 | | **27** | 2.1003.0 | 新增 Amazon ECR 資源政策，以授予 Amazon EMR Serverless 擷取容器映像的特定許可。如需此變更的詳細資訊，請參閱 `aws-cdk-cli` PR [\$1112](https://github.com/aws/aws-cdk-cli/pull/112)。 | | **28** | 2.1015.0 | 將執行堆疊重構動作的許可新增至部署角色，並將 TagSession 許可新增至所有角色。如需此變更的詳細資訊，請參閱 `aws-cdk-cli` PR [\$1471](https://github.com/aws/aws-cdk-cli/pull/471)。 | | **29** | 2.1026.0 | 除非停用，否則預設會拒絕提供 ExternalId 的所有 AssumeRole 呼叫。如需此變更的詳細資訊，請參閱 `aws-cdk-cli` PR [\$1811](https://github.com/aws/aws-cdk-cli/pull/811)。 | | **30** | 2.1034.0 | 新增許可，將堆疊事件描述到部署角色，以準確顯示 CloudFormation 早期驗證錯誤。如需此變更的詳細資訊，請參閱 `aws-cdk-cli` PR [\$1970](https://github.com/aws/aws-cdk-cli/pull/970)。 | ## 從舊版升級至現代引導範本 AWS CDK v1 支援兩個引導範本，傳統和現代。CDK v2 僅支援現代範本。以下是這兩個範本之間的高階差異，以供參考。 | 功能 | 舊版 （僅限 v1) | 現代 (v1 和 v2) | | --- | --- | --- | | **跨帳戶部署** | 不允許 | 允許 | | ** AWS CloudFormation 許可** | 使用目前使用者的許可進行部署 （依 AWS 設定檔、環境變數等決定） | 使用佈建引導堆疊時指定的許可進行部署 （例如，使用 `--trust`) | | **版本控制** | 只有一個版本的引導堆疊可用 | 引導堆疊已版本化；未來版本中可以新增新資源，而 AWS CDK 應用程式可能需要最低版本 | | **資源\$1** | Amazon S3 儲存貯體 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cdk/v2/guide/bootstrapping-env.html) | | ** AWS KMS 金鑰** | IAM 角色 | Amazon ECR 儲存庫 | | **資源命名** | 自動產生 | 確定性 | | **儲存貯體加密** | 預設金鑰 | AWS 根據預設， 受管金鑰。您可以自訂 以使用客戶受管金鑰。 | + *我們會視需要將其他資源新增至引導範本。* 使用舊版範本引導的環境必須透過重新引導升級，以使用 CDK v2 的現代範本。在刪除舊版儲存貯體之前，至少重新部署環境中的所有 AWS CDK 應用程式一次。 ## 地址安全中樞調查結果 如果您使用的是 AWS Security Hub，您可能會在 AWS CDK 引導程序建立的某些資源上看到報告的問題清單。Security Hub 調查結果可協助您尋找資源組態，您應該再次檢查其準確性和安全性。我們已與 AWS Security 一起檢閱這些特定資源組態，並確信它們不會構成安全問題。 **【KMS.2】 IAM 主體不應具有允許對所有 KMS 金鑰執行解密動作的 IAM 內嵌政策** *部署角色* (`DeploymentActionRole`) 授予讀取加密資料的許可，這是使用 CDK Pipelines 跨帳戶部署的必要許可。此角色中的政策不會授予所有資料的許可。它只授予從 Amazon S3 和 AWS KMS 讀取加密資料的許可，並且只有在這些資源透過其儲存貯體或金鑰政策允許時。 以下是從引導範本*部署角色*中這兩個陳述式的程式碼片段： ``` DeploymentActionRole: Type: AWS::IAM::Role Properties: ... Policies: - PolicyDocument: Statement: ... - Sid: PipelineCrossAccountArtifactsBucket Effect: Allow Action: - s3:GetObject* - s3:GetBucket* - s3:List* - s3:Abort* - s3:DeleteObject* - s3:PutObject* Resource: "*" Condition: StringNotEquals: s3:ResourceAccount: Ref: AWS::AccountId - Sid: PipelineCrossAccountArtifactsKey Effect: Allow Action: - kms:Decrypt - kms:DescribeKey - kms:Encrypt - kms:ReEncrypt* - kms:GenerateDataKey* Resource: "*" Condition: StringEquals: kms:ViaService: Fn::Sub: s3.${AWS::Region}.amazonaws.com ... ``` **為什麼 Security Hub 會標記此項目？** 政策包含`Resource: *`結合 `Condition`子句的 。Security Hub 會標記`*`萬用字元。使用此萬用字元是因為在帳戶啟動時，CDK Pipelines 為 CodePipeline 成品儲存貯體建立的 AWS KMS 金鑰尚不存在，因此 ARN 無法參考開機範本上的 。此外，在引發此旗標時，Security Hub 不會考慮 `Condition`子句。這`Condition`僅限於從 AWS KMS 金鑰的相同 AWS 帳戶提出的`Resource: *`請求。這些請求必須來自與 AWS AWS KMS 金鑰位於相同區域的 Amazon S3。 **我是否需要修正此問題清單？** 只要您尚未將引導範本上的 AWS KMS 金鑰修改為過度寬鬆，*部署角色*就不會允許超出所需的存取權。因此，不需要修正此調查結果。 **如果我想要修正此調查結果該怎麼辦？** 如何修正此調查結果取決於您是否將使用 CDK 管道進行跨帳戶部署。 **修正 Security Hub 調查結果，並使用 CDK 管道進行跨帳戶部署** 1. 如果您尚未這麼做，請使用 `cdk bootstrap`命令部署 CDK 引導堆疊。 1. 如果您尚未這麼做，請建立並部署您的 CDKPipeline。如需說明，請參閱[使用 CDK 管道的持續整合和交付 (CI/CD)](cdk-pipeline.md)。 1. 取得 CodePipeline 成品儲存貯體的 AWS KMS 金鑰 ARN。此資源會在管道建立期間建立。 1. 取得 CDK 引導範本的副本以進行修改。以下是使用 AWS CDK CLI 的範例： ``` $ cdk bootstrap --show-template > bootstrap-template.yaml ``` 1. 使用 ARN 值取代 `PipelineCrossAccountArtifactsKey`陳述`Resource: *`式來修改範本。 1. 部署 範本以更新您的引導堆疊。以下是使用 CDK CLI 的範例： ``` $ cdk bootstrap aws:/// --template bootstrap-template.yaml ``` **如果您未使用 CDK 管道進行跨帳戶部署，請修正 Security Hub 問題清單** 1. 取得 CDK 引導範本的副本以進行修改。以下是使用 CDK CLI 的範例： ``` $ cdk bootstrap --show-template > bootstrap-template.yaml ``` 1. 從範本刪除 `PipelineCrossAccountArtifactsBucket`和 `PipelineCrossAccountArtifactsKey`陳述式。 1. 部署 範本以更新您的引導堆疊。以下是使用 CDK CLI 的範例： ``` $ cdk bootstrap aws:/// --template bootstrap-template.yaml ``` ## 考量事項 由於引導會在您的環境中佈建資源，因此當這些資源與 AWS CDK 搭配使用時，可能會產生 AWS 費用。