Skip to main content
This page explains the tools and processes that CDK Terrain (CDKTN) uses to leverage the Terraform ecosystem and convert code into Terraform configuration files. It also explains the major components of a CDKTN application and how those pieces fit together.

​
CDKTN Building Blocks

CDKTN 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

CDKTN 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 Terrain are different products, and you cannot yet use AWS CDK constructs within CDKTN. The interoperability layer is a technical preview, and it is not yet ready for use in production.

​
jsii

The jsii tool enables publishing polyglot libraries in all supported languages from a single Typescript code base. CDKTN uses Typescript types to generate an assembly file that jsii uses to generate the code bindings for the other supported languages.

​
Terraform / OpenTofu

CDKTN synthesizes infrastructure that you define in a supported programming language into JSON configuration files that Terraform or OpenTofu can use to manage infrastructure. The following diagram shows how synthesizing a CDKTN 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 CDKTN CLI commands. All CDKTN CLI operations like diff, deploy, and destroy communicate with Terraform (or OpenTofu) for execution. CDK Terrain Workflowcdktn initCDKTN creates a projectwhere you define infrastructureCDKTN Appcdktn synthCDKTN generatesconfiguration filesOutputJSONConfigArtifactscdktn deployOpenTofu / Terraform provisionsyour infrastructureOpenTofu/ TerraformAWSAzureGCPKubernetes3000+providers CDKTN also automatically extracts the schemas from existing Terraform providers or modules and generates the necessary code bindings for your application. Provider and Module Code GenerationProviderModuleJSON SchemaCode GeneratorTypeScriptPythonJavaC#Go

​
CDKTN Components

CDKTN has two major components that allow you to define and provision infrastructure.
  • Lib: This is the cdktn package that is the foundation for each CDKTN project. It contains all of the core libraries that allow you to leverage the Terraform ecosystem and synthesize your application into Terraform configuration files.
  • CLI: The cdktn CLI allows you to initialize a new CDKTN project, adjust project settings, synthesize your infrastructure into Terraform configuration files, deploy your CDKTN application, and more. Refer to the CLI commands documentation for more details. You can also use some Terraform CLI commands like terraform apply and terraform destroy directly, but we recommend using the available cdktn cli commands where possible. If you use OpenTofu, set TERRAFORM_BINARY_NAME=tofu. Refer to Environment Variables for details.

​
Application Architecture

CDKTN 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 CDKTN application are App, Stack, and Resource. CDKTN Application ArchitectureAppStack (Development)ResourceResourceResourceStack (Test)ResourceResourceResourceOutputOutputJSONConfigArtifactsJSONConfigArtifactsOpenTofu/ Terraform

​
App Class

Each CDKTN 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 Class

A Stack represents a collection of infrastructure resources that CDKTN 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 Class

A Resource represents the definition for one or more infrastructure objects. Resources and their required attributes vary depending on the provider. Reference the resources documentation for more details.

​
Constructs

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.

​
Examples

Reference the examples page to see configured CDKTN applications in each supported programming language.