Production-Ready CDK – Bootstrapping

-

In the previous posts, we set up the project, wrote our first construct, and implemented a CI/CD Pipeline using CDK Pipelines. If you haven’t already done so, Bootstrapping AWS CDK is one of the first things we need to do in our AWS Accounts.


What is AWS CDK Bootstrapping?

To use CDK and deploy our CDK app to our AWS environment(an AWS account plus a region), we need to provision the resources required for deployment. These resources are mainly an S3 bucket to store files and IAM Roles to have permissions related to deployment. We call the process of setting these resources bootstrapping.

According to the documentation, you need bootstrapping if you use Assets and if your generated app template file size is more than 50 kilobytes. However, you will almost always cover these two cases, so you can start doing it without thinking more.

Why is it worth discussing?

You might be wondering why even I write about bootstrapping. Because in many tutorials, it says you need to use the cdk bootstrap command, and you are good to go, which is right most of the time.

But when you are using a company AWS account, the command will probably fail because of the permissions boundary. In that case, you need to consider Custom Bootstrapping, which might take some time if you don’t know how to do it. The following information will help you do it in a few minutes.
If the cdk bootstrap command works on the first try, you most likely don’t have the permissions boundary setup(you should seriously consider implementing it).


Side note: CDK v2 uses the modern bootstrapping template by default, unlike CDK v1. In CDK v1, the default template is the legacy one, and the modern one is optional as you need to use the context flag:
“@aws-cdk/core:newStyleStackSynthesis”: “true”.
If you have the legacy template in your environment, I recommend updating it and this post might be relevant to you. You can check the differences here.


Alright, how do we proceed?

Here is the documentation for the bootstrapping. Again, using CDK v2, I would try cdk bootstrap with my local credentials and profile (example: including --profile dev), and it would fail(hopefully)!

Having purposeful guardrails in the cloud is essential. It might first seem they are restricting us, developers. But, if we use the guardrails well, they will save us from future headaches.

Now, let’s say we have already tried the command and it didn’t work, because a role creation failed due to the permissions boundary. We need to think of Custom Bootstrapping, which is straightforward.

As the next step, you can download the bootstrapping template using the command cdk bootstrap --show-template > bootstrap-template.yaml. Then use the command cdk bootstrap --template bootstrap-template.yaml to deploy it. But it will fail again because we haven’t changed anything related to the permissions boundary.

Permissions Boundary Changes

We need to provide a permissions boundary to every role in the bootstrapping template to resolve the problem. To achieve that quickly, we can get the Amazon Resource Name(ARN) of the boundary as an input parameter and then use it.

In the example below, I omitted and dotted some parts for brevity. We can ignore those lines.

You can see the boundary parameter with the name PermissionsBoundaryArn. After defining the input parameter, we use it in the IAM Role declaration on line 54.


Description: This stack includes resources needed to deploy AWS CDK apps into this
  environment
Parameters:
  .
  .
  .
  .
  .
  PublicAccessBlockConfiguration:
    Description: Whether or not to enable S3 Staging Bucket Public Access Block Configuration
    Default: 'true'
    Type: 'String'
    AllowedValues: ['true', 'false']
  PermissionsBoundaryArn:
    Description: ARN of the Permissions Boundary
    Type: 'String'
Conditions:
  HasTrustedAccounts:
    Fn::Not:
      - Fn::Equals:
          - ''
          - Fn::Join:
              - ''
              - Ref: TrustedAccounts
  .
  .
  .
  .
Resources:
  .
  .
  .
  .
  FilePublishingRole:
    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
      RoleName:
        Fn::Sub: cdk-${Qualifier}-file-publishing-role-${AWS::AccountId}-${AWS::Region}
      PermissionsBoundary: !Ref PermissionsBoundaryArn
      Tags:
        - Key: aws-cdk:bootstrap-role
          Value: file-publishing

Here is the complete bootstrapping template. If you want to deploy from the CloudFormation Console, you don’t need to change anything(the template version is v12 by the time I wrote this). You only need to provide the ARN as input.

To deploy from your CLI, you need to provide the ARN value for PermissionsBoundaryArn in the template. Then you can use the command cdk bootstrap --template bootstrap-template.yaml.

More Customization

Depending on the industry & size of your company, your organization might have specific Compliance & Security requirements, such as adding Tags to the resources or having encryption for S3 Buckets. Depending on those requirements, you can keep modifying the template and deploy it in the same way.

For the other CLI command options, you can recheck the documentation. I recommend using flags:

  • ‒ ‒ tags: it is a best practice to tag all resources you can.
  • ‒ ‒ termination-protection: and have it enabled. Because you hardly need to delete the bootstrapping stack, you better have it.
  • ‒ ‒ trust: in case you need to deploy from your dev environment to higher environments.

In this part of the series, we focused on a shorter topic, bootstrapping, and especially how to do this in a custom way.

In the next chapter, we will continue with Aspects to overcome the Permissions Boundary. This time, it is for our CDK Pipeline roles and all the other roles/resources we will provision.

See you in the next ones. Ciao!