這是 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 費用。 # 自訂 AWS CDK 引導 您可以使用 AWS CDK 命令列界面 (AWS CDK CLI) 或修改和部署 AWS CloudFormation 引導範本，來自訂 AWS 雲端開發套件 (AWS CDK) 引導。 如需引導的簡介，請參閱 [AWS CDK 引導](bootstrapping.md)。 ## 使用 CDK CLI 自訂引導 以下是如何使用 CDK CLI 自訂引導的一些範例。如需所有`cdk bootstrap`選項的清單，請參閱 [cdk 引導](ref-cli-cmd-bootstrap.md)。 **覆寫 Amazon S3 儲存貯體的名稱** 使用 `--bootstrap-bucket-name`選項覆寫預設的 Amazon S3 儲存貯體名稱。這可能需要您修改範本合成。如需詳細資訊，請參閱[自訂 CDK 堆疊合成](configure-synth.md#bootstrapping-custom-synth)。 **修改 Amazon S3 儲存貯體的伺服器端加密金鑰** 根據預設，引導堆疊中的 Amazon S3 儲存貯體設定為使用 AWS 受管金鑰進行伺服器端加密。若要使用現有的客戶受管金鑰，請使用 `--bootstrap-kms-key-id`選項，並提供 Key Management Service (AWS KMS) AWS 金鑰要使用的值。如果您想要對加密金鑰進行更多控制，請提供 `--bootstrap-customer-key` 以使用客戶受管金鑰。 **將受管政策連接至 AWS CloudFormation 擔任的部署角色** 根據預設，堆疊會使用 `AdministratorAccess`政策以完整的管理員許可進行部署。若要使用您自己的受管政策，請使用 `--cloudformation-execution-policies`選項，並提供要連接到部署角色的受管政策 ARNs。 若要提供多個政策，請傳遞一個字串，並以逗號分隔： ``` $ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess" ``` 為了避免部署失敗，請確定您指定的政策足以讓您對要引導的環境執行任何部署。 **變更新增至引導堆疊中資源名稱的限定詞** 根據預設，`hnb659fds`限定詞會新增至引導堆疊中資源的實體 ID。若要變更此值，請使用 `--qualifier`選項。 此修改在相同環境中佈建多個引導堆疊時非常有用，以避免名稱衝突。 變更限定詞旨在隔離 CDK 本身自動測試之間的名稱。除非您可以非常精確地縮小授予 CloudFormation 執行角色的 IAM 許可範圍，否則在單一帳戶中具有兩個不同的引導堆疊，沒有許可隔離的優勢。因此，通常不需要變更此值。 當您變更限定詞時，您的 CDK 應用程式必須將變更的值傳遞至堆疊合成器。如需詳細資訊，請參閱[自訂 CDK 堆疊合成](configure-synth.md#bootstrapping-custom-synth)。 **將標籤新增至引導堆疊** 使用 格式的 `--tags`選項`KEY=VALUE`，將 CloudFormation 標籤新增至您的引導堆疊。 **指定可部署到要引導環境的其他 AWS 帳戶** 使用 `--trust`選項提供允許部署到要引導環境的其他 AWS 帳戶。根據預設，執行引導的帳戶一律會受信任。 當您從Pipeline另一個環境引導 CDK 部署到的環境時，此選項非常有用。 使用此選項時，您還必須提供 `--cloudformation-execution-policies`。 若要將信任的帳戶新增至現有的引導堆疊，您必須指定要信任的所有帳戶，包括您先前可能提供的帳戶。如果您只提供新帳戶來信任，先前信任的帳戶將被移除。 以下是信任兩個帳戶的範例： ``` $ cdk bootstrap aws://123456789012/us-west-2 --trust 234567890123 --trust 987654321098 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess ⏳ Bootstrapping environment aws://123456789012/us-west-2... Trusted accounts for deployment: 234567890123, 987654321098 Trusted accounts for lookup: (none) Execution policies: arn:aws:iam::aws:policy/AdministratorAccess CDKToolkit: creating CloudFormation changeset... ✅ Environment aws://123456789012/us-west-2 bootstrapped. ``` **指定可在要引導的環境中查詢資訊的其他 AWS 帳戶** 使用 `--trust-for-lookup`選項來指定允許從要引導的環境查詢內容資訊 AWS 的帳戶。此選項有助於為帳戶提供將部署到環境中的堆疊合成許可，而無需實際授予他們直接部署這些堆疊的許可。 **啟用引導堆疊的終止保護** 如果刪除引導堆疊，則最初在環境中佈建 AWS 的資源也會遭到刪除。環境開機後，建議您不要刪除並重新建立環境的開機堆疊，除非您刻意這麼做。反之，請再次執行 `cdk bootstrap`命令，嘗試將引導堆疊更新為新版本。 使用 `--termination-protection`選項來管理引導堆疊的終止保護設定。透過啟用終止保護，您可以防止不小心刪除引導堆疊及其資源。如果您使用 CDK，這尤其重要，Pipelines因為如果您不小心刪除引導堆疊，則沒有一般復原選項。 啟用終止保護後，您可以使用 AWS CLI 或 AWS CloudFormation 主控台進行驗證。 **啟用終止保護** 1. 執行下列命令，在新的或現有的引導堆疊上啟用終止保護： ``` $ cdk bootstrap --termination-protection ``` 1. 使用 AWS CLI 或 CloudFormation 主控台進行驗證。以下是使用 CLI AWS 的範例。如果您修改了引導堆疊名稱，請將 取代`CDKToolkit`為您的堆疊名稱： ``` $ aws cloudformation describe-stacks --stack-name --query "Stacks[0].EnableTerminationProtection" true ``` ## 修改預設引導範本 當您需要比 CDK CLI 更多的自訂時，您可以視需要修改引導範本。然後，部署 範本以引導您的環境。 **修改和部署預設引導範本** 1. 使用 `--show-template`選項取得預設引導範本。根據預設，CDK CLI 會在終端機視窗中輸出範本。您可以修改 CDK CLI 命令，將範本儲存至本機電腦。以下是範例： ``` $ cdk bootstrap --show-template > ``` 1. 視需要修改引導範本。您所做的任何變更都應該遵守引導範本合約。如需引導範本合約的詳細資訊，請參閱[遵循引導合約](#bootstrapping-contract)。 為了確保稍後`cdk bootstrap`使用預設範本執行的人員不會意外覆寫您的自訂，請變更`BootstrapVariant`範本參數的預設值。CDK CLI 只允許使用與目前部署的範本具有相同`BootstrapVariant`和相同或更高版本的範本覆寫引導堆疊。 1. 使用 preferred AWS CloudFormation 部署方法部署修改過的範本。以下是使用 CDK CLI 的範例： ``` $ cdk bootstrap --template ``` ## 遵循引導合約 若要讓您的 CDK 應用程式正確部署，合成期間產生的 CloudFormation 範本必須正確指定在引導期間建立的資源。這些資源通常稱為*引導資源*。引導會在您的 AWS 環境中建立由 AWS CDK 用來執行部署和管理應用程式資產的資源。合成會從應用程式中的每個 CDK 堆疊產生 CloudFormation 範本。這些範本不僅定義將從應用程式佈建 AWS 的資源。它們也會指定要在部署期間使用的引導資源。 在合成期間，CDK CLI 不知道如何引導您的 AWS 環境。反之，CDK CLI 會根據您設定的合成器產生 CloudFormation 範本。因此，當您自訂引導時，您可能需要自訂合成。如需自訂合成的指示，請參閱[自訂 CDK 堆疊合成](configure-synth.md#bootstrapping-custom-synth)。目的是確保您的合成 CloudFormation 範本與引導環境相容。此相容性稱為*引導合約*。 自訂堆疊合成最簡單的方法是修改`Stack`執行個體中的 `DefaultStackSynthesizer`類別。如果您需要超出此類別提供的自訂，您可以將自己的合成器寫入實作的類別 ` [IStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IStackSynthesizer.html) `（可能衍生自 `DefaultStackSynthesizer`)。 當您自訂引導時，請遵循引導範本合約，以保持與 的相容性`DefaultStackSynthesizer`。如果您修改引導範本合約以外的引導，則需要撰寫自己的合成器。 ### 版本控制 引導範本應包含資源，以使用已知名稱和輸出來建立 Amazon EC2 Systems Manager (SSM) 參數，以反映範本的版本： ``` Resources: CdkBootstrapVersion: Type: AWS::SSM::Parameter Properties: Type: String Name: Fn::Sub: '/cdk-bootstrap/${Qualifier}/version' Value: 4 Outputs: BootstrapVersion: Value: Fn::GetAtt: [CdkBootstrapVersion, Value] ``` ### 角色 `DefaultStackSynthesizer` 需要五個 IAM 角色用於五個不同的用途。如果您未使用預設角色，則必須在 `DefaultStackSynthesizer` 物件中指定 IAM 角色 ARNs。角色如下所示： + *部署角色*由 CDK CLI 和 AWS CodePipeline 擔任，以部署至環境。其`AssumeRolePolicy`控制誰可以部署到環境中。在 範本中，您可以查看此角色所需的許可。 + CDK CLI 會擔任*查詢角色*，以在 環境中執行內容查詢。其`AssumeRolePolicy`控制誰可以部署到環境中。您可以在範本中看到此角色所需的許可。 + CDK CLI 和 by AWS CodeBuild 專案會擔任*檔案發佈角色*和*映像發佈角色*，以將資產發佈至環境。它們分別用於寫入 Amazon S3 儲存貯體和 Amazon ECR 儲存庫。這些角色需要這些資源的寫入存取權。 + * AWS CloudFormation 執行角色*會傳遞至 AWS CloudFormation 以執行實際部署。其許可是部署將在其下執行的許可。許可會以列出受管政策 ARNs參數傳遞至堆疊。 ### 輸出 CDK CLI 要求引導堆疊上存在下列 CloudFormation 輸出： + `BucketName` – 檔案資產儲存貯體的名稱。 + `BucketDomainName` – 網域名稱格式的檔案資產儲存貯體。 + `BootstrapVersion` – 引導堆疊的目前版本。 ### 範本歷史記錄 引導範本會進行版本控制，並隨著 AWS CDK 本身隨著時間演進。如果您提供自己的引導範本，請讓它與正式預設範本保持最新狀態。您希望確保範本能繼續使用所有 CDK 功能。如需詳細資訊，請參閱[引導範本版本歷史記錄](bootstrapping-env.md#bootstrap-template-history)。 # 建立和套用 AWS CDK 的許可界限 *許可界限*是 AWS Identity and Access Management (IAM) 進階功能，可用來設定 IAM 實體可擁有的最大許可，例如使用者或角色。您可以使用許可界限來限制 IAM 實體在使用 AWS 雲端開發套件 (AWS CDK) 時可執行的動作。 若要進一步了解許可界限，請參閱《[IAM 使用者指南》中的 IAM 實體的許可界限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)。 ** ## 何時搭配 AWS CDK 使用許可界限 當您需要限制組織中的開發人員使用 AWS CDK 執行特定動作時，請考慮套用許可界限。例如，如果您 AWS 的環境中有您不希望開發人員修改的特定資源，您可以建立並套用許可界限。 ## 如何使用 AWS CDK 套用許可界限 ### 建立許可界限 首先，您要建立許可界限，使用 AWS 受管政策或客戶受管政策來設定 IAM 實體 （使用者或角色） 的界限。此政策會限制使用者或角色的最大許可。如需建立許可界限的指示，請參閱《[IAM 使用者指南》中的 IAM 實體的許可界限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)。 ** 許可界限會設定 IAM 實體可以擁有的最大許可，但不會自行授予許可。您必須搭配 IAM 政策使用許可界限，才能有效限制和授予組織的適當許可。您還必須防止 IAM 實體能夠逸出您設定的邊界。如需範例，請參閱《*IAM 使用者指南*》中的[使用許可界限將責任委派給其他人](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html#access_policies_boundaries-delegate)。 ### 在引導期間套用許可界限 建立許可界限之後，您可以在引導期間套用 AWS CDK 來強制執行許可界限。 使用 [`--custom-permissions-boundary`](ref-cli-cmd-bootstrap.md#ref-cli-cmd-bootstrap-options-custom-permissions-boundary)選項，並指定要套用的許可界限名稱。以下是套用名為 之許可界限的範例`cdk-permissions-boundary`： ``` $ cdk bootstrap --custom-permissions-boundary ``` 根據預設，CDK `CloudFormationExecutionRole` 會使用引導範本中定義的 IAM 角色來接收執行部署的許可。透過在引導期間套用自訂許可界限，許可界限會連接到此角色。然後，許可界限將設定組織中的開發人員在使用 AWS CDK 時可執行的最大許可。若要進一步了解此角色，請參閱[在引導期間建立的 IAM 角色](bootstrapping-env.md#bootstrapping-env-roles)。 當您以這種方式套用許可界限時，它們會套用至您引導的特定環境。若要在多個環境中使用相同的許可界限，您必須在引導期間套用每個環境的許可界限。您也可以將不同的許可界限套用至不同的環境。 ## 進一步了解 如需許可界限的詳細資訊，請參閱 * AWS 安全部落格*中的[使用 IAM 許可界限的時機和位置](https://aws.amazon.com/blogs/security/when-and-where-to-use-iam-permissions-boundaries/)。 # 故障診斷 AWS CDK 引導問題 使用 AWS 雲端開發套件 (AWS CDK) 啟動環境時的常見問題疑難排解。 + 如需引導的簡介，請參閱 [AWS CDK 引導](bootstrapping.md)。 + 如需引導的指示，請參閱[引導您的環境以搭配 AWS CDK 使用](bootstrapping-env.md)。 ## 使用預設範本引導時，您會收到 Amazon S3 儲存貯體的 'CREATE\$1FAILED' 錯誤 使用 AWS CDK Command Line Interface (CDK CLI) `cdk bootstrap`命令搭配預設引導範本進行引導時，您會收到下列錯誤： ``` CREATE_FAILED | AWS::S3::Bucket | already exists ``` 在疑難排解之前，請確定您使用的是最新版本的 CDK CLI。 + 若要檢查您的版本，請執行 `cdk --version`。 + 若要安裝最新版本，請執行 `npm install -g aws-cdk`。 安裝最新版本後，請嘗試再次引導您的環境。如果您仍然收到相同的錯誤，請繼續疑難排解。 ### 常見原因 當您引導環境時， AWS CDK 會為您的引導資源產生實體 IDs。如需詳細資訊，請參閱[在引導期間建立的資源 IDs](bootstrapping-env.md#bootstrapping-env-default-id)。 與其他引導資源不同，Amazon S3 儲存貯體名稱是全域的。這表示每個儲存貯體名稱在分割區內所有 AWS 區域中的所有 AWS 帳戶都必須是唯一的。如需詳細資訊，請參閱《*Amazon S3 使用者指南*》中的[儲存貯體概觀](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html)。因此，此錯誤的最常見原因是作為儲存貯體名稱產生的實體 ID 已存在於分割區的某處。這可能在您的 帳戶或其他帳戶中。 以下是儲存貯體名稱的範例：`cdk-hnb659fds-assets-012345678910-us-west-1`。雖然不太可能，但由於限定詞和帳戶 ID 是名稱的一部分，因此另一個 AWS 帳戶可能會使用此 Amazon S3 儲存貯體的名稱。由於儲存貯體名稱是全域範圍，因此如果由相同分割區中的不同帳戶使用，則無法使用它。您帳戶中的某個位置很可能存在同名的儲存貯體。這可能是在您嘗試引導的區域中，或另一個區域中。 一般而言，解決方案是在您的帳戶中找到此儲存貯體，並決定如何處理它，或自訂引導以建立不同名稱的引導資源。 ### Resolution 首先，判斷 AWS 帳戶中是否存在同名的儲存貯體。使用具有有效許可的 AWS 身分來查詢您帳戶中的 Amazon S3 儲存貯體，您可以透過下列方式執行此操作： + 使用 AWS Command Line Interface (AWS CLI) `aws s3 ls`命令來檢視所有儲存貯體的清單。 + 使用 [Amazon S3 主控台](https://console.aws.amazon.com/s3)查詢您帳戶中每個區域的儲存貯體名稱。 如果存在具有相同名稱的儲存貯體，請判斷是否正在使用該儲存貯體。如果未使用，請考慮刪除儲存貯體並嘗試再次引導您的環境。 如果具有相同名稱的儲存貯體存在且您不想將其刪除，請判斷它是否已與您帳戶中的引導堆疊相關聯。您可能需要檢查多個區域。Amazon S3 儲存貯體名稱中的區域不一定表示儲存貯體位於該區域。若要檢查它是否與`CDKToolkit`引導堆疊相關聯，您可以為每個區域執行下列其中一項操作： + 使用 AWS CLI `aws cloudformation describe-stack-resources --stack-name --region `命令來檢視引導堆疊中的資源，並檢查儲存貯體是否已列出。 + 在 [AWS CloudFormation 主控台](https://console.aws.amazon.com/cloudformation)中，找到`CDKToolkit`堆疊。然後，在**資源**索引標籤上，檢查儲存貯體是否存在。 如果儲存貯體與引導堆疊相關聯，請判斷引導堆疊是否位於您嘗試引導的相同區域。如果是，您的環境已經啟動，您應該能夠開始使用 CDK 將應用程式部署到您的環境。如果 Amazon S3 儲存貯體與不同區域中的引導堆疊相關聯，您將需要決定該怎麼做。可能的解決方法包括重新命名現有的 Amazon S3 儲存貯體、刪除未使用的目前 Amazon S3 儲存貯體，或是使用您嘗試建立的 Amazon S3 儲存貯體的新名稱。 如果您找不到帳戶中同名的 Amazon S3 儲存貯體，它可能會存在於不同的帳戶中。若要解決此問題，您需要自訂引導，才能為所有引導資源或僅建立 Amazon S3 儲存貯體的新名稱。若要為所有引導資源建立新名稱，您可以修改限定詞。若要僅為 Amazon S3 儲存貯體建立新的名稱，您可以提供新的儲存貯體名稱。 若要自訂引導，您可以使用選項搭配 CDK CLI `cdk bootstrap`命令或修改引導範本。如需說明，請參閱[自訂 AWS CDK 引導](bootstrapping-customizing.md)。 如果您自訂引導，則必須先將相同的變更套用至合成，才能正確部署應用程式。如需說明，請參閱[自訂 CDK 堆疊合成](configure-synth.md#bootstrapping-custom-synth)。 例如，您可以使用 提供新的限定詞`cdk bootstrap`： ``` $ cdk bootstrap --qualifier ``` 以下是將使用此修改建立的 Amazon S3 儲存貯體名稱範例：`cdk-abcde0123-assets-012345678910-us-west-1`。在引導期間建立的所有引導資源都會使用此限定詞。 開發 CDK 應用程式時，您必須在合成器中指定自訂限定詞。這有助於 CDK 在合成和部署期間識別您的引導資源。以下是為您的堆疊執行個體自訂預設合成器的範例： **Example** ``` new MyStack(this, 'MyStack', { synthesizer: new DefaultStackSynthesizer({ qualifier: 'abcde0123', }), }); ``` ``` new MyStack(this, 'MyStack', { synthesizer: new DefaultStackSynthesizer({ qualifier: 'abcde0123', }), }) ``` ``` MyStack(self, "MyStack", synthesizer=DefaultStackSynthesizer( qualifier="abcde0123" )) ``` ``` new MyStack(app, "MyStack", StackProps.builder() .synthesizer(DefaultStackSynthesizer.Builder.create() .qualifier("abcde0123") .build()) .build(); ) ``` ``` new MyStack(app, "MyStack", new StackProps { Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps { Qualifier = "abcde0123" }) }); ``` ``` func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack { var sprops awscdk.StackProps if props != nil { sprops = props.StackProps } stack := awscdk.NewStack(scope, &id, &sprops) synth := awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{ Qualifier: jsii.String("abcde0123"), }) stack.SetSynthesizer(synth) return stack } ``` 您也可以在 CDK 專案的 `cdk.json` 檔案中指定新的限定詞： ``` { "app": "...", "context": { "@aws-cdk/core:bootstrapQualifier": "abcde0123" } } ``` 若要僅修改 Amazon S3 儲存貯體名稱，您可以使用 ` --bootstrap-bucket-name `選項。以下是範例： ``` $ cdk bootstrap --bootstrap-bucket-name '' ``` 開發 CDK 應用程式時，您必須在合成器中指定新的儲存貯體名稱。以下是為您的堆疊執行個體自訂預設合成器的範例： **Example** ``` new MyStack(this, 'MyStack', { synthesizer: new DefaultStackSynthesizer({ fileAssetsBucketName: 'my-new-bucket-name', }), }); ``` ``` new MyStack(this, 'MyStack', { synthesizer: new DefaultStackSynthesizer({ fileAssetsBucketName: 'my-new-bucket-name', }), }) ``` ``` MyStack(self, "MyStack", synthesizer=DefaultStackSynthesizer( file_assets_bucket_name='my-new-bucket-name' )) ``` ``` new MyStack(app, "MyStack", StackProps.builder() .synthesizer(DefaultStackSynthesizer.Builder.create() .fileAssetsBucketName("my-new-bucket-name") .build()) .build(); ) ``` ``` new MyStack(app, "MyStack", new StackProps { Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps { FileAssetsBucketName = "my-new-bucket-name" }) }); ``` ``` func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack { var sprops awscdk.StackProps if props != nil { sprops = props.StackProps } stack := awscdk.NewStack(scope, &id, &sprops) synth := awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{ FileAssetsBucketName: jsii.String("my-new-bucket-name"), }) stack.SetSynthesizer(synth) return stack } ``` ### 預防 我們建議您主動引導您計劃使用的每個 AWS 環境。如需詳細資訊，請參閱[何時啟動您的環境](bootstrapping-env.md#bootstrapping-env-when)。特別是針對 Amazon S3 儲存貯體命名問題，這會在每個 AWS 環境中建立 Amazon S3 儲存貯體，並防止其他人使用您的 Amazon S3 儲存貯體名稱。