Nowadays there is no doubt that 'Infrastructure as real code' is a way of cloud resources provisioning. CDK is an incredible way of doing this in the AWS ecosystem. This article will talk about the situation when the Cloudformation template is in place and you want to make a new setup with the CDK using Typescript. The opinions are my own.

The Case

Let's imagine you have a new project in a team where CFN was used for a long time. There is a lot of boilerplate already and people are repeating the same things over and over again. There is also some custom CI/CD setup in place. With this background - you are set to start a new project with CDK.

Excited? Me too. But there are some complications because CFN is a YAML/JSON-based templating mechanism. CDK in short is an abstraction on top of CFN which is using a programming language for provisioning infrastructure in a structured way. Here are my tips on how to start switching from Cloudformation/SAM after using the tool for almost a year now.

Start with a small project

Consider a project without many elements. Try to avoid projects where you need to set up VPC by yourself. Also, it will be better to avoid projects with container orchestrations using ECS or Kubernetes. The ideal first project will be the one having S3, Lambda, CloudFront, API Gateway, DynamoDB, and IAM permissions. Example projects can be:

• Scheduled event placing data into S3/DynamoDB
• Event from Github/Bitbucket 
• The API call to do some simple job like routing request to another party.

Another important point is to use CDK version 2. x. In most of the guides, it will be suggested to utilize the first one. It is outdated and has many dependencies issues. The developing experience will be much more delightful. For installing it -  run:

npm install cdk@next

Study CDK basic concepts

There are multiple important terms when it comes to CDK. The first one is 'App'. It is the root element of the structure. There you can describe the stacks and their creation.
The most interesting concept is a construct. From AWS docs:

Constructs are the basic building blocks of AWS CDK apps. A construct represents a "cloud component" and encapsulates everything AWS CloudFormation needs to create the component.

It is basically a module of the resources packed together as a logical unit. The constructs are having different levels of abstraction. There are ones that are the closest to the CloudFormation. Typically, they have poor typing. 

There are 3 levels of abstraction: 

• CFN resources  - they are mapped to the underlined CFN resources.
• Level 2  - they give the abstractions and typing. The constructs can be also coming from the library here. Many constructs will allow having types and making fewer mistakes.
• Level 3 - these are the whole patterns. They can be done by AWS or other developers. The ones coming from AWS advocates and heroes could be found here.

From my point of view, the power of CDK lies in the third level. It gives the possibility to automate the creation of very common patterns in your team. For example, it can be a custom domain or pipeline setup. 

Planning the stacks

Another important point is to have an idea of how many stacks will you need to succeed in the provisioning of the infrastructure. One stack is not helpful in many cases. It means that stacks should be architecture in a way that each of them solves one problem. It can be an issue to determine whether to use the construct or the stack.

According to AWS documentation: "A stack is a collection of AWS resources that you can manage as a single unit." When you have an API with Lambdas - this can be a stack. However, if you have databases and other types of storage - this can be another stack. 

One more thing which comes quite often, in the end, is how the stacks will talk with each other. There are multiple ways of doing this. You can either pass general props or the whole stack as an input to the next one, for example.

Always check original documentation

The CDK is just awesome, from my point of view. But it is not saving us from reading and understanding Cloudformation. De-facto CDK is synthesizing the CloudFormation template in JSON format. Thus, it is obligatory to see what it is doing for us.

There are great tricks hidden in the official documentation when you are actually reading it. Most of the time, I am googling something like 'AWS::DynamoDB::Table'. The response will give the needed documentation page for the infrastructure element.

Failures are essential

My journey with CDK started with the failure of deployment when I tried to have an S3 bucket created. It took 15 minutes to deploy it with no success. It is ok to fail with CDK in the beginning. Do not try to hurry and migrate the whole application at once. 

During one of the projects, I had a CI/CD setup done with SAM and CloudFormation. Migration of it completely to CDK would take time from the actual feature development. So the solution was to migrate the implementation code infrastructure to CDK and rest the pipeline with the same setup. I learned a lot during this transition for the next project where I took the whole infrastructure into CDK.

All in all, CDK is worth to be tried on the next PoC or internal tool because it gives the real coding experience while doing infrastructure. This is especially important when you are going to use a DevOps mindset for the new features where engineers are responsible for not only the implementation. Usage of the same language for the IaC tool eliminates the context switching between TypeScript and YAML. Thus, it will increase the productivity of the whole team.