What is the AWS CDK? (A beginners guide)

Provisioning infrastructure in the Cloud using code has been a best practice standard now for a couple of years now.

Businesses and organizations now see the benefit of provisioning AWS resources compared to the manual approach in the AWS console.

From that point on there were two popular tools available that allowed you to define Cloud resources using a declarative approach such as AWS CloudFormation and Terraform.

However, the configuration of a declarative approach can be rather extensive and results in very large templates written in JSON or YAML that need to be maintained in order to keep your infrastructure as code up-to-date.

That’s where AWS CDK comes in to improve the workflow of developers and help them provision Cloud infrastructure using an imperative approach.

In this guide, you’ll learn what AWS CDK is, how you can use it to create your own infrastructure as code, and apply the best practices during development.

What is the AWS Cloud Development Kit (CDK)?

AWS CDK stands for Cloud Development Kit and is a framework developed by AWS that allows you to define and provision Cloud infrastructure in code and deploy it through AWS CloudFormation.

AWS publicly released AWS CDK (v.0.8.0) in beta back in 2018 as an alternative approach to developing AWS resources programmatically using TypeScript.

They made this project open-source so that it enabled the community to contribute to the code and directly pass on feedback to the official maintainers.

In December 2021 during Re:Invent Werner Vogels announced that AWS CDKv2 became generally available (GA) and currently supports the following programming languages:

• TypeScript
• JavaScript
• Python
• Java
• C#
• Go (Developer preview)

When AWS CDK became GA this meant that there wouldn’t be any breaking changes from that point on and it could safely be used for production workloads.

AWS CDK Concept

To simplify the concept of AWS CDK is that it consists of 3 major building blocks that allow you to customize the provisioning of your infrastructure:

• App – That is the root of your construct tree and consolidates all stacks and constructs in one application that can then be used to deploy on AWS Cloud.
• Stack – is similar to a CloudFormation stack. It’s a single unit (template) that holds the AWS resources in the form of constructs and can be used for deployment.
• Construct – is the basic building block that can contain a single AWS resource or multiple AWS resources combined. You’re free to build and combine AWS resources in your own constructs.

When an AWS CDK application is synthesized, the result is a cloud assembly, which contains the generated AWS CloudFormation templates for your stacks including the assets of your application.

This package can then be deployed by the AWS CDK CLI to your preferred AWS account and region.

AWS CDK construct concept

As you might’ve noticed in the previous diagram, you’ll see multiple constructs displayed within the stacks, each containing different AWS resources.

These constructs are fundamental to the biggest benefit that AWS CDK provides to the developer.

There are 3 ways to build constructs in AWS CDK, each with its own unique features:

• L1 Constructs are basically the AWS CDK version of AWS CloudFormation resource types. The properties are mapped exactly as its AWS CloudFormation counterpart. There’s no real benefit to using L1 constructs if you can build AWS resources using L2 and L3 constructs. There’s one exception to this rule… if an L2 or L3 construct doesn’t let you customize a certain property via its API, then you can fix that using an escape hatch.
• L2 Constructs are AWS resources developed by the AWS CDK team that encapsulate L1 constructs using pre-configured security measures in place including sensible defaults. The primary benefit of L2 constructs is that you’re able to create secure AWS resources with a few lines of code.
• L3 Constructs (also called patterns) are a group of L2 constructs combined to deliver a full solution. For example, you can group multiple resources together like an EC2 instance that is linked to an RDS and an Application Load Balancer (ALB). You can initialize this group of resources using a few lines of code, which allows you to reuse these patterns in multiple projects or stacks.

What are some of the features of AWS CDK?

The AWS CDK is a major step for developers to control and automate AWS infrastructure. Because it allowed you to develop AWS resources faster using your own development tools speed at which I can develop and iterate using CDK is significantly faster than using AWS CloudFormation alone.

The ability to share and distribute AWS CloudFormation patterns using my company’s native software tools increases the consistency and standardization across all Intuit accounts. Even more importantly, AWS has made this project open source.

This finally enables customers to directly contribute to and enhance the future of AWS CloudFormation.

Here are the best AWS Cloud Development Kit features that improve your development cycle:

• Supports multiple programming languages
• Use your own development tools to enhance the code quality of your AWS CDK project.
• You don’t have to reinvent the wheel as you create new AWS resources for your project because you can make use of the construct hub where you can find and share L2 and L3 CDK constructs
• Store your Infrastructure, application, config, and deployment in a single repo under one CDK app.
• Ability to contribute and pass feedback to the developer team since AWS CDK is open source.
• Ability to generate CloudFormation templates containing 1000s of lines with a few lines of Typescript code
• Ability to create recursive functions that allow you to iteratively generate multiple AWS resources e.g. generate 5 AWS Lambda functions without writing the same code 5 times.

AWS CDK vs CloudFormation

When AWS CDK came out I saw a huge shift happening and a community gets formed where constructs were shared and people discuss new ideas and share their experiences.

Back in the days when I used CloudFormation, I haven’t seen such a community that focused on sharing CloudFormation templates for instance, other than code shared on GitHub.

From my own experience as a DevOps engineer having used both services extensively over the years, I would say that I prefer AWS CDK over AWS CloudFormation for the following reasons:

• Speed up the development time of new resources by using L2/L3 constructs that contain sensible defaults and best practice security policies
• Ability to use a programming language of choice to define my infrastructure instead of having to strictly declare resources using YAML or JSON
• Spending time mastering a programming language is more useful for your career than spending time writing YAML for CloudFormation. The skills you learn writing code day in and day out are more transferable to other technical job functions.

One of the AWS community members made a good point about what many would consider a unique selling point of AWS CDK:

“1500 lines of CloudFormation became 14 lines of CDK” It’s important to understand that the deployed application still has 1500 lines’ worth of operations and maintenance ownership, not 14

— Ben Kehoe (@ben11kehoe) December 2, 2021

In the end, AWS CDK is just a transpiler for AWS CloudFormation by using cdk synth to turn your TypeScript source definition into a JSON template that will be deployed using AWS CloudFormation.

Therefore it’s a best practice to validate the output by tools such as cfn-lint and checkov to prevent misconfiguration of your infrastructure as code.

Having an abstraction such as AWS CDK can be great but only if you understand the underlying concepts. If you don’t know how CloudFormation works, it might be detrimental to your development cycle as you spend more time debugging and not understanding why things might not work.

How do I get started with AWS CDK?

To get started with AWS CDK you first need to install the AWS CDK toolkit on your machine, you use the node package manager in your terminal to install the package globally:

➜ npm install -g aws-cdk

added 180 packages, and audited 181 packages in 7s
found 0 vulnerabilities
~ took 7s

AWS CDK best practices

I’ve summed up a list of best practices that’ll help improve the way you develop using AWS CDK. These best practices focus on how you manage your code, environments, pipelines, and constructs.

• Start with implementing a landing zone strategy to organize your AWS accounts and automate the security policies and guardrails so you can quickly onboard and configure new accounts and teams.
• Create multiple stages (AWS accounts) e.g. Development, Test, Staging, and Production to promote build changes from your AWS CDK Apps.
• Add (automated) integration tests in your pipelines to mitigate any breaking changes to your application.
• Use the cdk diff command to inspect the AWS resource changes before you deploy to production.
• Consider keeping stateful constructs (like databases & storage) in a separate stack from stateless constructs (API, ECS, Monitoring). You can then turn on termination protection on the stateful stack, and can freely destroy or create multiple copies of the stateless stack without risk of data loss.
• Stateful resources are more sensitive to construct renaming—renaming leads to resource replacement—so it makes sense not to nest them inside constructs that are likely to be moved around or renamed (unless the state can be rebuilt if lost, like a cache). This is another good reason to put stateful resources in their own stack.
• Use conditions in your programming language to decide how to instantiate a construct at synthesis time. Don’t use the AWS CloudFormation logic (Conditions, { Fn::If }, and Parameters).

For more best practices, check out the official documentation.

Developer tools for AWS CDK

To help you speed up your development time and improve your code quality you need assistance in the form of tools. Here’s a list of tools that’ll help improve your workflow using AWS CDK:

• AWS Toolkit for VS Code – allows you to gain tree view access on your CDK App within your code editor.
• Projen – is a project generator that initializes new CDK projects for you which are already pre-configured using best practices. Managing project configuration files can be difficult and hard to transfer to new projects. With Projen you synthesize project configuration files from a well-typed definition written in TypeScript.
• Eslint – is a linter that statically analyzes your code to find problems based on a set of pre-configured rules.
• Visual Studio IntelliCode – provides AI-assisted code completion when building constructs.
• Cdk-nag – checks your application for best practices based on a library of available rules. Implement this tool in your CI/CD pipeline to enforce high standards on the AWS resources that you build and deploy.

Dive deeper into AWS CDK

I’ve written more articles on AWS CDK where we dive deeper into building constructs, using best practices and much more. Here’s a condensed list of articles that help you gain a deeper understanding.

Troubleshooting common AWS CDK issues

One of the more common errors that might occur when you run AWS CDK commands in your terminal is the following:

--app is required either in command-line, in cdk.json or in ~/.cdk.json

This error occurs likely when you don’t run the AWS CDK commands in the root location of your AWS CDK project.

To fix the error, you should run commands such as cdk init, cdk synth or cdk deploy from within the directory where the main file is located from which the cdk app is instantiated, for ease of use its located in the same location where the cdk.json is stored (since the cdk.json is stored in main directory of the AWS CDK project).

Here you can find a list of fixes provided by AWS that solve other common AWS CDK issues.

Conclusion

In this article, you’ve learned what AWS CDK is and how it could improve your own development cycle.

You’ve read how it stacks up against AWS CloudFormation and what the benefits and features are when you’re ready to adopt AWS CDK.

The best practices and tools that are shared will keep your code and infrastructure quality high without sacrificing the speed of delivery.

If you liked this and want to dive deeper. Then have a look at these AWS CDK examples that I’ve documented so you can build and deploy AWS CDK Constructs yourself and learn in a practical manner.

AWS CDK FAQ