Project Setup

There are several ways to create a new CDK for Terraform (CDKTF) project. You can create a new application from a pre-built or a custom template, and you can also convert an existing HCL project. When you create a new project, you can store Terraform state locally or use a remote backend. This page discusses these setup options in more detail.

Hands On: Try the CDK for Terraform Quick Start Demo and language-specific Get Started tutorials.

Initialize Project from a Template

Use init with a project template to automatically create and scaffold a new CDKTF project for your chosen programming language. Templates generate a new application with the necessary file structure for you to start defining infrastructure.

You can use a cdktf-cli pre-built template or a custom-built remote template when you initialize a new project.

$ cdktf init --template="templateName"

Use these template names for the available pre-built templates:

Note: Even though the CDKTF Java template sets up the Gradle build system for performance reasons, you can still use Maven to build your project. For more information refer to the Java examples which also include Maven examples: Java Examples.

Use a Local Backend

Add the --local flag to created a scaffolded project that is pre-configured to use a local backend. This means that your application stores Terraform state on your local machine and all Terraform operations run locally.

$ cdktf init --template="typescript" --local

Use HCP Terraform as a Remote Backend

When you run cdktf init without the --local flag, CDKTF defaults to using HCP Terraform as a remote backend. This lets you store state and run Terraform operations remotely in HCP Terraform. Refer to Set Up CDKTF With HCP Terraform for details.

Project Configuration

Initializing your project with a template generates a basic project in your preferred programming language that you can customize for your use case. You can manage global configuration for your project by customizing the cdktf.json configuration file or the application context.

`cdktf.json` Configuration File

The cdktf.json configuration file is where you can define the providers and modules that should be added to the project and supply custom configuration settings for the application. Refer to the cdktf.json documentation for more detail.

Application Context

All of the classes in your application can access the application context, so it is an ideal place to store project configuration. Context becomes available to any construct in your application after you run cdktf synth.

You can configure context as a static value in cdktf.json by setting the context property.

{
  // ...
  "context": {
    "myConfig": "value"
  }

You can also provide context when instantiating the App class.

const app = new App({ context: { myConfig: "value" } });

The following example uses App context to provide a custom tag value to an AWS EC2 instance.

import { Construct } from "constructs";
import { App, TerraformStack } from "cdktf";
import { AwsProvider } from "./.gen/providers/aws/provider";
import { Instance } from "./.gen/providers/aws/instance";

class MyStack extends TerraformStack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new AwsProvider(this, "aws", {
      region: "us-east-1",
    });

    new Instance(this, "Hello", {
      ami: "ami-2757f631",
      instanceType: "t2.micro",
      tags: {
        myConfig: this.node.getContext("myConfig"),
      },
    });
  }
}

const app = new App({ context: { myConfig: "value" } });
new MyStack(app, "hello-cdktf");
app.synth();

Generate Terraform Configuration

Run cdktf synth to synthesize your application into JSON configuration files that Terraform can use to manage infrastructure. You can then either use the JSON file with Terraform directly or provision your infrastructure using CDKTF CLI commands.

Refer to Deployment Patterns for example workflows, including connecting your CDKTF application to a Continuous Integration pipeline.

Convert an HCL Project to a CDKTF TypeScript Project

You can initialize a new CDKTF TypeScript project from an existing project written in HashiCorp Configuration Language (HCL). This option is currently limited to the typescript template.

To convert an existing HCL project, add --from-terraform-project to the init command with the TypeScript template.

$ cdktf init --template=typescript --from-terraform-project /path/to/my/tf-hcl-project

Usage Example

The following HCL configuration defines the random provider.

# File: /tmp/demo/main.tf

terraform {
  required_providers {
    random = {
      source = "hashicorp/random"
      version = "3.1.0"
    }
  }
}

provider "random" {
}

resource "random_pet" "server" {
}

Run the command to convert the HCL project in a new folder.

cdktf init --template=typescript --from-terraform-project /tmp/demo --local

CDKTF bootstraps a Typescript project and generates the equivalent configuration in JSON.

// File: /tmp/cdktf-demo/cdktf.json

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "projectId": "83684893-0e58-4a71-989a-ecb7c593a690",
  "terraformProviders": ["hashicorp/random@3.1.0"],
  "terraformModules": [],
  "context": {}
}

// File: /tmp/cdktf-demo/main.ts

/*Provider bindings are generated by running cdktf get.
Refer to https://www.terraform.io/cdktf/concepts/providers#providers for more details.*/
import { RandomProvider } from "./.gen/providers/random/provider";
import { Pet } from "./.gen/providers/random/provider";

import { Construct } from "constructs";
import { App, TerraformStack } from "cdktf";

class MyStack extends TerraformStack {
  constructor(scope: Construct, name: string) {
    super(scope, name);

    new RandomProvider(this, "random", {});
    new Pet(this, "server", {});
  }
}

const app = new App();
new MyStack(app, "cdktf-demo");
app.synth();

Convert HCL Files to CDKTF Format

Use the cdktf convert command to convert individual HCL files to CDKTF-compatible files in your preferred programming language. Refer to the cdktf convert command documentation for more information.