這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 自訂 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)。