» 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 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"
}

» 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.

  {
    // ...
    "moduleRequirements": [
      {
        "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"
    }
  ]
}

» Configuration Examples

» Change the Output Directory

Defining output changes the directory where cdktf will put your generated Terraform configuration file. All Terraform operations will be performed from this directory.

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

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

» Build Providers

With the terraformProviders configuration below, a cdktf get will build the latest AWS provider within the 2.X version range. The generated code will be saved into .gen by default. This can be adjusted with codeMakerOutput, see other examples below.

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

» Build Modules

With this terraformModules configuration, a cdktf get will build the latest terraform-aws-modules/vpc/aws module from the Terraform Registry. The generated code will be saved into .gen by default. This can be adjusted with codeMakerOutput - see other examples below.

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

» Build Providers & Modules

This combines the two examples above. A cdktf get will build 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"]
}

» Build Multiple Providers

It's possible to build multiple providers or modules as well.

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

» Build Providers in Custom Directory

This generates the aws provider bindings in the folder ./imports. This is used in the Python template to make it easier to reference the generated classes.

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