Note: CDK for Terraform is currently in beta.
This page explains the tools and processes that CDK for Terraform (CDKTF) uses to leverage the Terraform ecosystem and convert code into Terraform configuration files. It also explains the major components of a CDKTF application and how those pieces fit together.
» CDKTF Building Blocks
CDKTF leverages existing libraries and tools to help convert the definitions you write in your preferred programming language to Terraform configuration files. It also uses Terraform to provision and manage your infrastructure when you deploy your application.
» Amazon Web Services Cloud Development Kit
CDKTF shares core concepts and components with the Amazon Web Services Cloud Development Kit (AWS CDK), a tool that allows you to use familiar programming languages to define infrastructure on AWS CloudFormation. AWS CDK and CDK for Terraform are different products, and you cannot yet use AWS CDK constructs within CDKTF. The interoperability layer is a technical preview, and it is not yet ready for use in production.
jsii tool enables publishing polyglot libraries in all supported languages from a single Typescript code base. CDKTF uses Typescript types to generate an assembly file that
jsii uses to generate the code bindings for the other supported languages.
The diagram below shows how synthesizing a CDKTF application produces a series of artifacts in a designated output folder. You can then either use the JSON file with Terraform directly or provision your infrastructure using CDKTF CLI commands. All CDKTF CLI operations like
destroy communicate with Terraform for execution.
» CDKTF Components
CDKTF has two major components that allow you to define and provision infrastructure.
Lib: This is the
cdktfpackage that is the foundation for each CDKTF project. It contains all of the core libraries that allow you to leverage the Terraform ecosystem and synthesize your application into Terraform configuration files.
cdktfCLI allows you to initialize a new CDKTF project, adjust project settings, synthesize your infrastructure into Terraform configuration files, deploy your CDKTF application, and more. Refer to the CLI commands documentation for more details. You can also use some Terraform CLI commands like
terraform destroydirectly, but we recommend using the available
cdktf clicommands where possible.
» Application Architecture
CDKTF applications are structured as a tree of constructs, which the AWS documentation defines as "classes that define a 'piece of system state'". The foundational classes to build a CDKTF application are
Each CDKTF project has one or more
App instances that act as a container for the infrastructure configurations you create and deploy. An
App can have one or more
Stacks that represent a collection of related infrastructure.
Stack represents a collection of infrastructure resources that CDKTF synthesizes as a separate Terraform configuration. It is equivalent to a Terraform working directory.
Stacks allow you to separate the state management within an application. For example, you may want to deploy and manage separate infrastructure resources for development and testing. Reference the stack documentation for more details on when and how to use stacks in your project.
Resource represents the definition for one or more infrastructure objects. Resources and their required attributes vary depending on the provider. Reference the providers and resources documentation for more details.
Rather than defining resources by hand, you can leverage constructs to reuse existing resource configurations written in your programming language. For example, you might create a construct that describes a Kubernetes deployment, import it into your application, and customize the deployment via the exposed properties.
This is an example of a custom construct written in TypeScript that creates a machine image. The exported interface allows users to specify the instance type and one or more tags. The rest of the configuration is defined in the construct and is abstracted from the consumer.
Reference the constructs documentation for more details.
Reference the examples page to see configured CDKTF applications in each supported programming language.