The AWS Cloud Development Kit and You

I remember when I first started with AWS, many years ago. This was before Lambdas and much of their cloud offerings when we basically had S3 and EC2 instances. I manually configured all the things in the AWS console. I learned later, that this was bad, and started to describe my infrastructure with Cloud Formation Templates.

Cloud Formation Templates were a game-changer. I could now set up multiple environments exactly the same. This allowed me to find errors in my infrastructure configuration before we deployed to production, and became indispensable once I moved away from apps hosted on EC2 instances, and towards building apps with Lambdas and DynamoDB.

Managing the templates was a tedious process. My first templates were a couple of EC2 instances, perhaps a Cloud Front Distribution, and some Route53 bits. Now I was trying to handle dozens of Lambdas, and their associated IAM Roles, DynamoDB tables, SNS Topics, etc. A lot of the time, most of the configuration for any given resource was very similar, and after copying and pasting a few times, the cognitive dissonance was too much to bear, and I needed a programmatic solution.

I would write code that generated Cloud Formation Templates in JSON. Sometimes these took the form of a parser that would parse an existing template, add to it, and recompile it. Other times I found that building an object graph was a better approach. The problem was, with each new resource type I would need to poor over the documentation and design a class for it. This took the time I never seemed to have, and building a reusable library was a pipe dream.

Then one day, not too long ago, I discovered the AWS Cloud Development Kit. This was the library I always wanted but never had time to write.

Most of the time, creating AWS resources also includes creating IAM roles and policies to access those resources. For me, this tends to be the most tedious part of authoring Cloud Formation templates. The CDK isn't just a mapping of class properties to YAML properties, they've also created an abstraction on top of that mapping, that applies sane default values, and automatically generates IAM roles and policies so your resources can interact.

This doesn't alleviate your responsibility of writing IAM policies for Lambdas or Containers, but much of the work of connecting Code Pipelines to S3 buckets, etc, is handled for you. You don't even need to create an instance of an IAM role class.

On my most recent project, I had the need to create 5 different micro-sites that only varied in a few ways, mainly domain and S3 bucket names. With plain Cloud Formation Templates, I would need to do a lot of copying/pasting. Moreover, if I wanted to make a unilateral change to how all sites work, perhaps a Cloud Front Distribution behavior, I would need to do it 5 times. This is where the programable nature of CDK really shines. I was able to create a subclass of Stack, that allowed me to only change what would be different for each site. This is basic OOP inheritance, but when using it to build Cloud Formation Templates, it becomes extremely powerful.

export type SiteStackProps = {
    stackName: string,
    subDomain: string,
    s3BucketName: string
}

export abstract class SiteStack extends Stack {
    bucket: Bucket,
    distribution: CloudFrontWebDistribution,
    constructor(scope: App, props: SiteStackProps) {
        // The child class determines the stack name,
        // since these are unique within an account.
        super(scope, props.stackName);
        // I create a bucket, but use the passed in bucket name.
        this.bucket = new Bucket(this, "Bucket", {...})
        // I create a cloud front distribution, but use the passed in domain name.
        this.distribution = new CloudFrontWebDistribution(this, "Distribution", {...})
        // More was created in the actual implementation, but this should give you the gist.
        ...
    }
}

export class Site1Stack extends SiteStack {
     constructor(scope: App) {
         super(scope, {
             stackName: "Site1Stack",
             subDomain: "site-1",
             s3BucketName: "site-1-bucket"
         });
     }
}

export class Site2Stack extends SiteStack {
     constructor(scope: App) {
         super(scope, {
             stackName: "Site2Stack",
             subDomain: "site-2",
             s3BucketName: "site-2-bucket"
         });

         // For this stack, I may need to give 
         // bucket read access to some lambda.
         // I can have access to all resources exposed
         // as properties on the parent class.
         this.bucket.grantRead(...)
     }
}

I hope this little post has served to highlight some of the features and benefits of using the CDK. I was able to convert a handful of Cloud Formation Templates to a full CDK implementation in a sprint, including building a Code Pipeline that would update itself and deploy all the things. I think this should be in the arsenal of anyone who builds AWS cloud infrastructure.