Skip to main content
The 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 for cdktf.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 defines language 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 your cdktf.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 aws to 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 optional targetVersions 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:
Omitting a product means your project does not target it. When you omit targetVersions entirely, CDK Terrain assumes the most portable interpretation — every supported release of both products: { "terraform": ">=1.5.7", "opentofu": ">=1.6.0" }.
Values must be npm semver ranges (for example >=1.5.7 or ~1.5.7), not Terraform’s ~> pessimistic constraint syntax. CDK Terrain validates targetVersions when it parses cdktf.json and fails with an error if a range is malformed or uses ~>.

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:
each stack’s directory gets one file per declared product, next to cdk.tf.json:
settings.tf.json
settings.tofu.json
Terraform ignores .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.tf and settings.tofu instead.
  • If you don’t declare targetVersions, no files are written.
  • If you leave opentofu out of targetVersions, no settings.tofu.json is written.
  • If you leave terraform out, the opentofu range is written to settings.tf.json as well. OpenTofu 1.6 and 1.7 only read settings.tf.json, so this constrains them too.
  • A range that allows every version (*) gets a file without required_version.
  • Ranges that use || can’t be written as a required_version constraint. CDK Terrain shows a warning and leaves that product unconstrained.
  • OpenTofu 1.6 and 1.7 read settings.tf.json. If your opentofu range includes them and your terraform range would reject them, CDK Terrain shows a warning and doesn’t write settings.tf.json. To constrain Terraform as well, raise the opentofu floor 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 declared targetVersions, opt in with validateInstalledBinary:
When 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 using cdktn 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

Defining output 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 following terraformProviders 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 following terraformModules 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, a cdktn 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 the aws 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 the sendCrashReports 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.