@cdktf/hcl2cdk

@cdktf/hcl2cdk

Uses @cdktf/hcl2cdk to transform HCL configuration to CDK constructs.

Usage

yarn add @cdktf/hcl2cdk

Convert HCL strings to Constructs

import { convert } from "@cdktf/hcl2cdk";

const hcl = `
  variable "name" {
    description = "Name to be used on all the resources as identifier"
    type        = string
    default     = ""
  }
`(async () => {
  const ts = await convert(hcl, { language: "typescript" });
  console.log(ts.imports); // just the necessary imports
  console.log(ts.code); // just the constructs
  console.log(ts.all); // code with imports
})();

// =>
import * as cdktf from "cdktf";

new cdktf.TerraformVariable(this, "imageId", {
  type: "string",
  default: "ami-abcde123",
  description: "What AMI to use to create an instance",
});

Convert a project

import * as hcl2cdk from "@cdktf/hcl2cdk";
import {
  readSchema,
  ConstructsMakerProviderTarget,
  LANGUAGES,
  config,
} from "@cdktf/provider-generator";

(async () => {
  const hcl = hcl2cdk.getTerraformConfigFromDir("/path/to/terraform/project");
  const providerRequirements = await hcl2cdk.parseProviderRequirements(hcl);
  const targets = Object.entries(providerRequirements).map(([name, version]) =>
    ConstructsMakerProviderTarget.from(
      new config.TerraformProviderConstraint(`${name}@ ${version}`),
      LANGUAGES[0],
    ),
  );
  // Get all the provider schemas, making the conversion more precise
  const { providerSchema } = await readSchema(targets);

  const mainTs = await hcl2cdk.convert(hcl, {
    language: "typescript",
    providerSchema: providerSchema,
  });

  await hcl2cdk.convertProject(
    hcl,
    mainTs.code,
    require("../cdktf.json"),
    { language: "typescript", providerSchema }, // Currently we only support Typescript for project conversion
  );
})();

This transforms your Terraform project into a CDK for Terraform project, besides the resource naming within Terraform the deployed resources should not differ between terraform plan and cdktf plan.

Known Limitations

Providers guessed can be not functional

If your HCL includes providers that are not mentioned under required_providers we infer the name, e.g. if you use the datadog_dashboard resource we infer the provider datadog which is right, but the namespace is missing, for DataDog it would be datadog/datadog. Instead we will try to use hashicorp/datadog and fail because this provider is not known to the registry. Please see the required providers docs for more information on how to specify providers.

Local Modules and Files

We don't move modules or files for you, if you reference local modules you have to move them so that the relative paths are correct. If you want to make use of files you need to wrap them in a TerraformAsset before using them.

Development

We have two types of test cases, one within lib that are on the unit level and one within test that are testing the entire package at once by converting and then synthesizing the resulting code.

In general, both test types can be run by npx jest <pathToTestCase>. You can add -u to update the snapshots and --watch to run the tests in watch mode.

To make the tests inside test faster we disable synthesizing and multi-language snapshots by default. You can enable them by setting the envinronment variable CI=true. Another way of improving the performance significantly is setting the TF_PLUGIN_CACHE_DIR to a valid directory in order to cache the provider binaries used within the tests. E.g. by running TF_PLUGIN_CACHE_DIR=(mktemp -d) npx jest <pathToTestCase> --watch.

Changelog

0.21.0

Breaking Changes

Minimum required Node version updated to 20.9

Since long-term support for Node.js 18 has ended, we updated our minimum compatible node version to 20.9.

fix

• fix: Stop escaping quotes within HEREDOC #3890
• fix: Pass migrate-state flag through to terraform init #3887
• fix: #3630 Slightly improve HCL rendering for skipped attributes #3878
• fix: issue where archive was being closed before the file finished writing causing corrupt TerraformAssets #3873

feat

• feat!: update minimum required Node.js version to 20.19 #3888
• feat: Skip Provider Locking on request #3879

chore

• chore(deps): bump tar-fs from 2.1.2 to 2.1.3 #3897
• chore: Upgrade base image for docker image used in building CDKTF #3872
• chore: Upgrading dependencies #3871
• chore(deps): bump the github-actions-backward-compatible group with 6 updates #3869
• chore(ci): use Dependabot to keep GitHub Actions updated #3867
• chore: add comments to docs #3863