»Configuration File

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 for Terraform 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.

Specification

export enum Language {
  TYPESCRIPT = "typescript",
  PYTHON = "python",
  CSHARP = "csharp",
  JAVA = "java",
  GO = "go",
}

export interface TerraformDependencyConstraint {
  readonly name: string; // name of the module / provider
  readonly source?: string; // path / url / registry identifier for the module / provider
  readonly version?: string; // version constraint (https://www.terraform.io/docs/language/providers/requirements.html#version-constraints)
}
type RequirementDefinition = string | TerraformDependencyConstraint;

export interface Config {
  readonly app?: string; // The command to run in order to synthesize the code to Terraform compatible JSON
  readonly language?: Language; // Target language for building provider or module bindings. Currently supported: `typescript`, `python`, `java`, `csharp`, and `go`
  readonly output: string; // Default: 'cdktf.out'. Where the synthesized JSON should go. Also will be the working directory for Terraform operations
  readonly codeMakerOutput: string; // Default: '.gen'. Path where generated provider bindings will be rendered to.
  readonly projectId: string; // Default: generated UUID. Unique identifier for the project used to differentiate projects
  readonly sendCrashReports: boolean; // Default: false. Whether to send crash reports to the CDKTF team
  readonly terraformProviders?: RequirementDefinition[]; // Terraform Providers to build
  readonly terraformModules?: RequirementDefinition[]; // Terraform Modules to build
}

export enum Language {
  TYPESCRIPT = "typescript",
  PYTHON = "python",
  CSHARP = "csharp",
  JAVA = "java",
  GO = "go",
}

export interface TerraformDependencyConstraint {
  readonly name: string; // name of the module / provider
  readonly source?: string; // path / url / registry identifier for the module / provider
  readonly version?: string; // version constraint (https://www.terraform.io/docs/language/providers/requirements.html#version-constraints)
}
type RequirementDefinition = string | TerraformDependencyConstraint;

export interface Config {
  readonly app?: string; // The command to run in order to synthesize the code to Terraform compatible JSON
  readonly language?: Language; // Target language for building provider or module bindings. Currently supported: `typescript`, `python`, `java`, `csharp`, and `go`
  readonly output: string; // Default: 'cdktf.out'. Where the synthesized JSON should go. Also will be the working directory for Terraform operations
  readonly codeMakerOutput: string; // Default: '.gen'. Path where generated provider bindings will be rendered to.
  readonly projectId: string; // Default: generated UUID. Unique identifier for the project used to differentiate projects
  readonly sendCrashReports: boolean; // Default: false. Whether to send crash reports to the CDKTF team
  readonly terraformProviders?: RequirementDefinition[]; // Terraform Providers to build
  readonly terraformModules?: RequirementDefinition[]; // Terraform Modules to build
}

Minimal Configuration

The most basic configuration only defines app. This is useful when you plan to use pre-built providers and you don't need to generate any provider or module bindings.

{
  "app": "npm run --silent compile && node main.js"
}

{
  "app": "npm run --silent compile && node main.js"
}

Declare Providers and Modules

You must declare all of the providers and modules that require code bindings in your cdktf.json file. CDKTF generates these code bindings from cdktf.json when you run cdktf 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 for Terraform 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 CDKTF can properly name the generated classes.

{
  // ...
  "terraformModules": [
    {
      "name": "myLocalModule",
      "source": "../my-modules/local-module"
    }
  ]
}

{
  // ...
  "terraformModules": [
    {
      "name": "myLocalModule",
      "source": "../my-modules/local-module"
    }
  ]
}

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 for Terraform will download and use the latest version.

When you declare providers in JSON, add the constraint in the version property.

{
  //...
  "terraformProviders": [
    {
      "name": "aws",
      "source": "hashicorp/aws",
      "version": "~> 3.22"
    }
  ]
}

{
  //...
  "terraformProviders": [
    {
      "name": "aws",
      "source": "hashicorp/aws",
      "version": "~> 3.22"
    }
  ]
}

Enable Features

CDKTF uses feature flags to enable potentially breaking behaviors in a release. Flags are stored as runtime context values in cdktf.json. Feature flags are disabled by default, so existing projects that do not specify the flag will continue to work as expected with later CDKTF releases. New projects created using cdktf init include flags enabling all features available in the release that created the project.

Edit cdktf.json to disable flags for which you prefer the old behavior, or to add flags to enable new behaviors after upgrading. The following example adds a feature flag.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "context": {
    "excludeStackIdFromLogicalIds": "true"
  }
}

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "context": {
    "excludeStackIdFromLogicalIds": "true"
  }
}

The CHANGELOG on Github contains a description of new feature flags in each release, and the CDKTF source file features.ts provides a complete list of all feature flags.

Configure Files to Watch

When using cdktf watch, CDKTF inspects the cdktf.jsons watchPattern property to determine which files to watch. If you do not specify a watchPattern property, CDKTF 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 cdktf stores your generated Terraform configuration file. Terraform performs all operations within this directory.

The following example synthesizes the JSON Terraform configuration into my-workdir:

{
  "app": "npm run --silent compile && node main.js",
  "output": "my-workdir"
}

{
  "app": "npm run --silent compile && node main.js",
  "output": "my-workdir"
}

Build Providers

With the following terraformProviders configuration, a cdktf get builds the latest AWS provider within the 2.X version range. CDKTF saves the generated code in in .gen by default. You can adjust this behavior with codeMakerOutput. Refer to the other examples on this page.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformProviders": ["aws@~> 2.0"]
}

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformProviders": ["aws@~> 2.0"]
}

Build Modules

With the following terraformModules configuration, a cdktf 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.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformModules": ["terraform-aws-modules/vpc/aws"]
}

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformModules": ["terraform-aws-modules/vpc/aws"]
}

Build Providers & Modules

With the following example configuration, a cdktf get builds both the AWS provider and the latest terraform-aws-modules/vpc/aws module from the Terraform Registry.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformModules": ["terraform-aws-modules/vpc/aws"],
  "terraformProviders": ["aws@~> 2.0"]
}

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformModules": ["terraform-aws-modules/vpc/aws"],
  "terraformProviders": ["aws@~> 2.0"]
}

Build Multiple Providers

You can also build multiple providers or modules. The following example builds multiple providers.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformProviders": [
    "null",
    "aws",
    "google",
    "azurerm",
    "kubernetes",
    "consul",
    "vault",
    "nomad"
  ]
}

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "terraformProviders": [
    "null",
    "aws",
    "google",
    "azurerm",
    "kubernetes",
    "consul",
    "vault",
    "nomad"
  ]
}

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.

{
  "language": "python",
  "app": "pipenv run ./main.py",
  "terraformProviders": ["aws@~> 2.0"],
  "codeMakerOutput": "imports"
}

{
  "language": "python",
  "app": "pipenv run ./main.py",
  "terraformProviders": ["aws@~> 2.0"],
  "codeMakerOutput": "imports"
}

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.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "sendCrashReports": true
}

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "sendCrashReports": true
}