Upgrading to CDKTN Version 0.23 - CDK Terrain (CDKTN)

0.23 contains breaking changes to the language runtimes CDK Terrain (cdktn) supports. The framework and CLI APIs are unchanged — you only need to make sure your toolchain is running a supported runtime version before upgrading.

If your project already uses recent runtime versions, upgrading is as simple as bumping cdktn and cdktn-cli (and any @cdktn/provider-* packages) to ^0.23.2.

Breaking Changes

Dropped runtime support

Language	No longer supported	Minimum supported	Recommended
Go	1.18 – 1.24	1.25	1.25+
Python	3.8	3.9	3.9+
TypeScript	< 4.5	4.5	Latest 5.x

Go: update your go.mod toolchain directive and CI to Go 1.25 or higher.
Python: update your environment / pyproject.toml / requirements.txt to Python 3.9 or higher.
TypeScript: provider generation now uses features from TypeScript 4.5. There is no official minimum TypeScript version at this time, but using the latest 5.x release is recommended.

These are hard requirements for v0.23. Building or synthesizing on an unsupported runtime is no longer tested or supported.

Upcoming Breaking Changes

Node.js 20.x is end-of-life. Node.js 22.x will become the minimum supported version in an upcoming release. Plan to move your local and CI environments to Node 22.x soon.

Upgrade Process

TypeScript/JavaScript
Python
Go
Java
C#

1. Ensure TypeScript 4.5+ (latest 5.x recommended):

npm install --save-dev typescript@latest

2. Bump cdktn packages in package.json:

{
  "dependencies": {
-   "cdktn": "^0.22.0",
+   "cdktn": "^0.23.2",
    "@cdktn/provider-aws": "^20.0.0"
  },
  "devDependencies": {
-   "cdktn-cli": "^0.22.0"
+   "cdktn-cli": "^0.23.2"
  }
}

3. Reinstall and verify:

npm install
npx tsc --noEmit

1. Ensure Python 3.9+:

python --version   # must be >= 3.9

2. Bump cdktn in requirements.txt or Pipfile:

- cdktn>=0.22.0
+ cdktn>=0.23.2

3. Reinstall:

pip install -r requirements.txt --force-reinstall

1. Update your Go toolchain to 1.25+ in go.mod:

- go 1.23
+ go 1.25

2. Bump the cdktn module:

require (
-   github.com/open-constructs/cdk-terrain-go/cdktn v0.22.0
+   github.com/open-constructs/cdk-terrain-go/cdktn v0.23.2
)

3. Tidy modules:

go mod tidy

Bump the dependency to 0.23.2 and rebuild. No JDK change is required by this release.

dependencies {
-   implementation "io.cdktn:cdktn:0.22.0"
+   implementation "io.cdktn:cdktn:0.23.2"
}

./gradlew build

Bump the package reference to 0.23.2 and restore. No .NET SDK change is required by this release.

<ItemGroup>
-   <PackageReference Include="Io.Cdktn" Version="0.22.0" />
+   <PackageReference Include="Io.Cdktn" Version="0.23.2" />
</ItemGroup>

dotnet restore

What Stays the Same

The framework and CLI surface is unchanged from v0.22. Configuration (cdktf.json), the output directory (cdktf.out/), CDKTF_* environment variables, the ~/.cdktf home directory, Terraform provider sources, and your Terraform state are all unaffected. See the v0.22 migration guide if you are still migrating from cdktf.

Verification

After upgrading, confirm your project still synthesizes:

# Synthesize
cdktn synth

# Verify output
ls cdktf.out/stacks/*/cdk.tf.json

Getting Help

Ask a question in the cdk.dev Slack
GitHub Issues: https://github.com/open-constructs/cdk-terrain/issues

Documentation Index

​Breaking Changes

​Dropped runtime support

​Upcoming Breaking Changes

​Upgrade Process

​What Stays the Same

​Verification

​Getting Help

Breaking Changes

Dropped runtime support

Upcoming Breaking Changes

Upgrade Process

What Stays the Same

Verification

Getting Help