Cloud Development Kit for Terraform (CDKTF)

Warnings

• breaking CDKTF is officially deprecated as of December 10, 2025. HashiCorp will no longer maintain or develop the project, and no further updates, fixes, or compatibility changes will be provided.
  Fix: HashiCorp recommends migrating to standard Terraform HCL or AWS CDK if your infrastructure is tightly integrated with AWS CDK. Community forks may emerge, but continued use of CDKTF will be at your own risk.
• breaking Prior to reaching version 1.0, CDKTF followed semantic versioning where even minor version bumps could introduce breaking changes to APIs, generated provider bindings, and the synthesis process.
  Fix: Always consult the GitHub CHANGELOG and upgrade guides (available on the HashiCorp Developer site) for each specific version you are upgrading to. It's recommended to upgrade frequently in small steps.
• gotcha Provider import paths changed significantly in version 0.13. Previously, providers might be imported directly from `cdktf_cdktf_provider_<provider_name>`. The correct pattern now is typically `from cdktf_cdktf_provider_<provider_name>.provider import <ProviderName>`.
  Fix: Update provider import statements to reflect the nested `provider` module. For example, `from cdktf_cdktf_provider_aws.provider import AwsProvider`.
• gotcha Mismatched versions between the `cdktf-cli` and the `cdktf` Python library can lead to subtle and confusing errors during synthesis or deployment.
  Fix: Ensure that your globally installed `cdktf-cli` (`npm install --global cdktf-cli@latest`) and the `cdktf` Python library (`pip install cdktf`) are kept in sync, ideally running the same version number.
• gotcha After adding or modifying Terraform providers/modules in `cdktf.json` or installing new provider Python packages, you must run `cdktf get`. This command generates the necessary CDK Constructs for Terraform providers and modules within your project.
  Fix: Always run `cdktf get` after changing provider configurations or installing new provider bindings to ensure your project has the latest generated classes.

Install

• npm install --global cdktf-cli@latest Install CDKTF CLI (requires Node.js)
• pip install cdktf Install CDKTF Python library
• pip install cdktf-cdktf-provider-aws Install an example provider (e.g., AWS)

Imports

• App

  from cdktf import App

  Represents the CDKTF application.
• TerraformStack

  from cdktf import TerraformStack

  The base class for defining a stack of Terraform resources.
• Construct

  from constructs import Construct

  Base class for all constructs, shared with AWS CDK.
• AwsProvider

  from cdktf_cdktf_provider_aws.provider import AwsProvider

  Provider import for AWS. Provider imports generally follow 'cdktf_cdktf_provider_<provider_name>.provider'.

Quickstart

This quickstart defines an AWS S3 bucket. First, initialize a new CDKTF project with `cdktf init --template=python --providers=aws` in an empty directory. Then, replace the content of `main.py` with the code above. Ensure AWS credentials and default region are configured (e.g., via environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`). Run `cdktf get` to generate provider bindings, then `cdktf deploy` to provision the bucket.

import os
from constructs import Construct
from cdktf import App, TerraformStack, TerraformOutput
from cdktf_cdktf_provider_aws.provider import AwsProvider
from cdktf_cdktf_provider_aws.s3 import S3Bucket

class MyStack(TerraformStack):
    def __init__(self, scope: Construct, id: str):
        super().__init__(scope, id)

        AwsProvider(self, 'Aws', region=os.environ.get('AWS_REGION', 'us-east-1'))

        bucket = S3Bucket(self, 'MyBucket',
            bucket_prefix="my-unique-cdktf-bucket-",
            tags={
                "Environment": "Development",
                "ManagedBy": "CDKTF"
            }
        )

        TerraformOutput(self, 'bucket_name', value=bucket.id)


app = App()
MyStack(app, 'my-cdktf-aws-stack')
app.synth()