自訂 AWS CDK 引導 - AWS Cloud Development Kit (AWS CDK) v2
使用自訂CDKCLI啟動載入修改預設的啟動程序範本引導合同

這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

自訂 AWS CDK 引導

您可以使用 AWS CDK 命令列介面 (AWS CDK CLI) 或修改和部署 AWS Cloud Development Kit (AWS CDK) 啟動程序範本來自訂 AWS CloudFormation 啟動載入。

如需引導載入的簡介，請參閱。AWS CDK 引導

使用自訂CDKCLI啟動載入

以下是一些如何使用自訂啟動載入的範例。CDK CLI如需所有cdk bootstrap選項的清單，請參閱cdk bootstrap。

覆寫 Amazon S3 存儲桶的名稱

使用--bootstrap-bucket-name此選項覆寫預設的 Amazon S3 儲存貯體名稱。這可能需要您修改模板合成。如需詳細資訊，請參閱自訂CDK堆疊合成。

修改 Amazon S3 儲存貯體的伺服器端加密金鑰

根據預設，啟動程序堆疊中的 Amazon S3 儲存貯體設定為使用 AWS 受管金鑰進行伺服器端加密。若要使用現有的客戶管理金鑰，請使用--bootstrap-kms-key-id選項並提供要使用的 AWS Key Management Service (AWS KMS) 金鑰值。如果您想要進一步控制加密金鑰，請提供--bootstrap-customer-key使用客戶管理的金鑰。

將受管理的政策附加至以下項目的部署角色 AWS CloudFormation

根據預設，堆疊會使用該AdministratorAccess原則以完整的管理員權限部署。若要使用您自己ARNs的受管理原則，請使用--cloudformation-execution-policies選項並提供要附加至部署角色的受管理原則。

若要提供多個原則，請將單一字串傳遞給它們，並以逗號分隔：

$ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess"

若要避免部署失敗，請確定您指定的原則對於要在啟動載入的環境中執行的任何部署都足夠。

更改添加到引導程序堆棧中資源名稱的限定符

預設情況下，hnb659fds限定詞會新增至啟動程序堆疊中資源的實體 ID。若要變更此值，請使用--qualifier選項。

在相同環境中佈建多個啟動程序堆疊以避免名稱衝突時，此修改非常有用。

更改限定符旨在用於CDK本身的自動化測試之間的名稱隔離。除非您可以非常精確地IAM限定給予 CloudFormation 執行角色的權限範圍，否則在單個帳戶中擁有兩個不同的引導堆棧沒有權限隔離好處。因此，通常不需要變更此值。

當您更改限定符時，您的CDK應用程序必須將更改後的值傳遞給堆棧合成器。如需詳細資訊，請參閱自訂CDK堆疊合成。

將標籤新增至啟動程序堆疊

使用格式中的--tags選項，將 CloudFormation 標籤新增KEY=VALUE至啟動程序堆疊。

指定可 AWS 帳戶 部署到正在啟動載入的環境中的其他

使用此選--trust項可提供允 AWS 帳戶 許部署至啟動載入環境的其他選項。依預設，執行啟動載入的帳戶永遠會受到信任。

當您啟動安裝CDKPipeline從另一個環境將部署到的環境時，此選項非常有用。

當您使用此選項時，您還必須提供--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此選項可管理啟動程序堆疊的終止保護設定。透過啟用終止保護，您可以防止意外刪除啟動程序堆疊及其資源。如果您使用，這一點尤其重要，CDKPipelines因為如果您不小心刪除了引導程序堆棧，則沒有常規恢復選項。

啟用終止保護後，您可以使用 AWS CLI 或 AWS CloudFormation 控制台進行驗證。

啟用終止保護

  1. 執行下列命令，以在新的或現有的啟動程序堆疊上啟用終止保護：

    $ cdk bootstrap --termination-protection

  2. 使用 AWS CLI 或 CloudFormation 控制台進行驗證。以下是使用 AWS CLI的範例。如果您修改了引導程序堆棧名稱，請CDKToolkit替換為堆棧名稱：

    $ aws cloudformation describe-stacks --stack-name CDKToolkit --query "Stacks[0].EnableTerminationProtection"
true

修改預設的啟動程序範本

當您需要比CDKCLI可以提供的更多自訂項目時，您可以視需要修改啟動程序範本。然後，部署範本以啟動您的環境。

若要修改和部署預設啟動程序範本

  1. 使用--show-template選項取得預設啟動程序範本。默認情況下，CDKCLI將在終端窗口中輸出模板。您可以修改指CDKCLI令，將樣板儲存至本端電腦。以下是範例：

    $ cdk bootstrap --show-template > my-bootstrap-template.yaml

  2. 視需要修改啟動程序範本。您所做的任何更改都應遵守引導模板合同。如需啟動載入範本合約的詳細資訊，請參閱。按照引導合同

    若要確保稍後不會被使用預設範本執行的cdk bootstrap使用者意外覆寫您的自訂，請變更 BootstrapVariant template 參數的預設值。只允許使用與目前部署的範本具有相同BootstrapVariant且等於或更高版本的範本覆寫啟動程序堆疊。CDK CLI

  3. 使用偏好的 AWS CloudFormation 部署方法部署修改過的範本。以下是使用的範例 CDKCLI：

    $ cdk bootstrap --template my-bootstrap-template.yaml

按照引導合同

為了使您的CDK應用程序正確部署，在合成過程中生成的 CloudFormation 模板必須正確指定在引導過程中創建的資源。這些資源通常稱為引導資源。啟動安裝可在您的 AWS 環境中建立資源，供執行部署和管理應用程式資產使用。 AWS CDK 合成從應用程序中的每個CDK堆棧生成 CloudFormation 模板。這些範本不僅定義將從您的應用程式佈建的 AWS 資源。它們還指定部署期間要使用的啟動程序資源。

在合成過程中，CDKCLI不知道具體如何您的 AWS 環境已啟動載入。相反地，會根據您設定的合成器CDKCLI產生 CloudFormation 範本。因此，當您自定義引導載入時，可能需要自定義合成。如需自訂合成的指示，請參閱自訂CDK堆疊合成。目的是確保您的合成 CloudFormation 模板與引導環境兼容。此相容性稱為啟動程序合約。

自訂堆疊合成的最簡單方法是修改Stack執行個體中的DefaultStackSynthesizer類別。如果你需要超出這個類可以提供的定制，你可以編寫你自己的合成器作為一個實現IStackSynthesizer（也許派生自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對象ARNs中指定您的IAM角色。角色如下：

  • 部署角色由CDKCLI和假設，以部署 AWS CodePipeline 到環境中。它AssumeRolePolicy控制誰可以部署到環境中。在範本中，您可以看到此角色所需的權限。

  • 查詢角色由假定在環境中執行前後關聯查詢。CDK CLI它AssumeRolePolicy控制誰可以部署到環境中。您可以在範本中看到此角色所需的權限。

  • 檔案發佈角色和影像發佈角色由CDKCLI和由 AWS CodeBuild 專案承擔，以將資產發佈到環境中。它們用於分別寫入 Amazon S3 存儲桶和 Amazon ECR 存儲庫。這些角色需要這些資源的寫入權限。

  • AWS CloudFormation 執行角色會傳遞 AWS CloudFormation 給以執行實際部署。其權限是部署將在其下執行的權限。權限會作為列出受管理原則的參數傳遞至堆疊ARNs。

輸出

要CDKCLI求啟動程序堆棧上存在以下 CloudFormation 輸出：

  • BucketName— 檔案資產值區的名稱。

  • BucketDomainName— 網域名稱格式的檔案資產儲存貯體。

  • BootstrapVersion— 啟動程序堆疊的目前版本。

模板歷史

引導程序模板是版本化的，並隨著時間的 AWS CDK 推移而發展。如果您提供自己的引導模板，請使用規範的默認模板保持最新狀態。您要確保範本可繼續使用所有CDK功能。如需詳細資訊，請參閱Bootstrap 範本版本歷史記錄。