Introduction to AWS CDK

5 min read, last updated on 2020-12-22

AWS CloudFormation is with us since ~2011. Most of us work with it daily, some of us hate it with passion. It’s not the worst service available in the AWS portfolio. However, it has plenty of areas for improvement.

In August 2018, AWS announced one of the steps that should improve the current state of affairs. A new kid, called Cloud Development Kit, arrived on the block as a beta version (called a Developer Preview officially). Authors in the original blog post announcement initially defined it as:

The AWS CDK is a software development framework to define cloud infrastructure as code and provision it through CloudFormation.

aws.amazon.com/blogs/developer/aws-cdk-developer-preview

One year later, after a ton of feedback from the community, they’ve released an official version, with support for TypeScript and Python.

In the following blog post series, I want to address what it is, why I’m interested in it, how it can help you, and give you a few practical examples after playing with it in commercial applications.

What is it?

For software engineers, the most straightforward analogy is the authors’ one in the first blog post, that AWS CDK provides a way to describe your infrastructure in a higher-order, imperative language, and then use CloudFormation as the assembly language.

The following diagram describes it similarly, providing additional context and terms (including the supported programming languages in the bottom right corner):

Our CDK application is built from stacks (and directly transfers to the CloudFormation). But in opposition to the original tool, we receive an additional abstraction called a construct - that allows us to describe the set of the specific resources that serve a particular purpose.

After the modeling phase, our abstraction in the application is compiled to the CloudFormation templates and deployed on AWS like we used to do it.

Sounds legit? Well, this analogy - even that is correct, and sometimes referred to in the documentation (e.g., in case of Escape Hatches, which allows for injecting low-level CloudFormation concepts to a generated template, are very similar in nature to the inline assembly) - is very unfortunate and problematic. Ben Kehoe elaborates on the whole issue in his talk and article.

Long story short: it suggests that the whole compilation process, even that, can be deterministic, but the number of variables that affect it is overwhelming, and it causes fluctuations. Additionally, it introduces an additional layer that needs translation back-and-forth (e.g., in the case of debugging) and does not reflect the structure of the resource graph at all.

At the same time, we desperately need alternatives, as I wrote here, so we need to iterate and try. And as usual, behind such desperation, there is a story.

We need to talk about custom tools…

Around August 2018, together with my friends at Pattern Match, we were preparing a workshop for 25 people when we had to make identical environments for each participant - a simple one: IAM user, S3 bucket, proper IAM permissions, and some stuff for Amazon SageMaker.

How will you roll that with the CloudFormation? You will hit hard CTRL-C + CTRL-V combination or use some templating, scripting, etc. It’s less than ideal if you are iterating with the environment structure, but we can work around that.

This was the first time when I worked with CDK (here is the evidence: commit), and this helped me tremendously.

When you are doing workshops, such situations are frequently happening. For one workshop, we have needed a non-trivial VPC setup with ECS clusters for all 25 participants. But we have forgotten about it, and we jumped into writing our own Ansible and Python-based tool that handles everything. We have spent a whole month building it, and then I reminded myself about CDK - and wrote the same thing in one afternoon. 🤦‍♂️ I think I do not have to tell you how more pleasant this experience was in the end.

My journey with AWS CDK

My point above is that this tool fitted perfectly. Especially in a case like above or similar, when I needed to handle additional complexities - either coming from repetition or reusability, because, without extra tools, we lack such capabilities in the plain CloudFormation (or even Terraform).

If you have not worked with CDK yet, here you can taste the experience (in the TypeScript flavor):

const ROLE_ARN = 'arn:aws:iam::aws:policy/AmazonSageMakerFullAccess';

const amazonSageMakerRole = new Role(this, 'AmazonSageMakerRole', {
  assumedBy: new ServicePrincipal(AMAZON_SAGEMAKER_PRINCIPAL),
  roleName: 'amazon-sagemaker-in-practice-workshop-role'
});

amazonSageMakerRole.attachManagedPolicy(ROLE_ARN);

const participantsGroup =
  new Group(this, 'AmazonSageMakerInPracticeParticipants');
const policy =
  new Policy(this, 'AmazonSageMakerInPracticeParticipantsPolicy');

const permissions = [
  "sagemaker:*", "ecr:*", "cloudwatch:*", "logs:*",
  "s3:GetBucketLocation", "s3:ListAllMyBuckets",
  "iam:ListRoles", "iam:GetRole"
];

const defaultStatement =
  (new PolicyStatement())
    .allow()
    .addAllResources()
    .addActions(...permissions);

const condition = { 'iam:PassedToService': AMAZON_SM_PRINCIPAL };
const passRole =
  (new PolicyStatement())
    .allow()
    .addAllResources()
    .addAction("iam:PassRole")
    .addCondition("StringEquals", condition);

policy.addStatement(defaultStatement);
policy.addStatement(passRole);

participantsGroup.attachInlinePolicy(policy);

const dataSource = Bucket.import(this, 'DataSourceBucket', {
  bucketArn: 'arn:aws:s3:::amazon-sagemaker-in-practice-workshop'
});

This blog post is not the best place to introduce all elements and talk about technicalities - we will do it, but not yet. First, I would like to address the skepticism that I have mentioned above.

This tool has its merits. Even if someone claims that it is easy to misuse (guess what: you can misuse CloudFormation or Terraform too 😉) when used correctly, CDK saved my time and allowed me for much smoother maintenance - it can help you also. However, there are no silver bullets - and we will address situations when this tool may and will cause problems because it was not an easy-going journey all the way.

What’s next?

By this blog post, I want to start a series of blog posts about AWS CDK.

Step by step, we build a complete CDK application that will handle the preparation of the workshop environments for the participants. We will address the pros, cons, and discovered issues. As I stated above, there are pitfalls, and if you are looking into CDK as a viable solution to your problems, you will appreciate the helping hand. Finally, a change in the mindset is also necessary to use this tool correctly, and we will address that as well.

So, are you ready? The next part will arrive in the following week, where we will address the structure and basic concepts. 💪

In the meantime, tell me: What is your story? Why are you interested in AWS CDK? I will be delighted if you will share your motivation with me in the comments.