What is CDK for Terraform?

Cloud Development Kit for Terraform (CDKTF) allows you to use familiar programming languages to define and provision infrastructure. This gives you access to the entire Terraform ecosystem without learning HashiCorp Configuration Language (HCL) and lets you leverage the power of your existing toolchain for testing, dependency management, etc.

We currently support TypeScript, Python, Java, C#, and Go (experimental).

How does CDK for Terraform work?

CDK for Terraform leverages concepts and libraries from the AWS Cloud Development Kit to translate your code into infrastructure configuration files for Terraform.

At a high level, you will:

1. Create an Application: Use either a built-in or a custom template to scaffold a project in your chosen language.
2. Define Infrastructure: Use your chosen language to define the infrastructure you want to provision on one or more providers. CDKTF automatically extracts the schema from Terraform providers and modules to generate the necessary classes for your application.
3. Deploy: Use cdktf CLI commands to provision infrastructure with Terraform or synthesize your code into a JSON configuration file that others can use with Terraform directly.

You can use every Terraform provider and module available on the Terraform Registry, and you can use CDKTF with Terraform Cloud, Terraform Enterprise, and HashiCorp's policy as code framework, Sentinel. However, as CDKTF is under active development, we do not yet recommend it for production use cases (more details in Project Maturity below).

When to use CDK for Terraform

CDKTF offers many benefits, but it is not the right choice for every project. You should consider using CDKTF when:

• You have a strong preference or need to use a procedural language to define infrastructure.
• You need to create abstractions to help manage complexity. For example, you want to create constructs to model a reusable infrastructure pattern composed of multiple resources and convenience methods.
• You are comfortable doing your own troubleshooting and do not require commercial support.

You can make this choice for each team and project because CDK for Terraform interoperates with existing Terraform providers and modules.

Choosing a Language for your Project

Consider which of the supported languages you are most familiar with and which language best fits your organization's current tooling. We work towards providing feature parity and a good user experience across all supported languages, but there may be instances when new features will not be available for languages with experimental support.

If you plan to create and package your own constructs, we recommend choosing TypeScript. Using TypeScript allows you to use the cdktf constructs package generator to build and publish your constructs in multiple languages.

Project Maturity and Production Readiness

CDK for Terraform is under active development; we’re still working out key workflows and best practices. We’re iterating fast and are likely to introduce breaking changes to existing APIs to improve the overall user experience of the product.

This tool can be used with Terraform Cloud and Terraform Enterprise, but is not eligible for commercial support, and is not officially recommended for production use cases. Like other HashiCorp pre-1.0 tools, some early-adopter users are already using CDK for Terraform in production, and we are working with those users to validate and improve workflows.

Early adopters of CDK for Terraform should expect to encounter and work around bugs occasionally, may need to refactor their codebase with each major release, and will intermittently need to use HCL and understand how JSON Terraform configurations are generated. For example, overrides may be required to use Terraform functionality that cannot currently be expressed using CDK for Terraform. Our goal is to provide a user experience where this is an exceptional edge case. If you’re comfortable with this level of troubleshooting, we’re very interested in your feedback and practical experience. The Community page explains how to ask questions, submit issues, and contribute to the project.

These caveats apply to CDK for Terraform itself, which generates Terraform configurations. Generated Terraform configurations are applied using Terraform Core, a well established / mature tool to provision infrastructure.

Feature Flags

CDK for Terraform uses feature flags to enable potentially breaking behaviors in a release. Flags are stored as Runtime context values in cdktf.json as shown here.

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "context": {
    "excludeStackIdFromLogicalIds": "true"
  }
}

Feature flags are disabled by default, so existing projects that do not specify the flag will continue to work as expected with later CDKTF releases. New projects created using cdktf init include flags enabling all features available in the release that created the project. Edit cdktf.json to disable any flags for which you prefer the old behavior, or to add flags to enable new behaviors after upgrading the CDK for Terraform.

See the CHANGELOG in a given release for a description of any new feature flags added in that release. The CDKTF source file features.ts provides a complete list of all current feature flags.

Get Started

• Install CDKTF and set up your first project on HashiCorp Learn.
• Learn about CDKTF application architecture.
• Learn how to use key CDKTF concepts like providers, modules, and resources to define infrastructure.