This is the AWS CDK v1 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and will now only receive critical bug fixes and security patches. New features will be developed for CDK v2 exclusively. Support for CDK v1 will end entirely on June 1, 2023. [Migrate to CDK v2](work-with-cdk-v2.md) to have access to the latest features and fixes. # Bootstrapping Deploying AWS CDK apps into an AWS [environment](environments.md) (a combination of an AWS account and region) may require that you provision resources the AWS CDK needs to perform the deployment. These resources include an Amazon S3 bucket for storing files and IAM roles that grant permissions needed to perform deployments. The process of provisioning these initial resources is called *bootstrapping*. An environment needs to be bootstrapped if any of the following apply. + An AWS CDK stack being deployed uses [Assets](assets.md). + An CloudFormation template generated by the app exceeds 50 kilobytes. + One or more of the stacks uses the `DefaultSynthesizer`. We will explain stack synthesizers in more detail shortly, but in brief, the `DefaultSynthesizer` is used if you have set the `@aws-cdk/core:newStyleStackSynthesis` [feature flag](featureflags.md) in your app's `cdk.json` *or* if you explicitly create a `DefaultSynthesizer` and pass it to your stack. [CDK Pipelines](cdk-pipeline.md) use the `DefaultSynthesizer`, so if your app uses CDK Pipelines, you must bootstrap the environments you will deploy into as well as the environment that contains the pipeline. The required resources are defined in a CloudFormation stack, called the *bootstrap stack*, which is usually named `CDKToolkit`. Like any CloudFormation stack, it appears in the CloudFormation console once it has been deployed. The AWS CDK supports two bootstrap templates. At this writing, the AWS CDK is transitioning from one of these templates to the other, but the original template (dubbed "legacy") is still the default. The newer template ("modern") is required by CDK Pipelines today, and will become the default at some point in the future. For details, see [Bootstrapping templates](#bootstrapping-templates). Environments are independent, so if you want to deploy to multiple environments (different AWS accounts or different regions in the same account), each environment must be bootstrapped separately. **Important** You may incur AWS charges for data stored in the bootstrapped resources. **Note** Older versions of the modern template created a Customer Master Key (CMK) in each bootstrapped environment by default. To avoid charges for the CMK, re-bootstrap these environments using `--no-bootstrap-customer-key`. The current default is to not use a CMK to avoid these charges. If you attempt to deploy an AWS CDK application that requires bootstrap resources into an environment that does not have them, you receive an error message telling you that you need to bootstrap. If you are using CDK Pipelines to deploy into another account's environment, and you receive a message like the following: ``` Policy contains a statement with one or more invalid principals ``` This error message means that the appropriate IAM roles do not exist in the other environment, which is most likely caused by a lack of bootstrapping. **Note** Do not delete and recreate an account's bootstrap stack if you are using CDK Pipelines to deploy into that account. The pipeline will stop working. To update the bootstrap stack to a new version, instead re-run `cdk bootstrap` to update the bootstrap stack in place. ## How to bootstrap Bootstrapping is the deployment of a CloudFormation template to a specific AWS environment (account and region). The bootstrapping template accepts parameters that customize some aspects of the bootstrapped resources (see [Customizing bootstrapping](#bootstrapping-customizing)). Thus, you can bootstrap in one of two ways. + Use the AWS CDK Toolkit's **cdk bootstrap** command. This is the simplest method and works well if you have only a few environments to bootstrap. + Deploy the template provided by the AWS CDK Toolkit using another CloudFormation deployment tool. This lets you use CloudFormation Stack Sets or AWS Control Tower as well as the CloudFormation console or the AWS CLI. You can even make small modifications to the template before deployment. This approach is more flexible and is suitable for large-scale deployments. It is not an error to bootstrap an environment more than once. If an environment you bootstrap has already been bootstrapped, its bootstrap stack will be upgraded if necessary; otherwise, nothing happens. ### Bootstrapping with the AWS CDK Toolkit Use the `cdk bootstrap` command to bootstrap one or more AWS environments. In its basic form, this command bootstraps one or more specified AWS environments (two, in this example). ``` cdk bootstrap aws://ACCOUNT-NUMBER-1/REGION-1 aws://ACCOUNT-NUMBER-2/REGION-2 ... ``` The following examples illustrate bootstrapping of one and two environments, respectively. (Both use the same AWS account.) As shown in the second example, the `aws://` prefix is optional when specifying an environment. ``` cdk bootstrap aws://123456789012/us-east-1 cdk bootstrap 123456789012/us-east-1 123456789012/us-west-1 ``` The CDK Toolkit always synthesizes the AWS CDK app in the current directory. If you do not specify at least one environment in the `cdk bootstrap` command, it bootstraps all the environments referenced in the app. If a stack is environment-agnostic (that is, it does not have an `env` property), the CDK's environment (for example, the one specified using **--profile**, or the default AWS environment otherwise) is applied to make the stack environment-specific, and that environment is then bootstrapped. For example, the following command synthesizes the current AWS CDK app using the `prod` AWS profile, then bootstraps its environments. ``` cdk bootstrap --profile prod ``` ### Bootstrapping from the CloudFormation template AWS CDK bootstrapping is performed by an CloudFormation template. To get a copy of this template in the file `bootstrap-template.yaml`, run the following command. ------ #### [ macOS/Linux ] ``` cdk bootstrap --show-template > bootstrap-template.yaml ``` ------ #### [ Windows ] On Windows, PowerShell must be used to preserve the encoding of the template. ``` powershell "cdk bootstrap --show-template | Out-File -encoding utf8 bootstrap-template.yaml" ``` ------ The template is also available in the [AWS CDK GitHub repository](https://github.com/aws/aws-cdk/blob/master/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml). Deploy this template using the CDK CLI or your preferred deployment mechanism for CloudFormation templates. To deploy using the CDK CLI, run **cdk bootstrap --template *TEMPLATE\$1FILENAME***. You can also deploy it using the AWS CLI by running the command below, or [deploy to one or more accounts at once using CloudFormation Stack Sets](https://aws.amazon.com/blogs/mt/bootstrapping-multiple-aws-accounts-for-aws-cdk-using-cloudformation-stacksets/). ------ #### [ macOS/Linux ] ``` aws cloudformation create-stack \ --stack-name CDKToolkit \ --template-body file://bootstrap-template.yaml ``` ------ #### [ Windows ] ``` aws cloudformation create-stack ^ --stack-name CDKToolkit ^ --template-body file://bootstrap-template.yaml ``` ------ ## Bootstrapping templates At this writing, the AWS CDK is transitioning from one set of bootstrap resources to another. The original bootstrap template, which shipped with the very first version of the AWS CDK, is called the **legacy** template. A newer version of the template with additional resources was added in version 1.25.0. This newer template is called the **modern** template. The legacy template is still fully supported by the AWS CDK and is in fact the template that is selected by default when you issue `cdk bootstrap`. The modern template is required primarily by the CDK Pipelines module, which can be used to set up a continuous delivery pipeline for your CDK applications. More precisely, the modern template is used by the `DefaultSynthesizer` (see [Stack synthesizers](#bootstrapping-synthesizers)), and CDK Pipelines requires this synthesizer, The main differences between the templates are as follows. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cdk/v1/guide/bootstrapping.html) \$1 *We will add additional resources to the modern template as needed.* In AWS CDK version 2, the modern template will be the default bootstrapping template. In version 1, manually select the modern template when bootstrapping by setting the `CDK_NEW_BOOTSTRAP` environment variable. ------ #### [ macOS/Linux ] ``` export CDK_NEW_BOOTSTRAP=1 cdk bootstrap aws://ACCOUNT-NUMBER/REGION ``` ------ #### [ Windows ] ``` set CDK_NEW_BOOTSTRAP=1 cdk bootstrap aws://ACCOUNT-NUMBER/REGION ``` ------ The modern template is also selected when you issue **cdk bootstrap** in an AWS CDK app directory where the `@aws-cdk/core:newStyleStackSynthesis` feature flag is set in the app's `cdk.json` file. ``` { // ... "context": { "@aws-cdk/core:newStyleStackSynthesis": true } } ``` **Tip** We recommend always setting `CDK_NEW_BOOTSTRAP` when you want to bootstrap using the modern template. The context key is supported to make sure you bootstrap correctly if your app uses the `DefaultStackSynthesizer`, but relies on you being in an app's directory when bootstrapping. These two ways to specify the modern template also apply to `cdk bootstrap --show-template`, which will display the modern template if either of these flags is present. If the environment you are bootstrapping with the modern template has already been bootstrapped with the legacy template, the environment is upgraded to the modern template. The Amazon S3 bucket from the legacy stack is orphaned in the process. Re-deploy all AWS CDK applications in the environment at least once before deleting the legacy bucket. ## Customizing bootstrapping There are two ways to customize the bootstrapping resources. + Use command-line parameters with the `cdk bootstrap` command. This lets you modify a few aspects of the template. + Modify the default bootstrap template and deploy it yourself. This gives you unlimited control over the bootstrap resources. The following command-line options, when used with CDK Toolkit's **cdk bootstrap**, provide commonly-needed adjustments to the bootstrapping template. + -**-bootstrap-bucket-name** overrides the name of the Amazon S3 bucket. May require changes to your CDK app (see [Stack synthesizers](#bootstrapping-synthesizers)). + **--bootstrap-kms-key-id** overrides the AWS KMS key used to encrypt the S3 bucket. + **--tags** adds one or more CloudFormation tags to the bootstrap stack. + **--termination-protection** prevents the bootstrap stack from being deleted (see [Protecting a stack from being deleted](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html) in the CloudFormation User Guide) The following additional switches are available only with the modern bootstrapping template. + **--cloudformation-execution-policies** specifies the ARNs of managed policies that should be attached to the deployment role assumed by CloudFormation during deployment of your stacks. By default, stacks are deployed with full administrator privileges using the `AdministratorAccess` policy. The policy ARNs must be passed as a single string argument, with the individual ARNs separated by commas. For example: ``` --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess". ``` **Important** To avoid deployment failures, be sure the policies you specify are sufficient for any deployments you will perform in the environment being bootstrapped. + **--trust** lists the AWS accounts that may deploy into the environment being bootstrapped. Use this flag when bootstrapping an environment that a CDK Pipeline in another environment will deploy into. The account doing the bootstrapping is always trusted. + **--trust-for-lookup** lists the AWS accounts that may look up context information from the environment being bootstrapped. Use this flag to give accounts permission to synthesize stacks that will be deployed into the environment, without actually giving them permission to deploy those stacks directly. + **--qualifier** a string that is added to the names of all resources in the bootstrap stack. A qualifier lets you avoid resource name clashes when you provision multiple bootstrap stacks in the same environment using **--toolkit-stack-name**. The default is `hnb659fds` (this value has no significance). Changing the qualifier also requires that your CDK app pass the changed value to the stack synthesizer(see [Stack synthesizers](#bootstrapping-synthesizers)). **Important** The modern bootstrap template effectively grants the permissions implied by the `--cloudformation-execution-policies` to any AWS account in the `--trust` list. By default, this extends permissions to read and write to any resource in the bootstrapped account. Make sure to [configure the bootstrapping stack](#bootstrapping-customizing) with policies and trusted accounts that you are comfortable with. ### Customizing the template When you need more customization than the AWS CDK Toolkit switches can provide, you can modify the bootstrap template to suit your needs. Remember that you can obtain the template by using the **--show-template** flag. Optionally, set the **CDK\$1NEW\$1BOOTSTRAP** environment variable to get the modern template (otherwise, you'll get the legacy template). ------ #### [ macOS/Linux ] ``` export CDK_NEW_BOOTSTRAP=1 cdk bootstrap --show-template ``` ------ #### [ Windows ] ``` set CDK_NEW_BOOTSTRAP=1 powershell "cdk bootstrap --show-template | Out-File -encoding utf8 bootstrap-template.yaml" ``` ------ Any modifications you make must adhere to the [bootstrapping template contract](#bootstrapping-contract). To ensure that your customizations are not accidentally overwritten later by someone running **cdk bootstrap** using the default template, change the default value of the `BootstrapVariant` template parameter. The CDK CLI will only allow overwriting the bootstrap stack with templates that have the same `BootstrapVariant` and a equal or higher version than the template that is currently deployed. Deploy your modified template as described in [Bootstrapping from the CloudFormation template](#bootstrapping-howto-cfn), or using **cdk bootstrap --template**. ``` cdk bootstrap --template bootstrap-template.yaml ``` ## Stack synthesizers Your AWS CDK app needs to know about the bootstrapping resources available to it in order to successfully synthesize a stack that can be deployed. The *stack synthesizer* is an AWS CDK class that controls how the stack's template is synthesized, including how it uses bootstrapping resources (for example, how it refers to assets stored in the bootstrap bucket). The AWS CDK includes two stack synthesizers: + `LegacyStackSynthesizer` can be used with either bootstrap template. (It requires only an Amazon S3 bucket, and both templates include one.) + `DefaultStackSynthesizer` requires the modern bootstrap template. It includes capabilities for cross-account deployments and [CDK Pipelines](cdk-pipeline.md) deployments. You can pass a stack synthesizer to a stack when you instantiate it using the `synthesizer` property. ------ #### [ TypeScript ] ``` new MyStack(this, 'MyStack', { // stack properties synthesizer: new DefaultStackSynthesizer({ // synthesizer properties }), }); ``` ------ #### [ JavaScript ] ``` new MyStack(this, 'MyStack', { // stack properties synthesizer: new DefaultStackSynthesizer({ // synthesizer properties }), }); ``` ------ #### [ Python ] ``` MyStack(self, "MyStack", # stack properties synthesizer=DefaultStackSynthesizer( # synthesizer properties )) ``` ------ #### [ Java ] ``` new MyStack(app, "MyStack", StackProps.builder() // stack properties .synthesizer(DefaultStackSynthesizer.Builder.create() // synthesizer properties .build()) .build(); ``` ------ #### [ C\$1 ] ``` new MyStack(app, "MyStack", new StackProps // stack properties { Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps { // synthesizer properties }) }); ``` ------ If you don't provide the `synthesizer` property, the default behavior depends on whether the context key `@aws-cdk/core:newStyleStackSynthesis` is set, either in the AWS CDK app's source code or in `cdk.json`. If it is set, synthesis uses a `DefaultStackSynthesizer`; otherwise, a `LegacyStackSynthesizer` is used. This is the usual way of choosing a synthesizer unless you have customized the bootstrap template. The most important differences between the two built-in stack synthesizers are summarized here. | Feature | LegacyStackSynthesizer | DefaultStackSynthesizer | | --- | --- | --- | | Bootstrap stack | Both legacy and modern bootstrap stack | Modern bootstrap stack only | | Deployments | AWS CDK Toolkit deployments only | AWS CDK Toolkit and CDK Pipelines deployments | | Assets | Uses CloudFormation parameters to reference assets | Expects assets to be in a predictable location | | Docker image assets | Creates Amazon ECR repository on demand | Pushes images to Amazon ECR repository provisioned by bootstrapping | | Roles | Uses AWS CDK Toolkit's current permissions to deploy | Uses roles and permissions provisioned by bootstrapping to deploy | | Versioning | Not supported | Confirms versions of bootstrapping resources via embedded CloudFormation rule | ## Customizing synthesis Depending on the changes you made to the bootstrap template, you may also need to customize synthesis. The `DefaultStackSynthesizer` can be customized using the properties described below. If none of these properties provide the customizations you require, you can write your synthesizer as a class that implements `IStackSynthesizer` (perhaps deriving from `DefaultStackSynthesizer`). **Note** The `LegacyStackSynthesizer` does not offer any customization properties. ### Changing the qualifier The *qualifier* is added to the name of bootstrap resources to distinguish the resources in separate bootstrap stacks. To deploy two different versions of the bootstrap stack in the same environment (AWS account and region), then, the stacks must have different qualifiers. This feature is intended for name isolation between automated tests of the CDK itself. Unless you can very precisely scope down the IAM permissions given to the CloudFormation execution role, there are no privilege isolation benefits to having two different bootstrap stacks in a single account, so there is usually no need to change this value. To change the qualifier, configure the `DefaultStackSynthesizer` either by instantiating the synthesizer with the property: ------ #### [ TypeScript ] ``` new MyStack(this, 'MyStack', { synthesizer: new DefaultStackSynthesizer({ qualifier: 'MYQUALIFIER', }), }); ``` ------ #### [ JavaScript ] ``` new MyStack(this, 'MyStack', { synthesizer: new DefaultStackSynthesizer({ qualifier: 'MYQUALIFIER', }), }) ``` ------ #### [ Python ] ``` MyStack(self, "MyStack", synthesizer=DefaultStackSynthesizer( qualifier="MYQUALIFIER" )) ``` ------ #### [ Java ] ``` new MyStack(app, "MyStack", StackProps.builder() .synthesizer(DefaultStackSynthesizer.Builder.create() .qualifier("MYQUALIFIER") .build()) .build(); ``` ------ #### [ C\$1 ] ``` new MyStack(app, "MyStack", new StackProps { Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps { Qualifier = "MYQUALIFIER" }) }); ``` ------ Or by configuring the qualifier as a context key in `cdk.json`. ``` { "app": "...", "context": { "@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER" } } ``` ### Changing the resource names All the other `DefaultStackSynthesizer` properties relate to the names of the resources in the modern bootstrapping template. You only need to provide any of these properties if you modified the bootstrap template and changed the resource names or naming scheme. All properties accept the special placeholders `${Qualifier}`, `${AWS::Partition}`, `${AWS::AccountId}`, and `${AWS::Region}`. These placeholders are replaced with the values of the `qualifier` parameter and with the values of the AWS partition, account ID, and region for the stack's environment, respectively. The following example shows the most commonly-used properties for `DefaultStackSynthesizer` along with their default values, as if you were instantiating the synthesizer. For a complete list, see [DefaultStackSynthesizerProps](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_core.DefaultStackSynthesizerProps.html#properties). ------ #### [ TypeScript ] ``` 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}', // 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 deploy 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 deploy 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, }) ``` ------ #### [ JavaScript ] ``` 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}', // 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 deploy 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 deploy 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, }) ``` ------ #### [ Python ] ``` 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}", # 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 deploy 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 deploy 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, ) ``` ------ #### [ Java ] ``` 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}") // 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 deploy 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 deploy 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() ``` ------ #### [ C\$1 ] ``` 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}", // 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 deploy 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 deploy 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, }) ``` ------ ## The bootstrapping template contract The requirements of the bootstrapping stack depend on the stack synthesizer in use. If you write your own stack synthesizer, you have complete control of the bootstrap resources that your synthesizer requires and how the synthesizer finds them. This section describes the expectations that the `DefaultStackSynthesizer` has of the bootstrapping template. ### Versioning The template should contain a resource to create an SSM parameter with a well-known name and an output to reflect the template's version. ``` 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] ``` ### Roles The `DefaultStackSynthesizer` requires five IAM roles for five different purposes. If you are not using the default roles, the synthesizer needs to be told the ARNs for the roles you want to use. The roles are: + The *deployment role* is assumed by the AWS CDK Toolkit and by AWS CodePipeline to deploy into an environment. Its `AssumeRolePolicy` controls who can deploy into the environment. The permissions this role needs can be seen in the template. + The *lookup role* is assumed by the AWS CDK Toolkit to perform context lookups in an environment. Its `AssumeRolePolicy` controls who can deploy into the environment. The permissions this role needs can be seen in the template. + The *file publishing role* and the *image publishing role* are assumed by the AWS CDK Toolkit and by AWS CodeBuild projects to publish assets into an environment: that is, to write to the S3 bucket and the ECR repository, respectively. These roles require write access to these resources. + *The CloudFormation execution role* is passed to CloudFormation to perform the actual deployment. Its permissions are the permissions that the deployment will execute under. The permissions are passed to the stack as a parameter that lists managed policy ARNs. ### Outputs The AWS CDK Toolkit requires that the following CloudFormation outputs exist on the bootstrap stack. + `BucketName`: the name of the file asset bucket + `BucketDomainName`: the file asset bucket in domain name format + `BootstrapVersion`: the current version of the bootstrap stack ### Template history The bootstrap template is versioned and evolves over time with the AWS CDK itself. If you provide your own bootstrap template, keep it up-to-date with the canonical default template to ensure that yours continues to work with all CDK features. This section contains a list of the changes made in each version. | Template version | AWS CDK version | Changes | | --- | --- | --- | | 1 | 1.40.0 | Initial version of template with Bucket, Key, Repository and Roles. | | 2 | 1.45.0 | Split asset publishing role into separate file and image publishing roles. | | 3 | 1.46.0 | Add FileAssetKeyArn export to be able to add decrypt permissions to asset consumers. | | 4 | 1.61.0 | KMS permissions are now implicit via S3 and no longer require FileAsetKeyArn, Add CdkBootstrapVersion SSM parameter so the bootstrap stack version can be verified without knowing the stack name. | | 5 | 1.87.0 | Deployment role can read SSM parameter. | | 6 | 1.108.0 | Add lookup role separate from deployment role. | | 6 | 1.109.0 | Attach aws-cdk:bootstrap-role tag to deployment, file publishing, and image publishing roles. | | 7 | 1.110.0 | Deployment role can no longer read Buckets in the target account directly (however, this role is effectively an administrator, and could always use its CloudFormation permissions to make the bucket readable anyway). | | 8 | 1.114.0 | The lookup role has full read-only permissions to the target environment, and has a aws-cdk:bootstrap-role tag as well. | | 9 | 1.135.0 | Fixes S3 asset uploads from being rejected by commonly referenced encryption SCP. | | 10 | 1.139.0 | ECR ScanOnPush is now enabled by default. | | 11 | 1.150.0 | Adds policy allowing Lambda to pull from Amazon ECR repos so it survives rebootstrapping. | | 12 | 1.152.0 | Adds support for experimental cdk import. | ## Security Hub Findings If you are using AWS Security Hub CSPM, you may see findings reported on some of the resources created by the AWS CDK Bootstrapping process. Security Hub CSPM findings help you find resource configurations you should double-check for accuracy and safety. We have reviewed these specific resource configurations with AWS Security and are confident they do not constitute a security problem. ### [KMS.2] IAM principals should not have IAM inline policies that allow decryption actions on all KMS keys The Deploy Role (default name `cdk-hnb659fds-deploy-role-ACCOUNT-REGION`) has permissions to read encrypted data stored in Amazon S3. The policy does not give permission to any data by itself: only data read from Amazon S3 can be decrypted, and only from buckets that explicitly allow the Deploy Role to read from them via their Bucket Policy, and keys that explicitly allow the Deploy Role to decrypt using them using their Key Policy. This statement is used to allow AWS CDK Pipelines to perform cross-account deployments. ** Why does Security Hub flag this? ** The policy contains a `Resource: *` combined with a `Condition` clause; Security Hub CSPM is flagging the `*`. The `*` is necessary because at the time the account is bootstrapped, the AWS KMS key created by AWS CDK Pipelines for the CodePipeline Artifact Bucket does not exist yet so we can't reference its ARN. In addition, Security Hub CSPM does not include the `Condition` clause in the policy statement in its reasoning. ** What if I want to fix this finding? ** As long as the resource policies on your AWS KMS keys are not unnecessarily permissive, the current Role policy does not allow the Deploy Role to access any more data than it should. If you still want to get rid of the finding, you can do so by customizing the bootstrap stack (using the process outlined above) in one of these 2 ways: + If you are not using AWS CDK Pipelines for cross-account deployments: remove the statement with `Sid: PipelineCrossAccountArtifactsBucket` from the deploy role; or + If you are using AWS CDK Pipelines for cross-account deployments: after deploying your AWS CDK Pipeline, look up the AWS KMS Key ARN of the Artifact Bucket and replace the `Resource: *` of the `Sid: PipelineCrossAccountArtifactsBucket` statement with the actual Key ARN.