How do I customize my AWS CDK bootstrap and deploy the CFNToolkit CloudFormation stack?

Short description

To use AWS CDK, you must bootstrap your AWS account. The bootstrap action creates the resources required by AWS CDK on the account. You can customize your bootstrap template to implement compliance and security requirements with the following actions:

• Add tags to resources.
• Add encryption for Amazon Simple Storage Service (Amazon S3) buckets.
• Use custom S3 bucket names.
• Use existing S3 buckets or apply the least privileged principal on the AWS Identity and Access Management (IAM) roles generated by the bootstrap template.

The cdk bootstrap command creates a CloudFormation stack with the name CDKToolkit. The resources deployed in the CDKToolkit CloudFormation stack come from the template.

To show your bootstrap template, run the following command:

cdk bootstrap --show-template > bootstrap-template.yml

The preceding bootstrap template has the following resources:

• Resources such as the S3 bucket
• AWS Key Management Service (AWS KMS) key
• IAM roles
• SSM parameter for versioning

For more information, see AWS CDK Bootstrap Template for Custom Bootstrapping on the GitHub website.

You can customize your bootstrap template for the following use cases:

• Use AWS CDK to deploy only the resources that you use.
• Update or create a custom qualifier and name for an S3 bucket to store AWS CDK app file assets.
• Use an existing S3 bucket to hold AWS CDK app file assets.

Resolution

To customize your bootstrap template, use one of the following methods:

Use AWS CDK to deploy only the resources that you use

AWS CDK bootstrap creates a role CloudFormationExecutionRole that CloudFormation assumes to deploy your stack. CloudFormation then uses this role to deploy from your local machine with the cdk deploy command or to deploy through AWS CDK pipelines for CI/CD.

To allow resources to be created with AWS CDK, the CloudFormationExecutionRole has the arn:aws:iam:aws:policy/AdministratorAccess policy that grants full access to perform all actions. Note that this policy goes against the least privilege principle. To restrict this policy, you must create a new policy and then bootstrap AWS CDK with the new custom policy.

Note: Make sure to review all commands and replace all instances of example strings with your required values.

1. Create a custom policy in IAM:

   aws iam create-policy \
     --policy-name cdkCFExecutionPolicy \
     --policy-document file://example-custom-Execution-Policy-name.json

2. Use the newly created IAM policy to bootstrap the AWS CDK:

   ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
   cdk bootstrap aws://$ACCOUNT_ID/example-Region \
     --cloudformation-execution-policies "arn:aws:iam::$ACCOUNT_ID:policy/example-custom-Execution-Policy-name"

3. (Optional) if the account is already bootstrapped, then rerun the cdk bootstrap command with the new custom policy.

4. (Optional) Update your policy as required by the AWS CDK application create a new policy version. New policy versions can be set as the default policy.

Note: Only five policy versions can be saved in IAM. Delete earlier versions as required if you update your policy.

Update or create a custom qualifier and name for an S3 bucket to store AWS CDK app file assets

1. Pass additional flags for qualifier and bootstrap-bucket-name to bootstrap the account. These flags create or update the CDKToolkit CloudFormation stack with new values for the resources.

   cdk bootstrap --template bootstrap-template.yml --qualifier <example-custom-qualifier-value> --bootstrap-bucket-name <example-custom-bucket-name> --profile <example-profile-name>

2. Update the app.py file with the following values:

   import os 
   import aws_cdk as cdk 
   from myproject.myproject_stack import MyprojectStack 
   app = cdk.App() 
   MyprojectStack(app, "MyprojectStack", synthesizer=cdk.DefaultStackSynthesizer(qualifier="<example-custom-qualifier-value>", file_assets_bucket_name="<example-custom-bucket-name>"))
   app.synth()

Note: If the CDKToolkit stack fails to deploy because of a resource that already exists, first identify and delete the resource if it's not needed. Then, perform the bootstrap from the CloudFormation stack again.

Use an existing S3 bucket to hold AWS CDK app file assets

AWS CDK applications use the S3 bucket name and location from the CDKToolkit AWS CloudFormation Stack > Outputs section. To use an existing S3 bucket, you must modify the bootstrap-template.yml:

1. Modify the Outputs value for BucketName and BucketDomainName with your existing S3 bucket details:

   Outputs:
       BucketName:
           Description: The name of S3 bucket owned by the CDK toolkit stack
           Value: <example-existing-bucket-name>
       BucketDomainName:
           Description: The domain name of the S3 bucket owned by the CDK toolkit stack
           Value: <example-existing-bucket-name>.s3.<example-Region>.amazonaws.com

2. Add the ARN of the existing S3 bucket in the DeploymentActionRole and FilePublishingRoleDefaultPolicy resources of the bootstrap-template.yml:

   Resources:
       DeploymentActionRole:
           Type: AWS::IAM::Role
           Properties:
             AssumeRolePolicyDocument:
               Statement:
                 - Action: sts:AssumeRole
                   Effect: Allow
                   Principal:
                     AWS:
                       Ref: AWS::AccountId
                 - Fn::If:
                     - HasTrustedAccounts
                     - Action: sts:AssumeRole
                       Effect: Allow
                       Principal:
                         AWS:
                           Ref: TrustedAccounts
                     - Ref: AWS::NoValue
             Policies:
               - PolicyDocument:
                   Statement:
                     - Sid: CliStagingBucket
                       Effect: Allow
                       Action:
                         - s3:GetObject*
                         - s3:GetBucket*
                         - s3:List*
                       Resource:
                         - Fn::Sub: ${StagingBucket.Arn}
                         - Fn::Sub: ${StagingBucket.Arn}/*
                         - arn:aws:s3:::<example-existing-bucket-name>
                         - arn:aws:s3:::<example-existing-bucket-name>/
                   Version: "example-version"
                 PolicyName: default
             RoleName:
               Fn::Sub: cdk-${Qualifier}-deploy-role-${AWS::AccountId}-${AWS::Region}
             Tags:
               - Key: aws-cdk:bootstrap-role
                 Value: deploy
       FilePublishingRoleDefaultPolicy:
           Type: AWS::IAM::Policy
           Properties:
             PolicyDocument:
               Statement:
                 - Action:
                     - s3:GetObject*
                     - s3:GetBucket*
                     - s3:GetEncryptionConfiguration
                     - s3:List*
                     - s3:DeleteObject*
                     - s3:PutObject*
                     - s3:Abort*
                   Resource:
                     - Fn::Sub: ${StagingBucket.Arn}
                     - Fn::Sub: ${StagingBucket.Arn}/*
                     - arn:aws:s3:::<example-existing-bucket-name>/
                     - arn:aws:s3:::<example-existing-bucket-name>
                   Effect: Allow
                 - Action:
                     - kms:Decrypt
                     - kms:DescribeKey
                     - kms:Encrypt
                     - kms:ReEncrypt*
                     - kms:GenerateDataKey*
                   Effect: Allow
                   Resource:
                     Fn::If:
                       - CreateNewKey
                       - Fn::Sub: ${FileAssetsBucketEncryptionKey.Arn}
                       - Fn::Sub: arn:${AWS::Partition}:kms:${AWS::Region}:${AWS::AccountId}:key/${FileAssetsBucketKmsKeyId}
               Version: "example-version"
             Roles:
               - Ref: FilePublishingRole
             PolicyName:
               Fn::Sub: cdk-${Qualifier}-file-publishing-role-default-policy-${AWS::AccountId}-${AWS::Region}

3. Run the cdk bootstrap command. The CDKToolkit CloudFormation stack is created or updated with the preceding changes.

4. To upload the file assets to your existing S3 bucket within your project, edit the stack synthesizer for CDK. Include the following in your app.py file:

   MyprojectStack(app, "MyprojectStack", synthesizer=cdk.DefaultStackSynthesizer(file_assets_bucket_name="<example-existing-bucket-name>"))

Note: You can configure and customize additional parameters. For more information, see Customizing bootstrapping.