Skip to content

CDKTF

Terrateam configuration updates are required in order to enable CDKTF.

Terrateam Configuration Terrateam behavior can be configured via a config.yml. This file is located in a directory named .terrateam at the root of your Terraform repository: .terrateam/config.yml.

See Configuration documentation for details.

Full Example

Repository Layout

josh@elmer:~ $ tree cdktf-code/
cdktf-code/
└── prod
    └── main.ts

1 directory, 1 file

CDKTF in TypeScript

cdktf-code/prod/main.ts

import { Construct } from "constructs";
import { App, TerraformStack } from "cdktf";
import * as Null from './.gen/providers/null';

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

    new Null.provider.NullProvider(this, 'test-provider');
    new Null.resource.Resource(this, 'test');
  }
}

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

Terrateam Configuration

.terrateam/config.yml

workflows:
  - tag_query: cdktf-code
    cdktf: true
dirs:
  prod:   
    tags: [cdktf-code]
    when_modified:   
      file_patterns: ['${DIR}/*.ts']
    stacks:
      'cdktf-stack1':
        tags: []
      'cdktf-stack2':
        tags: []

Configuration Explained

  1. Lines 1-3: Any directory containing the tag cdktf-code will enable CDKTF in a Terrateam operation. See Workflows for details.
  2. Lines 7-8: The prod directory:
    1. Terrateam operations should be triggered if any file with matches the *.ts pattern is changed in a pull request.
    2. Assign the tag cdktf-code to be used in workflows.
    3. Define two stacks: cdktf-stack1, cdktf-stack2. See When Modified for details.

Planning and Applying

Terrateam operations are identical when CDKTF is enabled. However, enabling CDKTF does create an additional implicit tag to match on the stack giving users the flexibility to run operations against stacks.

For example, to plan any directory with a stack named cdktf-stack1, one could comment the following in a pull request:

terrateam plan stack:cdktf-stack1

CDKTF Frequently Asked Questions

Last updated: 2023/02/20

What does CDKTF mean?

CDKTF stands for Cloud Development Kit for Terraform. The term CDK is used to describe tools which allow managing cloud infrastructure using common programming languages.

What problem does CDKTF solve?

Developers can manage their infrastructure using familiar programming languages in place of the Terraform HCL language. As well as using familiar programming languages, developers benefit from being able to use the ecosystem of their language of choice when developing infrastructure components.

CDKTF was initially developed in collaboration with AWS which had released AWS CDK. AWS CDK turned out to be popular and developers really liked being able to work in their language of choice.

AWS CDK and CDKTF are similar to Pulumi, which was developed with the idea of managing infrastructure using familiar programming languages.

Key differences between the three offerings are as follows:

  • Pulumi has its own engine for planning and applying changes
  • AWS CDK generates AWS Cloud Assembly for planning and applying changes
  • CDKTF generates Terraform code (HCL) for planning and applying changes

What languages does CDKTF support?

CDKTF can be written in the following languages:

Is CDKTF production ready?

Yes. On Aug 1 2022, HashiCorp announced that CDKTF is Generally Available and ready for production usage. CDKTF is still a maturing technology, however, you should feel confident using it in a production environment.

What are the advantages of CDKTF?

  • Developers who are familiar with programming languages but not HCL can contribute to infrastructure changes.
  • Being able to express infrastructure in TypeScript, Python, Java, C#, or Go allows for leveraging the ecosystem of those languages.
  • The development environments (editors, IDEs, language servers, testing frameworks) are very mature.
  • Programming languages are more powerful than HCL.
  • More people are familiar with programming languages than HCL.

What are the disadvantages of CDKTF?

  • CDKTF is still maturing. The underlying engine which executes CDKTF is robust. One needs to have implementations of providers and resources in the CDKTF ecosystem, which is still growing.
  • Documentation, especially around providers, is lacking. One might have to read code in order to understand how to use a provider.
  • CDKTF is complicated. It requires converting code written in a programming language to HCL, which you could have written yourself.
  • CDKTF also adds new concepts (for example “stacks”), making it not a direct one-to-one translation of Terraform. This means those developers who are familiar with Terraform will need to learn CDKTF before they are effective.
  • With great power comes great responsibility. Programming languages are much more expressive than HCL. While HCL has its limitations, these limitations also mean the code has a ceiling of complexity. Programming languages do not have the same constraints.

Should I use CDKTF?

Like most technical decisions: it depends.

Whether or not CDKTF is the right decision for you is something you need to determine. Here are some factors you should consider:

  1. Is using CDKTF going to make it easier for developers in my organization to contribute infrastructure changes?
  2. Do I have the innovation tokens to use a maturing technology?

CDKTF will continue to be developed and improved by HashiCorp, so if you like where it is now, it is probably a good decision.

Does CDTKTF require Terraform Cloud?

No. You can use CDKTF anywhere.

What language is CDKTF implemented in?

The CDKTF CLI is implemented in TypeScript. Providers and resources are implemented in TypeScript as well. jsii is used to compile the providers and resources to the supported languages.

How does CDKTF work?

The high-level process of how CDKTF works is as follows:

  1. Developer writes code in their preferred programming language that CDKTF supports.
  2. The code must create an instance of an “app”.
  3. The developer creates “stacks”, “providers”, and “resources” and adds them to the “app”. This creates an internal representation of the infrastructure which can be turned into something else using the synth function.
  4. After constructing the infrastructure objects, at the end the developer must call the synth function.
  5. The user then executes cdktf diff, cdktf deploy, or cdktf synth.
  6. The CDKTF CLI runs the code the developer wrote and the call to synth knows how to convert the app (which has the stack and resources and providers added to it) to the JSON representation of HCL.
  7. The CDKTF CLI can then run terraform plan or terraform apply on the HCL.

It is possible that cdktf diff and cdktf deploy could perform the translation to Terraform HCL and execution in-memory, however cdktf synth will always produce Terraform HCL in a directory that you can manually run the Terraform CLI against.

Considering the following CDKTF code in TypeScript:

import { Construct } from "constructs";
import { App, TerraformStack } from "cdktf";
import * as Null from './.gen/providers/null';

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

    new Null.provider.NullProvider(this, 'test-provider');
    new Null.resource.Resource(this, 'test');
  }
}

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

On the highlighted line number 16, app.synth(), the entire app has been created and all providers and resources have been added to the stack. The synth call can then produce Terraform HCL files and the CDKTF CLI can execute terraform plan or terraform apply.

How can I convert Terraform code to CDKTF?

The CDKTF CLI can convert Terraform files using cdktf convert.

What is an app?

CDKTF code constructs an object called “app”. This represents all of the infrastructure that will be generated in CDKTF. Stacks will be added to the app. And providers and resources will be added to the stack.

What is a stack?

Stacks represent a collection of infrastructure configuration that will be managed. You can think of them as somewhere between Terraform modules and workspaces. You might use a stack to represent the infrastructure in an AWS region and then create an instance of that stack per region. For example:

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

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

    // define resources here
  }
}

const app = new App();
new MyStack(app, "cdktf-stack1", "us-east-1");
new MyStack(app, "cdtff-stack2", "us-west-1");
app.synth();

Where can I learn more about CDKTF?