cdktf.json file is where you can supply custom configuration settings for your application and define the providers and modules that you want to use. When you initialize a new CDK Terrain project with a built-in template, the template generates a basic cdktf.json file in your root directory that you can customize for your application. Refer to the Project Setup documentation for more information about initializing a new project.
Editor Validation
CDK Terrain publishes a JSON schema forcdktf.json. Editors that support JSON schemas, such as VS Code and JetBrains IDEs, use it to suggest keys and flag invalid values as you type. Projects created with cdktn init already reference it. To add it to an existing project, set $schema to the schema for your CLI version (cdktn --version):
Specification
Minimal Configuration
The most basic configuration only defineslanguage and app, which every project needs. This is useful when you plan to use pre-built providers and you don’t need to generate any provider or module bindings.
Declare Providers and Modules
You must declare all of the providers and modules that require code bindings in yourcdktf.json file. CDKTN generates these code bindings from cdktf.json when you run cdktn get. We have a selection of pre-built providers available, but you may occasionally want to re-generate the code bindings for those providers yourself. For example, you may need a different version of that provider than the pre-built package. We do not provide pre-built modules, so you must always declare them in your cdktf.json file.
The schema for both providers and modules in CDK Terrain consists of a name, a source, and a version constraint.
You can declare providers and modules using either JSON or a string with the format source@ ~> version.
Provider Source
-
HashiCorp providers: You can specify official HashiCorp maintained providers by their name on the Terraform Registry. For example, you can use
awsto declare the official AWS provider:aws@ ~> 2.0 -
Community providers: You must provide the fully-qualified name. The fully-qualified name is available on the provider’s registry page. For example, to define the DataDog provider:
DataDog/datadog@ ~> 3.4.0
Module Source
-
For modules on the Terraform Registry, provide the the full registry namespace. For example, to define the AWS VPC module:
terraform-aws-modules/vpc/aws@ ~> 3.2.0. -
For local modules, please use the object format to ensure that CDKTN can properly name the generated classes.
Version Constraint
When you declare providers and modules in the string format, add the version constraint after the provider or module name separated by an@. For example, so provider|module@ ~> version. The version constraint is optional; when you omit the version constraint, CDK Terrain will download and use the latest version.
When you declare providers in JSON, add the constraint in the version property.
Declare Target Runtimes
The optionaltargetVersions field declares the Terraform and OpenTofu version ranges your project intends to support. CDK Terrain validates your configuration against this declaration at synthesis time — for example, the function availability validation checks that the Terraform functions you use are available across every version you target — without ever executing a binary.
Declare a range per product as an npm semver range, keyed by terraform and/or opentofu:
targetVersions entirely, CDK Terrain assumes the most portable interpretation — every supported release of both products: { "terraform": ">=1.5.7", "opentofu": ">=1.6.0" }.
Write required_version from targetVersions
CDK Terrain also writes each declared range into the stack’s directory as a required_version constraint, so Terraform and OpenTofu refuse to run outside the versions your project supports. For example, with:
cdk.tf.json:
settings.tf.json
settings.tofu.json
.tofu.json files, and OpenTofu 1.8 and later loads settings.tofu.json in place of settings.tf.json, so each binary enforces only its own range. OpenTofu 1.12 and later only reads required_version from .tofu and .tofu.json files.
- With HCL output, the files are
settings.tfandsettings.tofuinstead. - If you don’t declare
targetVersions, no files are written. - If you leave
opentofuout oftargetVersions, nosettings.tofu.jsonis written. - If you leave
terraformout, theopentofurange is written tosettings.tf.jsonas well. OpenTofu 1.6 and 1.7 only readsettings.tf.json, so this constrains them too. - A range that allows every version (
*) gets a file withoutrequired_version. - Ranges that use
||can’t be written as arequired_versionconstraint. CDK Terrain shows a warning and leaves that product unconstrained. - OpenTofu 1.6 and 1.7 read
settings.tf.json. If youropentofurange includes them and yourterraformrange would reject them, CDK Terrain shows a warning and doesn’t writesettings.tf.json. To constrain Terraform as well, raise theopentofufloor to>=1.8.0.
A
required_version set with an escape hatch ends up in cdk.tf.json instead, where Terraform and OpenTofu 1.8–1.11 both enforce it and OpenTofu 1.12 and later ignores it. Remove it once you declare targetVersions.Validate the Installed Binary
The declarative checks above never run Terraform or OpenTofu, so they behave identically in CI, package builds, and environments without either installed. To additionally verify that the binary actually installed on a machine falls inside your declaredtargetVersions, opt in with validateInstalledBinary:
validateInstalledBinary is true (default false), the commands that execute the Terraform-compatible CLI — diff, deploy, and destroy — check the installed binary before running it. The command fails if:
- the binary cannot be identified as Terraform or OpenTofu,
- its product is not declared in
targetVersions, or - its version falls outside the declared range.
Configure Files to Watch
When usingcdktn watch, CDKTN inspects the cdktf.jsons watchPattern property to determine which files to watch. If you do not specify a watchPattern property, CDKTN adds the default watch pattern for your language on the first run. The watchPattern expects an array of glob patterns, e.g. ["main.ts", "../constructs/**/*.ts", "lib/*.ts"].
Configuration Examples
Change the Output Directory
Definingoutput changes the directory where cdktn stores your generated Terraform configuration file. Terraform performs all operations within this directory.
The following example synthesizes the JSON Terraform configuration into my-workdir:
Build Providers
With the followingterraformProviders configuration, a cdktn get builds the latest AWS provider within the 2.X version range. CDKTN saves the generated code in in .gen by default. You can adjust this behavior with codeMakerOutput. Refer to the other examples on this page.
Build Modules
With the followingterraformModules configuration, a cdktn get builds the latest terraform-aws-modules/vpc/aws module from the Terraform Registry. The generated code will be saved into .gen by default. You can adjust this behavior with codeMakerOutput. Refer to the other examples on this page.
Build Providers & Modules
With the following example configuration, acdktn get builds both the AWS provider and the latest terraform-aws-modules/vpc/aws module from the Terraform Registry.
Build Multiple Providers
You can also build multiple providers or modules. The following example builds multiple providers.Build Providers in Custom Directory
The following configuration generates theaws provider bindings in the folder ./imports. The Python template uses this method to make it easier to reference the generated classes.
Enable Crash Reporting for the CLI
You can enable or disable crash reporting by setting thesendCrashReports property to true or false. Sending crash reports helps our team improve the CLI faster. Refer to Telemetry for more information about what we track. The separate sendUsageTelemetry property controls anonymous usage metrics; refer to Telemetry for how the two flags work.