Skip to main content
There are several ways to create a new CDK Terrain (CDKTN) 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.
Try the CDK Terrain 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 CDKTN 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 cdktn-cli pre-built template or a custom-built remote template when you initialize a new project. 
$ cdktn init --template="templateName"
Use these template names for the available pre-built templates:
  • typescript
  • python
  • c#
  • java
  • go
Note: Even though the CDKTN 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. 
$ cdktn init --template="typescript" --local

​
Use HCP Terraform as a Remote Backend

When you run cdktn init without the --local flag, CDKTN 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 CDKTN 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 cdktn 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 "cdktn";
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-cdktn");
app.synth();

​
Generate Terraform Configuration

Run cdktn 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 CDKTN CLI commands. Refer to Deployment Patterns for example workflows, including connecting your CDKTN application to a Continuous Integration pipeline.

​
Convert an HCL Project to a CDKTN TypeScript Project

You can initialize a new CDKTN 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. 
$ cdktn 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. 
cdktn init --template=typescript --from-terraform-project /tmp/demo --local
CDKTN bootstraps a Typescript project and generates the equivalent configuration in JSON. 
// File: /tmp/cdktn-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/cdktn-demo/main.ts

/*Provider bindings are generated by running cdktn get.
Refer to https://www.terraform.io/cdktn/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 "cdktn";

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, "cdktn-demo");
app.synth();

​
Convert HCL Files to CDKTN Format

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