Getting started with AWS CDK v2

With the AWS CDK you can easily build your infrastructure on AWS as Infrastructure-as-Code. Instead of writing long CloudFormation templates in YML you can write short, to the point code to create an S3 bucket, deploy a Lambda or create a CloudFront distribution. We will walk you through everything you need to know to get started quickly with the AWS CDK.

CDK stands for Cloud Development Kit. It is an Infrastructure-as-Code (IaC) framework in which you can define your AWS resources in TypeScript, JavaScript, Go, C#, Python or Java. The code you write is transformed by the CDK CLI into a CloudFormation template, that will then automatically be deployed to AWS. In this article we will get started with the CDK in TypeScript. You can install the AWS CDK for TypeScript or JavaScript simply via npm or yarn. The package name is aws-cdk-lib: npm install -g aws-cdk-lib.

And to create a new CDK app, we need to run the following commands:

mkdir hello-cdk
cd hello-cdk
cdk init app --language typescript

Your new CDK project is now created. Each CDK project consists of a bin and a lib folder. In the bin folder you will define your app (you can see each CDK project as a single app) and you will add your stacks here to your app. In the lib folder you will build your stacks with the resources you want to create.

Let's look at a simple code sample on how to create an S3 bucket with the CDK:

import { App, Stack, StackProps } from'aws-cdk-lib';
import * as s3 from'aws-cdk-lib/aws-s3'; 

class S3CdkStack extends Stack {  

constructor(scope: App, id: string, props?: StackProps) {   
   super(scope, id, props);    
   const s3Bucket = new s3.Bucket(this, 'MyFirstBucket', {      
      autoDeleteObjects: true    
   });  
  }
}

A stack is a collection of AWS resources, this is the same concept as in CloudFormation. Within a stack you create resources, in our case an S3 bucket. In each stack you can define as many resources as you want, but we recommend to split your resources among stacks based on what belongs together. It can happen that you need to breakdown a stack and it wouldn't be great if you're unnecessary breaking down resources that could have stayed up.

With the CLI command cdk synth you can convert your CDK project into a CloudFormation template and with cdk deploy you can actually deploy your CDK project to AWS.

You can find an overview of all resources, together with code samples and their options, on the documentation portal of the CDK. The documentation is generally of high quality and complete, for at least the stable modules. Do pay attention whether your looking at the V1 or V2 of the CDK docs. This is indicated on the top left on the page.

For all concepts of the CDK, check out the documentation on AWS. Here you can also find for example how to use parameters, as well as other CDK options and features.

Constructs

The most important concept in the CDK are the constructs. In most cases this will represent an AWS resource. AWS describes it as a "cloud component". You can use the CDK to create constructs on three different levels. The lowest level is level 1 (L1), the so called CFN resources (Cfn). With level 1 you are pretty much just manipulating CloudFormation templates. You can recognize these constructs from the fact that their name starts with Cfn. For example a CfnBucket is an S3 bucket. Level 1 being the lowest level means that when you are creating objects here, you will have to configure a lot of options, the CDK does not provide sane defaults.

Most of the code you will write in the AWS CDK will be on level 2 (L2). At this level a lot of boilerplate will be out of the way and you won't have to write as much code to make resources work together. Furthermore, the CDK offers you good, sane defaults on level 2 following AWS' best practices. This means you won't have to know every single, small detail from the AWS resources you are working with. When you want to create an S3 bucket on level 2 for example, you can use the s3.Bucket class, as is done in the code sample above.

The highest level of constructs is level 3 (L3). On this level we are actually not talking about resources anymore, but more about patterns. For example, with L3 constructs you can deploy a Lambda behind an API REST Gateway all at once, or create a Fargate cluster with an Application Load Balancer in front. L3 of the CDK is still under active development and not quite complete.

Escape hatch

It can happen that the CDK is behind on what you can do in CloudFormation or in the AWS Console, or it can be that the CDK doesn't expose a certain option or even has a bug in some deployed resources. With an Escape hatch you can easily convert a level 2 to a level 1 resource, so that you can have much better control over the generated CloudFormation template. You can even directly override CloudFormation template options. For example:

// Convert our Level 2 S3 bucket to a Level 1 construct
const cfnBucket = bucket.node.defaultChildas s3.CfnBucket; 

// We can now directly override CloudFormation template properties
cfnBucket.addOverride('Properties.VersioningConfiguration.Status', 'NewStatus');

The bucket is an AWS resource on level 2. Via the node.defaultChild properties we convert this resource to a level 1 resource. Then we can call addOverride to directly manipulate the properties of the generated CloudFormation template and modify them to our wishes.

Bootstrapping

Before you can get started with the CDK, it is required to bootstrap the AWS account in which you want to deploy your CDK resources. The CDK itself needs some resources to be able to deploy your resources, such as IAM roles and policies. Before your first-time CDK deploy, make sure to run the CLI command cdk bootstrap once to prepare your AWS account. After that you are ready to get started with the AWS CDK.

CDK v1 vs v2

At the moment of writing there are two versions of the AWS CDK in development. When you are getting started now, we recommend to use CDK v2. In this version the CDK is merged into a single package, which makes developing with the CDK much more pleasant. V1 will get new features until 1 June 2022. After that it will only receive bug and security fixes until 1 June 2023. Upgrading to V2 is not very difficult: Just fix the imports and keep in mind that the Constructs are moved to their own package.

Conclusion

We've shown you how to get started with the AWS CDK v2, how to install its CLI, create your first CDK project and we've also explained some important concepts of the CDK, such as Stacks, Constructs and Escape hatches. The AWS CDK is an interesting alternative for CloudFormation and also for Terraform, with the biggest difference that with AWS CDK you can use an actual programming language instead of a purely declarative language.