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. Starting from version 0.20, CDKTF can also generate Terraform HCL as output by setting the --hcl flag when running cdktf synth.

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.

CDKTF to HCL

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

import { Construct } from "constructs";
import { TerraformOutput, TerraformStack, TerraformVariable } from "cdktf";
import { Pet } from "@cdktf/provider-random/lib/pet";
import { RandomProvider } from "@cdktf/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,
    });
  }
}

import software.constructs.Construct;
import com.hashicorp.cdktf.TerraformStack;
import com.hashicorp.cdktf.TerraformOutput;
import com.hashicorp.cdktf.TerraformOutputConfig;
import com.hashicorp.cdktf.TerraformVariable;
import com.hashicorp.cdktf.TerraformVariableConfig;
import com.hashicorp.cdktf.App;
import imports.random.provider.RandomProvider;
import imports.random.pet.Pet;
import imports.random.pet.PetConfig;

public class MainHCL extends TerraformStack {

    public MainHCL(Construct scope, String id) {
        super(scope, id);

        new RandomProvider(this, "default");
        TerraformVariable petNameLength = new TerraformVariable(this, "petNameLength", TerraformVariableConfig.builder()
                .type("number")
                .defaultValue(2)
                .description("Pet name length")
                .build());

        Pet myPet = new Pet(this, "example", PetConfig.builder()
                .length(petNameLength.getNumberValue())
                .build());

        new TerraformOutput(this, "name", TerraformOutputConfig.builder()
                .value(myPet.getId())
                .build());
    }

    public static void main(String[] args) {
        final App app = new App();
        new MainHCL(app, "random-pet-module");
        app.synth();
    }
}

from constructs import Construct
from cdktf import App, TerraformOutput, TerraformStack, TerraformVariable
from imports.random.pet import Pet
from imports.random.provider import RandomProvider

class HclInteropStack(TerraformStack):
    def __init__(self, scope: Construct, name: str):
        super().__init__(scope, name)

        RandomProvider(self, "default")
        petNameLength = TerraformVariable(self, "petNameLength",
                            type="number",
                            default=2,
                            description="Pet name length"
                        )

        myPet = Pet(self, "example",
                    length=petNameLength.number_value
                )

        TerraformOutput(self, "name",
            value=myPet.id
        )
# app = App()
# HclInteropStack(app, "random-pet-module")
# app.synth()

using System;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Constructs;
using HashiCorp.Cdktf;
using random.Provider;
using random.Pet;

namespace Examples
{
    class HclInteropStack : TerraformStack
    {
        public HclInteropStack(Construct scope, string name) : base(scope, name)
        {
            new RandomProvider(this, "default", new RandomProviderConfig { });

            var petNameLength = new TerraformVariable(this, "petNameLength", new TerraformVariableConfig
            {
                Type = "number",
                Default = 2,
                Description = "Pet name length"
            });

            var myPet = new Pet(this, "example", new PetConfig
            {
                Length = petNameLength.NumberValue
            });

            new TerraformOutput(this, "name", new TerraformOutputConfig
            {
                Value = myPet.Id
            });
        }
    }
}

import (
    "github.com/aws/constructs-go/constructs/v10"
    "github.com/aws/jsii-runtime-go"
    "github.com/hashicorp/terraform-cdk-go/cdktf"
    "github.com/hashicorp/terraform-cdk/examples/go/documentation/generated/hashicorp/random/pet"
    random "github.com/hashicorp/terraform-cdk/examples/go/documentation/generated/hashicorp/random/provider"
)

func NewHclInteropStack(scope constructs.Construct, name string) cdktf.TerraformStack {
    stack := cdktf.NewTerraformStack(scope, &name)

    random.NewRandomProvider(stack, jsii.String("default"), &random.RandomProviderConfig{})

    petNameLength := cdktf.NewTerraformVariable(stack, jsii.String("petNameLength"), &cdktf.TerraformVariableConfig{
        Type:        jsii.String("number"),
        Default:     jsii.Number(2),
        Description: jsii.String("Pet name length"),
    })

    myPet := pet.NewPet(stack, jsii.String("example"), &pet.PetConfig{
        Length: petNameLength.NumberValue(),
    })

    cdktf.NewTerraformOutput(stack, jsii.String("name"), &cdktf.TerraformOutputConfig{
        Value: myPet.Id(),
    })

    return stack
}

To use this as a Terraform module, run cdktf 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, cdktf synth generates Terraform JSON, but starting from version 0.20, CDKTF can also generate Terraform HCL output by passing the --hcl flag to cdktf 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 CDKTF

HCL can be used with Terraform CDK in two ways. Converting HCL code directly to a CDKTF language, and using Terraform modules directly within CDKTF projects.

• In order to convert HCL to a CDKTF language, the cdktf convert command can be used. It automatically translates HCL into a preferred CDKTF language. This is useful when working with an existing codebase that needs to be converted to CDKTF.

• While CDKTF has the ability to import HCL modules through cdktf 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 for Terraform projects.