這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 自訂 CDK 堆疊合成
您可以修改預設合成器、使用其他可用的內建合成器，或建立自己的合成器，來自訂 AWS 雲端開發套件 (AWS CDK) 堆疊合成。
AWS CDK 包含下列內建合成器，可用於自訂合成行為：
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html) – 如果您未指定合成器，則會自動使用此合成器。它支援使用 [CDK 管道](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html)建構的跨帳戶部署和部署。其引導合約需要具有已知名稱的現有 Amazon S3 儲存貯體、具有已知名稱的現有 Amazon ECR 儲存庫，以及具有已知名稱的五個現有 IAM 角色。預設引導範本符合這些要求。
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html) – 此合成器的引導合約需要現有的 Amazon S3 儲存貯體和現有的 Amazon ECR 儲存庫。它不需要任何 IAM 角色。為了執行部署，此合成器依賴 CDK CLI 使用者的許可，建議用於想要限制 IAM 部署憑證的組織。此合成器不支援跨帳戶部署或 CDK 管道。
+ [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.LegacyStackSynthesizer.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.LegacyStackSynthesizer.html) – 此合成器模擬 CDK v1 合成行為。其引導合約需要任意名稱的現有 Amazon S3 儲存貯體，並預期資產的位置會以 CloudFormation 堆疊參數的形式傳入。如果您使用此合成器，則必須使用 CDK CLI 來執行部署。
如果這些內建合成器都不適用於您的使用案例，您可以將自己的合成器撰寫為實作`IStackSynthesizer`或從 Construct Hub 查看[合成器](https://constructs.dev/search?q=synthesizer&cdk=aws-cdk)的類別。
## 自訂 `DefaultStackSynthesizer`
`DefaultStackSynthesizer` 是 AWS CDK 的預設合成器。它旨在允許跨帳戶部署 CDK 應用程式，以及從沒有明確支援 CDK 但支援定期 CloudFormation 部署的 CI/CD 系統部署 AWS CDK 應用程式，例如 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 環境中使用 AWS CDK 部署 。 |
| 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 parameter (SSM 參數) | Bootstrap 版本參數 | /cdk-bootstrap/hnb659fds/ | 引導範本的版本。引導範本和 CDK CLI 會使用它來驗證需求。 |
自訂 CDK 堆疊合成的一種方法是修改 [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html)。您可以使用`Stack`執行個體的 `synthesizer` 屬性，為單一 CDK 堆疊自訂此合成器。您也可以使用`App`執行個體的 `defaultStackSynthesizer` 屬性`DefaultStackSynthesizer`，針對 CDK 應用程式中的所有堆疊進行修改。
### 變更限定詞
*限定詞*會新增至引導期間建立的資源名稱。根據預設，此值為 `hnb659fds`。當您在引導期間修改限定詞時，您需要自訂 CDK 堆疊合成以使用相同的限定詞。
若要變更限定詞，請設定 的 `qualifier` 屬性，`DefaultStackSynthesizer`或將限定詞設定為 CDK 專案`cdk.json`檔案中的內容索引鍵。
以下是設定 `qualifier` 屬性的範例`DefaultStackSynthesizer`：
**Example**
```
new MyStack(this, 'MyStack', {
synthesizer: new DefaultStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
```
```
new MyStack(this, 'MyStack', {
synthesizer: new DefaultStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
})
```
```
MyStack(self, "MyStack",
synthesizer=DefaultStackSynthesizer(
qualifier="MYQUALIFIER"
))
```
```
new MyStack(app, "MyStack", StackProps.builder()
.synthesizer(DefaultStackSynthesizer.Builder.create()
.qualifier("MYQUALIFIER")
.build())
.build();
)
```
```
new MyStack(app, "MyStack", new StackProps
{
Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps
{
Qualifier = "MYQUALIFIER"
})
});
```
```
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("MYQUALIFIER"),
})
stack.SetSynthesizer(synth)
return stack
}
```
以下是在 中將限定詞設定為內容索引鍵的範例`cdk.json`：
```
{
"app": "...",
"context": {
"@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER"
}
}
```
### 變更資源名稱
所有其他`DefaultStackSynthesizer`屬性都與引導範本中的資源名稱相關。只有在您修改引導範本並變更資源名稱或命名方案時，才需要提供這些屬性。
所有屬性都接受特殊預留位置 `${Qualifier}`、`${AWS::AccountId}`、 `${AWS::Partition}`和 `${AWS::Region}`。這些預留位置會分別替換為 `qualifier` 參數的值，以及堆疊環境的 AWS 分割區、帳戶 ID 和 AWS 區域值。
下列範例顯示 最常使用的屬性`DefaultStackSynthesizer`及其預設值，就像您執行個體化合成器一樣。如需完整清單，請參閱[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizerProps.html#properties](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizerProps.html#properties)：
**Example**
```
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,
})
```
```
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,
})
```
```
DefaultStackSynthesizer(
# Name of the S3 bucket for file assets
file_assets_bucket_name="cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}",
bucket_prefix="",
# Name of the ECR repository for Docker image assets
image_assets_repository_name="cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}",
docker_tag_prefix="",
# ARN of the role assumed by the CLI and Pipeline to deploy here
deploy_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-deploy-role-${AWS::AccountId}-${AWS::Region}",
deploy_role_external_id="",
# ARN of the role used for file asset publishing (assumed from the CLI role)
file_asset_publishing_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-file-publishing-role-${AWS::AccountId}-${AWS::Region}",
file_asset_publishing_external_id="",
# ARN of the role used for Docker asset publishing (assumed from the CLI role)
image_asset_publishing_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-image-publishing-role-${AWS::AccountId}-${AWS::Region}",
image_asset_publishing_external_id="",
# ARN of the role passed to CloudFormation to execute the deployments
cloud_formation_execution_role="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
lookup_role_arn="arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-lookup-role-${AWS::AccountId}-${AWS::Region}",
lookup_role_external_id="",
# Name of the SSM parameter which describes the bootstrap stack version number
bootstrap_stack_version_ssm_parameter="/cdk-bootstrap/${Qualifier}/version",
# Add a rule to every template which verifies the required bootstrap stack version
generate_bootstrap_version_rule=True,
)
```
```
DefaultStackSynthesizer.Builder.create()
// 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}")
.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)
.build()
```
```
new DefaultStackSynthesizer(new DefaultStackSynthesizerProps
{
// 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}",
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 部署期間提供許可的安全登入資料，您可以使用 自訂合成[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html)。此合成器使用在引導期間建立的預設 AWS 資源來存放資產，例如 Amazon S3 儲存貯體和 Amazon ECR 儲存庫。不使用 CDK 在引導期間建立的預設 IAM 角色，而是使用啟動部署之演員的安全登入資料。因此，演員的安全登入資料必須具有執行所有部署動作的有效許可。下圖說明使用此合成器時的部署程序：
![\[使用 CLICredentialsStackSynthesizer 的部署程序。\]](http://docs.aws.amazon.com/zh_tw/cdk/v2/guide/images/CliCredentialsStackSynthesizer-deploy-process_cdk_flowchart.png)
使用 時`CliCredentialsStackSynthesizer`：
+ 根據預設，CloudFormation 會使用演員的許可在您的帳戶中執行 API 呼叫。因此，目前的身分必須具有對 CloudFormation 堆疊中的 AWS 資源進行必要變更的許可，以及執行必要 CloudFormation 操作的許可，例如 `CreateStack`或 `UpdateStack`。部署功能將僅限於演員的許可。
+ 資產發佈和 CloudFormation 部署將使用目前的 IAM 身分完成。此身分必須具有足夠的許可，才能讀取和寫入資產儲存貯體和儲存庫。
+ 查詢是使用目前的 IAM 身分執行，而查詢受其政策約束。
使用此合成器時，您可以使用 [`--role-arn`](ref-cli-cmd.md#ref-cli-cmd-options-role-arn)選項搭配任何 CDK CLI 命令來指定個別 CloudFormation 執行角色。
### `CliCredentialsStackSynthesizer` 引導合約
`CliCredentialsStackSynthesizer` 需要下列引導合約。這些是在引導期間必須建立的資源：
| 引導資源 | 描述 | 預設預期資源名稱 | 用途 |
| --- | --- | --- | --- |
| Amazon S3 儲存貯體 | 預備儲存貯體 | cdk-hnb659fds-assets-- | 存放檔案資產。 |
| Amazon ECR 儲存庫 | 預備儲存庫 | cdk-hnb659fds-container-assets-- | 存放和管理 Docker 映像資產。 |
資源名稱`hnb659fds`中的字串稱為 *限定詞*。其預設值沒有特殊意義。您可以在單一環境中有多個引導資源的副本，只要它們具有不同的限定詞即可。擁有多個複本有助於將相同環境中不同應用程式的資產分開。
您可以部署預設引導範本，以滿足 `CliCredentialsStackSynthesizer`的引導合約。預設引導範本會建立 IAM 角色，但此合成器不會使用這些角色。您也可以自訂引導範本來移除 IAM 角色。
### 修改 `CliCredentialsStackSynthesizer`
如果您在引導期間變更限定詞或任何預設引導資源名稱，則必須修改合成器以使用相同的名稱。您可以修改單一堆疊或應用程式中所有堆疊的合成器。以下是範例：
**Example**
```
new MyStack(this, 'MyStack', {
synthesizer: new CliCredentialsStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
```
```
new MyStack(this, 'MyStack', {
synthesizer: new CliCredentialsStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
})
```
```
MyStack(self, "MyStack",
synthesizer=CliCredentialsStackSynthesizer(
qualifier="MYQUALIFIER"
))
```
```
new MyStack(app, "MyStack", StackProps.builder()
.synthesizer(CliCredentialsStackSynthesizer.Builder.create()
.qualifier("MYQUALIFIER")
.build())
.build();
)
```
```
new MyStack(app, "MyStack", new StackProps
{
Synthesizer = new CliCredentialsStackSynthesizer(new CliCredentialsStackSynthesizerProps
{
Qualifier = "MYQUALIFIER"
})
});
```
下列範例顯示 最常使用的屬性`CliCredentialsStackSynthesizer`及其預設值。如需完整清單，請參閱[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizerProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizerProps.html)：
**Example**
```
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: '',
})
```
```
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: '',
})
```
```
CliCredentialsStackSynthesizer(
# Value for '${Qualifier}' in the resource names
qualifier="hnb659fds",
# Name of the S3 bucket for file assets
file_assets_bucket_name="cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}",
bucket_prefix="",
# Name of the ECR repository for Docker image assets
image_assets_repository_name="cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}",
docker_tag_prefix="",
)
```
```
CliCredentialsStackSynthesizer.Builder.create()
// 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('')
.build()
```
```
new CliCredentialsStackSynthesizer(new CliCredentialsStackSynthesizerProps
{
// 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 部署的行為。執行部署之演員的安全登入資料將用於建立許可。檔案資產將上傳至必須使用名為 的 a AWS CloudFormation 堆疊建立的儲存貯體`CDKToolkit`。CDK CLI 會建立名為 的未受管 Amazon ECR 儲存庫`aws-cdk/assets`，以存放 Docker 映像資產。您將負責清除和管理此儲存庫。使用 合成的 Stacks `LegacyStackSynthesizer` 只能使用 CDK CLI 部署。
`LegacyStackSynthesizer` 如果您要從 CDK v1 遷移至 CDK v2，且無法重新引導您的環境，您可以使用 。對於新專案，我們建議您不要使用 `LegacyStackSynthesizer`。
### `LegacyStackSynthesizer` 引導合約
`LegacyStackSynthesizer` 需要下列引導合約。這些是在引導期間必須建立的資源：
| Bootstrap 資源 | 描述 | 預設預期資源名稱 | 用途 |
| --- | --- | --- | --- |
| Amazon S3 儲存貯體 | 預備儲存貯體 | cdk-hnb659fds-assets-- | 存放檔案資產。 |
| CloudFormation 輸出 | 儲存貯體名稱輸出 | 堆疊 – `CDKToolkit` 輸出名稱 – `BucketName` | 描述預備儲存貯體名稱的 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 堆疊。在此堆疊中，CDK 會CLI讀取名為 的 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 參數的形式傳遞。