Introduction to AWS CDK
Relevant source files
The following files were used as context for generating this wiki page:The AWS Cloud Development Kit (AWS CDK) is an open-source software development framework used to define cloud infrastructure in code and provision it through AWS CloudFormation. It provides a high-level, object-oriented abstraction for defining AWS resources imperatively using modern programming languages. This allows developers to encapsulate AWS best practices into reusable infrastructure components and share them without extensive boilerplate logic.
The CDK framework is used to define reusable cloud components called constructs, which are then composed into stacks and apps. The AWS CDK Command Line Interface (CLI) is used to interact with these apps to synthesize CloudFormation templates, deploy stacks to AWS accounts, and compare changes against deployed stacks. The ecosystem also includes the AWS Construct Library, which provides modules for each AWS service with rich APIs to simplify integration.
Sources: README.md:8-15, README.md:26-34
Core Concepts
The AWS CDK is built around three main concepts: Constructs, Stacks, and Apps. These components form a hierarchy that represents the structure of your cloud application.
Sources: README.md:26-29, design/construct-tree.md:14-19
Constructs
Constructs are the fundamental building blocks of AWS CDK applications. A construct can represent a single AWS resource, like an S3 bucket (an L1 construct), or it can be a higher-level component (an L2 or L3 construct) that encapsulates multiple AWS resources with built-in logic and best practices. For example, a construct could represent a worker queue with its associated compute capacity or an entire multi-region application.
Developers compose constructs together to define their infrastructure. The AWS Construct Library provides a wide range of pre-built constructs for various AWS services.
Sources: README.md:27, design/construct-tree.md:14-19, packages/@aws-cdk/example-construct-library/README.md:18-22
Stacks
A Stack is the smallest physical unit of deployment in the CDK and maps directly to an AWS CloudFormation Stack. You define a stack by creating a class that inherits from cdk.Stack and instantiating constructs within its constructor. An application can be composed of one or more stacks, which is useful for organizing resources, separating stateful from stateless components, or managing resource limits.
When resources are referenced across different stacks within the same account and region, the CDK automatically synthesizes CloudFormation Exports and Fn::ImportValue calls to manage the dependencies.
Sources: packages/@aws-cdk/core/README.md:12-26, packages/@aws-cdk/core/README.md:73-82
Apps
A CDK App is the root of the construct tree. It is a container for one or more stacks that define your cloud infrastructure. The app is the entry point for the CDK CLI to synthesize the CloudFormation templates for all the stacks it contains.
Sources: README.md:28, design/construct-tree.md:14-15
The following diagram illustrates the hierarchical relationship between an App, Stacks, and Constructs.
The Construct Tree
The CDK represents every app as a construct tree. To improve debugging and visibility, the CDK can publish this tree as an artifact named tree.json within the cloud assembly (cdk.out directory) during synthesis. This file provides a structured, machine-readable representation of the entire construct hierarchy, from the root app down to individual resources and their properties.
The goal is to expose this tree to enrich the developer experience, making it easier to understand what resources a high-level construct contains, what properties they were initialized with, and how constructs are related, without needing to inspect the raw CloudFormation template.
Sources: design/construct-tree.md:5-8, design/construct-tree.md:53-55, design/construct-tree.md:83-86
tree.json Data Model
The tree.json file has a root object containing version and tree keys. The tree object represents the root of the construct hierarchy and contains nested children objects that define the full tree structure.
| Property | Type | Description |
|---|---|---|
id | string | The construct's identifier within its scope. |
path | string | The full, absolute path of the construct within the tree. |
children | object | An object containing direct children of this construct, keyed by their ID. |
attributes | object | A key-value map of arbitrary metadata associated with the construct. |
Sources: design/construct-tree.md:90-100, design/construct-tree.md:115-139
Below is a sample structure of the tree.json file.
{
"version": "tree-0.1",
"tree": {
"id": "App",
"path": "",
"children": {
"mystack": {
"path": "mystack",
"children": {
"mytopic": {
"path": "mystack/mytopic",
"attributes": {
"aws:cdk:cloudformation:type": "AWS::SNS::Topic",
"aws:cdk:cloudformation:properties": {
"DisplayName": "MyTopic"
}
}
}
}
}
}
}
}
Sources: design/construct-tree.md:115-139
Development Workflow and CLI
The primary tool for interacting with a CDK app is the aws-cdk CLI. The typical workflow involves initializing a project, defining infrastructure in code, and then using the CLI to synthesize, diff, and deploy.
Sources: README.md:30-32, packages/aws-cdk/lib/init-templates/v2/app/javascript/README.md:7-11
This diagram shows the basic development lifecycle using the CDK CLI.
Key CLI Commands
| Command | Description |
|---|---|
cdk init | Initializes a new CDK project in a specified language. |
cdk synth | Synthesizes a CloudFormation template from the CDK app. |
cdk deploy | Deploys the specified stack(s) to your AWS account. |
cdk diff | Compares the current state of the app with the deployed stack. |
cdk ls | Lists all stacks in the app. |
Sources: README.md:62-75, packages/aws-cdk/lib/init-templates/v2/app/javascript/README.md:9-11, packages/aws-cdk/lib/init-templates/v2/app/java/README.md:10-14
Supported Languages
The AWS CDK is available in several programming languages, allowing developers to use familiar tools and ecosystems.
| Language | Requirements | Status |
|---|---|---|
| JavaScript/TypeScript | Node.js ≥ 10.13.0 (Active LTS recommended) | Stable |
| Python | Python ≥ 3.6 | Stable |
| Java | Java ≥ 8 and Maven ≥ 3.5.4 | Stable |
| .NET | .NET Core ≥ 3.1 | Stable |
| Go | Go ≥ 1.16.4 | Developer Preview |
Sources: README.md:17-24, packages/aws-cdk/lib/init-templates/v2/app/go/README.md:5-7
Declarative CDK (deCDK)
deCDK is a tool that allows for defining AWS CDK applications declaratively using JSON or YAML, similar to CloudFormation templates. It can interpret both standard CloudFormation resources (e.g., AWS::S3::Bucket) and AWS CDK constructs (e.g., @aws-cdk/aws-s3.Bucket).
This enables a CloudFormation-like authoring experience while still leveraging the power and high-level abstractions of the AWS Construct Library. deCDK processes the template, identifies CDK construct types, and instantiates them with the specified properties.
Sources: packages/decdk/README.md:3-6, packages/decdk/README.md:18-22
Here is an example of defining an SQS queue using deCDK in a JSON file:
{
"$schema": "./cdk.schema.json",
"Resources": {
"MyQueue": {
"Type": "@aws-cdk/aws-sqs.Queue",
"Properties": {
"fifo": true
}
}
}
}
This declarative definition can be synthesized into a CloudFormation template using the CDK CLI: cdk -a "decdk hello.json" synth.
Sources: packages/decdk/README.md:12-26
Summary
The AWS CDK provides a powerful, code-first approach to defining and provisioning cloud infrastructure. By using familiar programming languages, developers can create reusable, high-level abstractions called constructs, which are organized into stacks and deployed as a cohesive application. Key features like the construct tree artifact (tree.json) and the deCDK declarative syntax enhance visibility and offer flexible authoring experiences. The AWS CDK CLI serves as the central tool for managing the entire lifecycle of a CDK application, from initialization to deployment and monitoring.
Sources: README.md:8-15, design/construct-tree.md:5-8, packages/decdk/README.md:3-6