這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護,並於 2023 年 6 月 1 日結束支援。
本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
您可以修改預設合成器、使用其他可用的內建合成器,或建立自己的合成器,來自訂 AWS Cloud Development Kit (AWS CDK) 堆疊合成。
AWS CDK 包含下列內建合成器,可用於自訂合成行為:
-
DefaultStackSynthesizer
– 如果您未指定合成器,則會自動使用此合成器。它支援使用CDK管道建構的跨帳戶部署和部署。其引導合約需要具有已知名稱的現有 Amazon S3 儲存貯體、具有已知名稱的現有 Amazon ECR儲存庫,以及具有已知名稱的五個現有IAM角色。預設引導範本符合這些要求。 -
CliCredentialsStackSynthesizer
– 此合成器的引導合約需要現有的 Amazon S3 儲存貯體和現有的 Amazon ECR儲存庫。它不需要任何IAM角色。為了執行部署,此合成器依賴 的許可 CDK CLI 使用者,建議用於想要限制IAM部署憑證的組織。此合成器不支援跨帳戶部署或CDK管道。 -
LegacyStackSynthesizer
– 此合成器模擬 CDK v1 合成行為。其引導合約需要具有任意名稱的現有 Amazon S3 儲存貯體,並預期將資產的位置作為 CloudFormation 堆疊參數傳入。如果您使用此合成器,則必須使用 CDK CLI 來執行部署。
如果這些內建合成器都不適用於您的使用案例,您可以將自己的合成器撰寫為實作IStackSynthesizer
或查看 合成器
自訂 DefaultStackSynthesizer
DefaultStackSynthesizer
是 的預設合成器 AWS CDK。它旨在允許跨帳戶部署CDK應用程式,以及從 CI/CD 系統部署應用程式,這些CDK系統未明確支援 AWS CDK,但支援定期 CloudFormation 部署,例如 AWS CodePipeline。此合成器是大多數使用案例的最佳選項。
DefaultStackSynthesizer
引導合約
DefaultStackSynthesizer
需要下列引導合約。這些是在引導期間必須建立的資源:
引導資源 | 描述 | 預設預期資源名稱 | 用途 |
---|---|---|---|
Amazon S3 儲存貯體 |
預備儲存貯體 |
cdk-hnb659fds-assets- |
存放檔案資產。 |
Amazon ECR儲存庫 |
預備儲存庫 |
cdk-hnb659fds-container-assets- |
存放和管理 Docker 映像資產。 |
IAM 角色 |
部署角色 |
cdk-hnb659fds-deploy-role- |
由 擔任 CDK CLI 和 CodePipeline 可能擔任其他角色並開始 AWS CloudFormation 部署。 此角色的信任政策會控制誰可以 AWS CDK 在此 AWS 環境中使用 部署 。 |
IAM 角色 |
AWS CloudFormation 執行角色 |
cdk-hnb659fds-cfn-exec-role- |
此角色 AWS CloudFormation 由 用來執行部署。 此角色的政策會控制CDK部署可執行的操作。 |
IAM 角色 |
查詢角色 |
cdk-hnb659fds-lookup-role- |
當 時,會使用此角色 CDK CLI 需要執行環境內容查詢。 此角色的信任政策會控制誰可以查詢環境中的資訊。 |
IAM 角色 |
檔案發佈角色 |
cdk-hnb659fds-file-publishing-role- |
此角色用於將資產上傳至 Amazon S3 預備儲存貯體。它從部署角色擔任。 |
IAM 角色 |
影像發佈角色 |
cdk-hnb659fds-image-publishing-role- |
此角色用於上傳 Docker 映像到 Amazon ECR 預備儲存庫。它從部署角色擔任。 |
SSM 參數 |
Bootstrap 版本參數 |
/cdk-bootstrap/hnb659fds/ |
引導範本的版本。它由引導範本和 CDK CLI 驗證需求。 |
自訂CDK堆疊合成的一種方法是修改 DefaultStackSynthesizer
。您可以使用Stack
執行個體的 synthesizer
屬性,為單一CDK堆疊自訂此合成器。您也可以使用App
執行個體的 defaultStackSynthesizer
屬性DefaultStackSynthesizer
,針對CDK應用程式中的所有堆疊進行修改。
變更限定詞
限定詞會新增至引導期間建立的資源名稱。根據預設,此值為 hnb659fds
。當您在引導期間修改限定詞時,您需要自訂CDK堆疊合成以使用相同的限定詞。
若要變更限定詞,請設定 屬性,qualifier
DefaultStackSynthesizer
或將限定詞設定為CDK專案cdk.json
檔案中的內容索引鍵。
以下是設定 qualifier
屬性的範例DefaultStackSynthesizer
:
new MyStack(this, 'MyStack', {
synthesizer: new DefaultStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
以下是在 中將限定詞設定為內容索引鍵的範例cdk.json
:
{
"app": "...",
"context": {
"@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER"
}
}
變更資源名稱
所有其他DefaultStackSynthesizer
屬性都與引導範本中的資源名稱相關。只有在您修改引導範本並變更資源名稱或命名方案時,才需要提供這些屬性中的任何一個。
所有屬性都接受特殊預留位置 ${Qualifier}
、${AWS::AccountId}
、 ${AWS::Partition}
和 ${AWS::Region}
。這些預留位置會分別替換為 qualifier
參數的值,以及堆疊環境的 AWS 分割區、帳戶 ID 和 AWS 區域 值。
下列範例顯示 最常使用的屬性DefaultStackSynthesizer
及其預設值,就像您執行個體化合成器一樣。如需完整清單,請參閱DefaultStackSynthesizerProps:
new DefaultStackSynthesizer({
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
// ARN of the role assumed by the CLI and Pipeline to deploy here
deployRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-deploy-role-${AWS::AccountId}-${AWS::Region}',
deployRoleExternalId: '',
// ARN of the role used for file asset publishing (assumed from the CLI role)
fileAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-file-publishing-role-${AWS::AccountId}-${AWS::Region}',
fileAssetPublishingExternalId: '',
// ARN of the role used for Docker asset publishing (assumed from the CLI role)
imageAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-image-publishing-role-${AWS::AccountId}-${AWS::Region}',
imageAssetPublishingExternalId: '',
// ARN of the role passed to CloudFormation to execute the deployments
cloudFormationExecutionRole: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-cfn-exec-role-${AWS::AccountId}-${AWS::Region}',
// ARN of the role used to look up context information in an environment
lookupRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-lookup-role-${AWS::AccountId}-${AWS::Region}',
lookupRoleExternalId: '',
// Name of the SSM parameter which describes the bootstrap stack version number
bootstrapStackVersionSsmParameter: '/cdk-bootstrap/${Qualifier}/version',
// Add a rule to every template which verifies the required bootstrap stack version
generateBootstrapVersionRule: true,
})
使用 CliCredentialsStackSynthesizer
若要修改用於在CDK部署期間提供許可的安全登入資料,您可以使用 自訂合成CliCredentialsStackSynthesizer
。此合成器使用在引導期間建立的預設 AWS 資源來存放資產,例如 Amazon S3 儲存貯體和 Amazon ECR儲存庫。不使用 於引導CDK期間建立的預設IAM角色,而是使用啟動部署之演員的安全登入資料。因此,演員的安全登入資料必須具有執行所有部署動作的有效許可。下圖說明使用此合成器時的部署程序:
使用 時CliCredentialsStackSynthesizer
:
-
根據預設, 會使用演員的許可,在您的帳戶中 CloudFormation 執行API呼叫。因此,目前的身分必須具有許可,才能對 CloudFormation 堆疊中的 AWS 資源進行必要的變更,以及執行必要 CloudFormation 操作的許可,例如
CreateStack
或UpdateStack
。部署功能將僅限於演員的許可。 -
資產發佈和 CloudFormation 部署將使用目前的IAM身分完成。此身分必須具有足夠的許可,才能讀取和寫入資產儲存貯體和儲存庫。
-
查詢是使用目前的IAM身分執行,而查詢受其政策約束。
使用此合成器時,您可以使用 CloudFormation --role-arn
選項搭配任何 CDK CLI 命令。
CliCredentialsStackSynthesizer
引導合約
CliCredentialsStackSynthesizer
需要下列引導合約。這些是在引導期間必須建立的資源:
引導資源 | 描述 | 預設預期資源名稱 | 用途 |
---|---|---|---|
Amazon S3 儲存貯體 |
預備儲存貯體 |
cdk-hnb659fds-assets- |
存放檔案資產。 |
Amazon ECR儲存庫 |
預備儲存庫 |
cdk-hnb659fds-container-assets- |
存放和管理 Docker 映像資產。 |
資源名稱hnb659fds
中的字串稱為限定詞。其預設值沒有特殊意義。您可以在單一環境中有多個引導資源的複本,只要它們具有不同的限定詞即可。擁有多個複本對於將相同環境中不同應用程式的資產保持隔離非常有用。
您可以部署預設引導範本,以滿足 CliCredentialsStackSynthesizer
的引導合約。預設引導範本會建立IAM角色,但此合成器不會使用這些角色。您也可以自訂引導範本來移除IAM角色。
修改 CliCredentialsStackSynthesizer
如果您在引導期間變更限定詞或任何預設引導資源名稱,則必須修改合成器以使用相同的名稱。您可以修改單一堆疊或應用程式中所有堆疊的合成器。以下是範例:
new MyStack(this, 'MyStack', {
synthesizer: new CliCredentialsStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
下列範例顯示 最常使用的屬性CliCredentialsStackSynthesizer
及其預設值。如需完整清單,請參閱CliCredentialsStackSynthesizerProps:
new CliCredentialsStackSynthesizer({
// Value for '${Qualifier}' in the resource names
qualifier: 'hnb659fds',
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
})
使用 LegacyStackSynthesizer
LegacyStackSynthesizer
模擬 CDK v1 部署的行為。執行部署之演員的安全登入資料將用於建立許可。檔案資產將上傳至必須使用名為 的 AWS CloudFormation 堆疊建立的儲存貯體CDKToolkit
。CDK CLI 將建立名為 的未受管 Amazon ECR儲存庫aws-cdk/assets
來存放 Docker 映像資產。您將負責清除和管理此儲存庫。使用 合成的堆疊LegacyStackSynthesizer
只能使用 部署 CDK CLI.
LegacyStackSynthesizer
如果您要從 CDK v1 遷移到 CDK v2,且無法重新引導您的環境,您可以使用 。對於新專案,我們建議您不要使用 LegacyStackSynthesizer
。
LegacyStackSynthesizer
引導合約
LegacyStackSynthesizer
需要下列引導合約。這些是在引導期間必須建立的資源:
引導資源 | 描述 | 預設預期資源名稱 | 用途 |
---|---|---|---|
Amazon S3 儲存貯體 |
預備儲存貯體 |
cdk-hnb659fds-assets- |
存放檔案資產。 |
CloudFormation 輸出 |
儲存貯體名稱輸出 |
堆疊 – 輸出名稱 – |
描述預備儲存貯體名稱的 CloudFormation 輸出 |
LegacyStackSynthesizer
不會假設存在具有固定名稱的 Amazon S3 儲存貯體。反之,合成的 CloudFormation 範本將包含每個檔案資產的三個 CloudFormation 參數。這些參數將存放每個檔案資產的 Amazon S3 儲存貯體名稱、Amazon S3 物件金鑰和成品雜湊。
Docker 映像資產將發佈至名為 的 Amazon ECR儲存庫aws-cdk/assets
。每個資產都可以變更此名稱。如果儲存庫不存在,則會建立儲存庫。
CloudFormation 堆疊必須具有預設名稱 CDKToolkit
。此堆疊必須具有 CloudFormation一個名為 的匯出BucketName
,該匯出是指預備儲存貯體。
預設引導範本可滿足LegacyStackSynthesizer
引導合約。不過,只會使用來自引導範本之引導資源的 Amazon S3 儲存貯體。您可以自訂引導範本來移除 Amazon ECR、 IAM和SSM引導資源。
LegacyStackSynthesizer
部署程序
當您使用此合成器時,會在部署期間執行下列程序:
-
CDK CLI 會在您的環境中尋找名為
CDKToolkit
的 CloudFormation 堆疊。從此堆疊中, CDKCLI 會讀取名為 的 CloudFormation 輸出BucketName
。您可以使用--toolkit-stack-name
選項cdk deploy
來指定不同的堆疊名稱。 -
啟動部署之演員的安全登入資料將用於建立部署許可。因此,演員必須有足夠的許可才能執行所有部署動作。這包括讀取和寫入 Amazon S3 預備儲存貯體、建立和寫入 Amazon ECR儲存庫、啟動和監控 AWS CloudFormation 部署,以及執行部署所需的任何API呼叫。
-
如有必要且許可有效,檔案資產將發佈至 Amazon S3 預備儲存貯體。
-
如有必要,如果許可有效,Docker 映像資產會發佈至資產的
repositoryName
屬性所命名的儲存庫。'aws-cdk/assets'
如果您不提供儲存庫名稱,則預設值為 。 -
如果許可有效,則會執行 AWS CloudFormation 部署。Amazon S3 預備儲存貯體和金鑰的位置會以 CloudFormation 參數形式傳遞。