» HCL Interoperability

Terraform requires infrastructure configuration files written in either HashiCorp Configuration Language (HCL) or JSON syntax. CDK for Terraform (CDKTF) works by translating configurations defined in an imperative programming language to JSON configuration files for Terraform.

CDKTF may not be the right choice for every team and project within your organization. For example, some teams may already be very familiar with Terraform and have created HCL modules, providers, etc. To provide flexibility, CDKTF applications are interoperable with Terraform projects written in HCL. Specifically:

  • CDKTF applications can use all existing Terraform providers and HCL modules.
  • CDKTF can generate modules that HCL Terraform projects can use in their configurations.

This page shows how you can interoperate HCL and CDK for Terraform configuration.


The TypeScript example below is a CDKTF application that uses the hashicorp/random provider to generate a random name.

import { Construct } from "constructs";
import { App, TerraformOutput, TerraformStack, TerraformVariable } from "cdktf";
import { Pet, RandomProvider } from "./.gen/providers/random";

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

    new RandomProvider(this, "default", {});
    const petNameLength = new TerraformVariable(this, "petNameLength", {
      type: "number",
      default: 2,
      description: "Pet name length",

    const myPet = new Pet(this, "example", {
      length: petNameLength.value,

    new TerraformOutput(this, "name", {
      value: myPet.id,

const app = new App();
new MyStack(app, "random-pet-module");

To use this as a Terraform module, run cdktf synth and copy the resulting cdktf.out/stacks/random-pet-module/cdktf.json file out to the module directory in your HCL project.

After you transfer the cdktf.json file, you can reference the pet name module as you would any other HCL Terraform module.

terraform {
  required_providers {
    docker = {
      source = "hashicorp/random"
      version = "~> 3.1"

module "pet" {
    source = "./mods/pet"
    petNameLength = "1"

output "name" {
  value = module.pet.name


Use the cdktf convert command to automatically translate existing HCL into a preferred CDKTF language. The modules documentation shows how to use existing Terraform modules in CDK for Terraform projects.