AWS CDK: infrastructure as code in TypeScript, Python, Java, .NET or Go

What the AWS CDK is for, and who should reach for it

The CDK is a framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation. The problem it addresses is the gap between a template file and the rest of a codebase. A raw CloudFormation template is declarative JSON or YAML with no functions, no loops, no type checking and no package manager. The CDK replaces that with an object-oriented library you consume from a real language, so infrastructure definitions can be split into reusable components, tested, and shared across teams.

The intended audience is developers who already work in one of the supported languages. The README lists JavaScript and TypeScript (Node.js >= 20.x), Python (>= 3.8), Java (>= 8 with Maven >= 3.5.4), .NET (>= 8.0) and Go (>= 1.16.4). If your team lives in one of those, the CDK asks you to learn AWS resource semantics rather than a new DSL. If your team is not a programming team, the CDK adds a toolchain and a compile step where a plain template would have been enough. That is a real cost, not a detail.

The README also states that third-party language versions are supported only until their vendor or community end-of-life date, and that this can change with prior notice. So the supported-language list is a moving target you have to track.

Constructs, stacks and apps: how the CDK turns code into CloudFormation

The data flow is the part worth understanding before you install anything. Developers write a CDK app in a supported language. Inside it they define constructs, which the README describes as reusable cloud components, and compose those constructs into stacks. A stack is the unit that maps onto a CloudFormation stack.

The AWS Construct Library provides a module per AWS service. Those modules are the API surface you actually program against, and the README says their purpose is to reduce the complexity and glue logic needed to integrate AWS services. The CDK CLI then synthesizes the app into AWS CloudFormation templates, deploys stacks to an AWS account, and can diff a deployed stack against your code to show the impact of a change.

That synthesis step is the key architectural fact. The CDK is not a deployment engine. It is a compiler that emits CloudFormation, and CloudFormation remains the thing that talks to AWS. Whatever CloudFormation cannot express, the CDK cannot deploy without an escape hatch to raw resources. This also means the CDK inherits CloudFormation's deployment model, including stack-level operations, rather than replacing it with a client-side apply loop.

Stability is tracked per module, not per project. The README says modules are designated Experimental while they are being built and may take breaking API changes in any release. Once a module is designated Stable it follows semantic versioning, and only major releases can carry breaking changes. Each module's designation appears on its Overview page in the AWS CDK API Reference. That per-module distinction matters more than the top-level version number when you plan an upgrade.

Installing the AWS CDK CLI and deploying a first stack

The README gives npm as the install path for the CLI, with a note that a signed .zip manual installation is documented separately in MANUAL_INSTALLATION.md. The npm install command is:

npm i -g aws-cdk

After that, `cdk` is on your path. You do not need a global install of the library itself; the library is a normal dependency of your project, and the README points to aws-cdk-lib on npm, PyPI, NuGet and Maven Central for the language-specific packages.

Scaffold a project with the CLI. The README uses a TypeScript sample:

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

That produces a stack file. The README's generated example wires an SQS queue to an SNS topic, and the shape is the point: a queue with a visibility timeout, a topic, and a subscription connecting them.

export class HelloCdkStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const queue = new sqs.Queue(this, 'HelloCdkQueue', {
      visibilityTimeout: cdk.Duration.seconds(300)
    });

    const topic = new sns.Topic(this, 'HelloCdkTopic');

    topic.addSubscription(new subs.SqsSubscription(queue));
  }
}

Deploy it with the CLI:

cdk deploy

The README lists three CLI commands worth knowing from the start: `cdk deploy` deploys the app into an AWS account, `cdk synth` synthesizes an AWS CloudFormation template for the app, and `cdk diff` compares the app with the deployed stack. Run `cdk synth` before your first deploy and read the template it prints. That output is the contract between your code and AWS, and it is the fastest way to see what the construct library actually generated on your behalf.

Where the AWS CDK is the wrong tool

The clearest limitation is stated in the README itself: experimental modules may have breaking API changes in any release. If you build on a module that is still Experimental, a routine library upgrade can change a constructor signature or a property name. Semantic versioning protection applies only after a module is designated Stable. Teams that pin versions and upgrade on a schedule absorb this; teams that upgrade casually will be surprised.

A second constraint is the CloudFormation dependency. The CDK synthesizes templates and CloudFormation deploys them, so the CDK cannot be more capable than the underlying service. Anyone expecting client-side apply semantics, or a way to manage resources CloudFormation does not model, is looking at the wrong layer.

The third case is multi-cloud or provider-neutral infrastructure. Nothing in the repository material suggests the CDK targets anything other than AWS. The construct library is organized per AWS service. If your requirement is one definition that can be applied to more than one cloud, the CDK is not the tool for that requirement, and evaluating it on that axis will only produce a negative result.

Finally, the CDK assumes a working language toolchain. Node.js >= 20.x for JavaScript and TypeScript, Python >= 3.8, Java >= 8 with Maven, .NET >= 8.0, Go >= 1.16.4. On a team with no build system and no dependency management, adding one to define a handful of resources is a poor trade.

AWS CDK compared with Terraform and with plain CloudFormation

Against plain CloudFormation, the difference is the authoring layer rather than the execution layer. Both end up at CloudFormation. The CDK adds a programming language, a construct library and a synthesis step on top, which buys you abstraction and reuse at the cost of an extra toolchain and an extra artifact to inspect. If your templates are small and static, the CDK is overhead. If they are large and repetitive, the construct library is where the value sits.

Against Terraform, the difference is in the approach rather than the syntax. Terraform defines infrastructure in HCL and applies it through its own provider-based engine, with state tracked by Terraform. The CDK defines infrastructure in a general-purpose language and hands the result to CloudFormation, so deployment state lives in CloudFormation stacks. That single distinction drives most of the practical consequences: which resources are reachable, how drift and rollback are handled, and what a plan or diff actually shows you. If you have already invested in Terraform state and modules, moving to the CDK is not a syntax migration, it is a change of deployment engine.

A related question people ask is how the CDK differs from the AWS SDK. The SDK calls AWS APIs from application code at runtime. The CDK describes resources that should exist and provisions them through CloudFormation. They solve different problems and are often used together in the same repository.

Release cadence, versioning and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-21. Recent releases follow a roughly weekly pattern: v2.270.0 on 2026-09-17, v2.269.0 on 2026-09-10, v2.268.0 on 2026-09-02. That cadence is the main upgrade cost. Frequent releases mean frequent opportunities to pick up fixes, and also frequent opportunities to pick up a change in an Experimental module.

Versioning has two layers. The project version moves quickly, while module stability governs whether a change can break you. The README is explicit that only major releases can carry breaking changes once a module is Stable. That is the mechanism to lean on when deciding how tightly to pin. A team using only Stable modules can upgrade within a major line with reasonable confidence; a team using Experimental modules should read the changelog for those modules before every bump.

The repository ships a CHANGELOG.md alongside CHANGELOG.v2.md and CHANGELOG.v2.alpha.md, and a DEPRECATED_APIs.md file, which is where deprecation notices accumulate. Those files are the practical upgrade checklist.

The licence is Apache-2.0, at the repository root in LICENSE, with a NOTICE file. Apache-2.0 is a permissive licence that includes an express patent grant, which is generally what enterprises want for a dependency they build on. This is a description of the licence text, not legal advice; if your organization has rules about attribution or notice files, check them against LICENSE and NOTICE yourself.

Editorial conclusion

Adopt the CDK if your team already writes TypeScript, Python, Java, .NET or Go and you want shared, reusable infrastructure components rather than a template file per stack. Do not adopt it if you need a provider-neutral tool, or if you rely on modules still marked Experimental, since those may take breaking API changes in any release. Before committing, run cdk synth on a scaffolded app and read the generated CloudFormation template end to end, then check the stability designation of every module you plan to use in the API Reference.

Frequently asked questions

Official sources

1. aws/aws-cdk on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases