Skip to main content
Terraform requires infrastructure configuration files written in either HashiCorp Configuration Language (HCL) or JSON syntax. CDK Terrain (CDKTN) works by translating configurations defined in an imperative programming language to JSON configuration files for Terraform. Starting from version 0.20, CDKTN can also generate Terraform HCL as output by setting the --hcl flag when running cdktn synth. CDKTN 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, CDKTN applications are interoperable with Terraform projects written in HCL. Specifically:
  • CDKTN applications can use all existing Terraform providers and HCL modules.
  • CDKTN can generate modules that HCL Terraform projects can use in their configurations.
This page shows how you can interoperate HCL and CDK Terrain configuration.

​
CDKTN to HCL

The following example is a CDKTN application that uses the hashicorp/random provider to generate a random name. 
import { Construct } from "constructs";
import { TerraformOutput, TerraformStack, TerraformVariable } from "cdktn";
import { Pet } from "@cdktn/provider-random/lib/pet";
import { RandomProvider } from "@cdktn/provider-random/lib/provider";

export class HCLInteropStack 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,
    });
  }
}
To use this as a Terraform module, run cdktn synth and copy the resulting cdktf.out/stacks/random-pet-module/cdk.tf.json file out to the module directory in your HCL project. By default, cdktn synth generates Terraform JSON, but starting from version 0.20, CDKTN can also generate Terraform HCL output by passing the --hcl flag to cdktn synth. After you transfer the cdk.tf.json (or cdk.tf) 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
}

​
HCL to CDKTN

HCL can be used with Terraform CDK in two ways. Converting HCL code directly to a CDKTN language, and using Terraform modules directly within CDKTN projects.
  • In order to convert HCL to a CDKTN language, the cdktn convert command can be used. It automatically translates HCL into a preferred CDKTN language. This is useful when working with an existing codebase that needs to be converted to CDKTN.
  • While CDKTN has the ability to import HCL modules through cdktn get when referenced within the cdktf.json file, Terraform modules can also be referenced without generating language specific bindings. The modules documentation shows how to use existing Terraform modules in CDK Terrain projects.