Terraform Provider Bridging

Provider bridging translates Terraform provider schemas into native Python constructs. This process enables strict schema validation, IDE autocomplete, and programmatic infrastructure composition. Engineering teams leverage bridging to modernize legacy Terraform codebases without abandoning established provider ecosystems.

This topic sits inside CDKTF Workflows & Terraform Synthesis and answers a narrow but load-bearing question: what exactly happens between hashicorp/aws@~> 6.0 in a manifest file and from cdktf_cdktf_provider_aws.s3_bucket import S3Bucket in your editor? Two guides sit beneath it. Converting existing Terraform HCL to CDKTF Python walks a legacy HCL estate through translation and state import so nothing is recreated. Using multiple Terraform providers in one CDKTF stack covers provider aliases and per-resource routing once a single default provider is no longer enough.

Everything below assumes the bridge is a compiler, not a wrapper. It reads a schema, emits code, and that code has properties — naming rules, type fidelity, version coupling — that determine how your Python behaves months later when the provider ships a breaking release.

Problem Framing

Terraform's value is not its language. It is the several thousand provider plugins that know how to create, read, update, and delete objects in every cloud and SaaS product an engineering organisation touches. A team that moves to Python for the readability, the type checking, and the ability to unit test a stack does not want to give that up and start writing HTTP clients by hand.

Bridging is the mechanism that keeps both. The provider plugin stays exactly as it is — a Go binary speaking Terraform's plugin protocol — and a code generator produces a Python surface over its declared schema. What you write is Python. What runs against the cloud API is the same provider binary Terraform would have used, invoked with the same arguments, producing the same state entries.

Bridging operates as a programmatic translation layer between Terraform provider registries and Python runtime environments. The synthesis engine parses provider JSON schemas and generates strongly typed Python classes via cdktf get. This eliminates runtime attribute guessing and enforces compile-time validation.

The foundational synthesis pipeline documented in CDKTF Architecture & Synthesis ensures deterministic schema resolution. Translation occurs before synthesis, not during it: by the time cdktf synth runs, the Python classes already exist on disk and are ordinary importable modules. Generated Python artifacts map one-to-one onto Terraform resource types, and the JSON they synthesize is the same JSON an equivalent HCL file would have produced.

The failure modes are equally specific. A provider version bump changes the schema, the generator emits different classes, and Python that referenced a removed argument stops importing. A resource whose Terraform name collides with a generated struct gets a suffixed class name that no amount of guessing will produce. An attribute typed as any in the provider schema arrives in Python as typing.Any, which means the type checker stops helping precisely where the configuration is most error-prone. Those are the details this topic covers.

Prerequisites

• Node.js 18+ on the PATH. CDKTF's core is TypeScript, and the Python classes are jsii proxies that call into a Node process. No Node, no synthesis — even for a pure-Python stack.
• Terraform 1.5+ CLI, used by cdktf get to fetch provider schemas and by cdktf deploy to run the plan and apply.
• CDKTF CLI 0.20+ and Python 3.9 or newer with type annotations enabled.
• Registry network access from wherever you run cdktf get. Air-gapped builds need a filesystem or network mirror configured through .terraformrc.
• A pinned provider constraint in cdktf.json and a matching pin for any prebuilt provider package in requirements.txt or pyproject.toml.

# CLI: confirm every part of the bridge toolchain before generating bindings
node --version          # 18+ — the jsii kernel runs here
terraform version       # 1.5+ — used to fetch provider schemas
cdktf --version         # 0.20+
python -c "import cdktf, jsii; print(cdktf.__name__, jsii.__name__)"

How a Provider Schema Becomes a Python Class

The generation step is worth understanding in detail, because almost every confusing bridging error is explained by one of its stages.

cdktf get reads the terraformProviders array in cdktf.json, resolves each constraint against the registry, and downloads the provider plugin into a temporary working directory. It then asks Terraform itself for the machine-readable schema — the same document terraform providers schema -json prints — which describes every resource type, every data source, every attribute, its type, and whether it is required, optional, or computed.

That schema is fed to CDKTF's provider generator, which produces a jsii assembly: a language-neutral description of classes, constructors, and property bags. jsii then emits idiomatic bindings per language. For Python, the result lands in the directory named by codeMakerOutput in cdktf.json — imports in the standard Python template — as an ordinary package you import like any other.

# CLI: generate provider bindings from the pins in cdktf.json
cat cdktf.json
cdktf get                       # writes Python packages under ./imports
ls imports/aws | head           # provider.py, s3_bucket.py, data_aws_ami.py, ...

Naming rules you will meet immediately

The mapping from Terraform names to Python names is mechanical, and once you know the rules you can predict any import path without searching.

A resource type aws_s3_bucket becomes a module s3_bucket and a class S3Bucket. A data source aws_ami becomes module data_aws_ami and class DataAwsAmi. Attribute names keep their snake_case form in Python — bucket, force_destroy, storage_encrypted — even though the TypeScript layer between them uses camelCase and the synthesized JSON converts back to snake_case.

Nested blocks become their own classes, named by concatenating the parent resource and the block. The versioning_configuration block of aws_s3_bucket_versioning arrives as S3BucketVersioningVersioningConfiguration. These are keyword-only structs, not dictionaries, so a typo is a TypeError at construction rather than a silent no-op at apply time.

Then there is the suffix that surprises everyone. When a generated class name would collide with another symbol in the same jsii namespace, jsii disambiguates by appending a capital A. That is why the versioning resource is S3BucketVersioningA and not S3BucketVersioning. The rule is not arbitrary — the collision is real — but it is invisible from the Terraform side, so read the generated module's exports rather than guessing.

# CLI: python -c "import stacks.naming"   (import-only smoke test of the generated names)
from cdktf_cdktf_provider_aws.s3_bucket import S3Bucket
from cdktf_cdktf_provider_aws.s3_bucket_versioning import (
    S3BucketVersioningA,
    S3BucketVersioningVersioningConfiguration,
)
from cdktf_cdktf_provider_aws.data_aws_caller_identity import DataAwsCallerIdentity

# Provider note: the trailing "A" is a jsii collision suffix, not a version marker.
RESOURCE_CLASSES: dict[str, type] = {
    "aws_s3_bucket": S3Bucket,
    "aws_s3_bucket_versioning": S3BucketVersioningA,
    "aws_caller_identity (data source)": DataAwsCallerIdentity,
}

BLOCK_STRUCTS: dict[str, type] = {
    "versioning_configuration": S3BucketVersioningVersioningConfiguration,
}

Tokens: why an attribute is not a value

The second mechanism that trips people up is that resource attributes are not values at the time your Python runs. bucket.arn does not contain an ARN; it contains a token — a placeholder string of the form ${TfToken[TOKEN.7]} — that CDKTF replaces during synthesis with the corresponding Terraform interpolation, ${aws_s3_bucket.data.arn}.

This has two practical consequences. First, you cannot branch on an attribute value in Python: if bucket.arn.endswith("prod"): compares a token, not an ARN, and will silently take the wrong branch on every run. Any conditional that depends on a value the provider computes must be expressed with Terraform functions through cdktf.Fn, or moved into a data source lookup that resolves before synthesis. Second, string interpolation works fine — an f-string embeds the token and synthesis substitutes it — so building an ARN prefix or a policy document from attributes is safe as long as you never inspect the result.

# CLI: cdktf synth && grep -o '\${aws_s3_bucket[^}]*}' cdktf.out/stacks/bridged-aws-stack/cdk.tf.json
from typing import Any, Dict
from cdktf import Fn, Token
from cdktf_cdktf_provider_aws.s3_bucket import S3Bucket

def bucket_object_arn_pattern(bucket: S3Bucket) -> str:
    """Build an ARN pattern from a computed attribute.

    bucket.arn is a token at Python runtime; the f-string embeds the token and
    synthesis rewrites it to ${aws_s3_bucket.<id>.arn}. Never branch on it.
    """
    # State implication: the emitted JSON carries an interpolation, so Terraform
    # records the dependency edge in state and orders the apply correctly.
    return f"{bucket.arn}/*"

def as_string(raw: Any) -> str:
    """Token.as_string turns an untyped (Any) schema field into a usable token."""
    return Token.as_string(raw)

def encoded(document: Dict[str, Any]) -> str:
    """Fn.jsonencode defers encoding to Terraform, keeping tokens intact."""
    return Fn.jsonencode(document)

Prebuilt Packages Versus Locally Generated Bindings

There are two ways to obtain the same classes, and the choice affects build time, reproducibility, and how painful provider upgrades are.

Prebuilt providers are published to PyPI by HashiCorp — cdktf-cdktf-provider-aws, cdktf-cdktf-provider-google, cdktf-cdktf-provider-kubernetes, and dozens more. You pip install them, import from cdktf_cdktf_provider_aws, and skip cdktf get entirely. Build times drop to nothing, the artifact is hash-pinned in your lockfile, and offline CI works. The cost is coupling: each prebuilt release targets a compatible range of the cdktf runtime, so upgrading CDKTF and upgrading the provider become one decision rather than two.

Locally generated bindings come from cdktf get and land in imports/. They are the only option for providers with no prebuilt package — an internal provider, a small community provider, or a provider you have forked. They also let you pin a provider version that no prebuilt release targets. The cost is that cdktf get needs registry access and a minute or two on every clean checkout, and the generated tree is either committed (large, noisy diffs) or regenerated (slower CI).

Most teams end up mixed: prebuilt for the major clouds, generated for the one internal provider that manages their DNS appliance. That is fine. The import paths differ but the classes behave identically, because both come out of the same generator.

{
  "language": "python",
  "app": "pipenv run python main.py",
  "codeMakerOutput": "imports",
  "projectId": "bridged-aws",
  "terraformProviders": [
    "hashicorp/aws@~> 6.0",
    "acme/internal-dns@= 1.4.2"
  ],
  "terraformModules": []
}

The ~> operator allows patch and minor upgrades within a major version; = pins exactly. Use = for anything whose schema you do not want changing without a code review, and re-run cdktf get after every edit to this file — the bindings on disk do not update themselves, and a stale imports/ tree is one of the quietest ways to ship a surprise.

Where the Pulumi Bridge Differs

CDKTF maintains strict parity with Terraform CLI behavior and is optimal for teams requiring exact HCL equivalence with Python syntax. The toolchain preserves native state file formats and provider lifecycle hooks.

Pulumi uses its own provider bridge (pulumi-terraform-bridge) to wrap Terraform providers, but the wrapping happens at a completely different point in the lifecycle. Pulumi's bridge is compiled into the provider plugin: the maintainers run the bridge against a Terraform provider's Go source and ship the result as pulumi-aws, pulumi-gcp, or pulumi-cloudflare. You never run a generator. There is no synthesis step and no imports/ directory, and the Python package you install is a finished SDK.

The bridge also renames aggressively. Terraform's aws_s3_bucket surfaces as pulumi_aws.s3.BucketV2 with the type token aws:s3/bucketV2:BucketV2; snake_case arguments become camelCase properties on the wire, though the Python SDK still accepts snake_case keywords. Every output attribute is an Output[T] — an awaitable-like wrapper that carries dependency information. That is the same idea as a CDKTF token, but a real object with .apply() rather than a magic string. Because outputs are objects, a type checker can tell you that you are using an unresolved value where a plain str is required; CDKTF cannot, because a token is a str.

Translation details in CDKTF Architecture & Synthesis explain how schema resolution differs between the engines. Choose based on state portability requirements and existing CI/CD constraints: if the estate is already Terraform and the state must stay Terraform, CDKTF; if you are starting clean and want the shorter feedback loop, Pulumi.

# CLI: pulumi preview --stack dev
from typing import Optional
import pulumi
import pulumi_aws as aws

# pulumi-aws is already a bridged provider—use it directly with typed outputs
def create_bridged_resource(
    vpc_id: pulumi.Output[str],
    cidr_block: str = "10.0.1.0/24",
    opts: Optional[pulumi.ResourceOptions] = None,
) -> aws.ec2.Subnet:
    """Create a subnet referencing a VPC output—demonstrates Output dependency chaining."""
    # State implication: passing the Output (not a string) records the dependency
    # in the Pulumi checkpoint, so the subnet is created after the VPC.
    return aws.ec2.Subnet(
        "bridged-subnet",
        vpc_id=vpc_id,
        cidr_block=cidr_block,
        opts=opts,
    )

vpc = aws.ec2.Vpc("main-vpc", cidr_block="10.0.0.0/16")
subnet = create_bridged_resource(vpc_id=vpc.id)

# Provider note: .apply() is the only safe way to read a computed value; the
# lambda runs after the provider returns, never during program construction.
pulumi.export("subnet_cidr", subnet.cidr_block.apply(lambda c: c.upper()))

Pulumi Terraform Bridge Setup & Type Mapping

Pulumi's bridge wraps Terraform providers as Pulumi packages. These providers expose Output[T]-typed attributes and integrate with Pulumi's state engine directly—no synthesis step required. The bridge is used by Pulumi internally to generate packages like pulumi-aws, pulumi-gcp, and pulumi-azure-native.

The practical mapping rules are short and worth memorising. A Terraform required attribute becomes a keyword argument with no default; optional becomes a keyword defaulting to None; computed becomes an output-only property that the SDK will not let you set. A Terraform block declared with MaxItems: 1 collapses into a single nested Args class rather than a list, which is why the versioning configuration on a bucket takes one Args object and not a one-element list. Providers that are not bridged — pulumi-azure-native is generated from Azure's own API specifications, and pulumi-kubernetes from the Kubernetes OpenAPI schema — do not follow these rules at all, which is a common source of confusion when moving between packages in the same program.

Step-by-Step: Bridging a Provider into a Typed Stack

Provider configuration requires explicit version pinning and dependency resolution. The cdktf.json manifest dictates synthesis behavior. Python dependencies must align with the generated provider bindings.

1. Initialize the project and pin the provider

# CLI: scaffold a Python CDKTF project and install the toolchain
cdktf init --template="python" --local
pip install -r requirements.txt

Edit cdktf.json so terraformProviders names the exact constraint you intend to run, then generate. If you are using a prebuilt package instead, pip install "cdktf-cdktf-provider-aws==21.*" and skip cdktf get — but do not do both for the same provider, because two copies of the same classes in one process produce jsii type-identity errors whose tracebacks explain nothing.

# CLI: generate (or refresh) the bindings after any change to cdktf.json
cdktf get

2. Declare the provider and the stack

The provider class is the entry point for every bridged resource. Configure it once per stack; resources inherit it unless they are explicitly routed to an alias.

# CLI: cdktf synth
from typing import TypedDict, Optional
from constructs import Construct
from cdktf import App, TerraformStack
from cdktf_cdktf_provider_aws.provider import AwsProvider

class AWSProviderConfig(TypedDict, total=False):
    region: str
    profile: Optional[str]
    alias: Optional[str]

class BridgedStack(TerraformStack):
    def __init__(self, scope: Construct, ns: str, config: AWSProviderConfig) -> None:
        super().__init__(scope, ns)

        # Provider note: exactly one AwsProvider may omit `alias` per stack; a
        # second unaliased provider fails validation with "Duplicate provider
        # configuration".
        AwsProvider(
            self,
            "aws",
            region=config.get("region", "us-east-1"),
            profile=config.get("profile"),
            alias=config.get("alias"),
        )

def main() -> None:
    app = App()
    stack_config: AWSProviderConfig = {
        "region": "us-east-1",
        "alias": "primary",
    }
    BridgedStack(app, "bridged-aws-stack", stack_config)
    app.synth()

if __name__ == "__main__":
    main()

3. Add resources, and use the escape hatch when the schema wins

Most of the time the generated class covers what you need. Occasionally it does not: a lifecycle meta-argument, a provisioner, or an argument the generator typed as Any. CDKTF exposes add_override for exactly this — it writes raw keys into the synthesized JSON for that one resource, bypassing the typed surface without abandoning it everywhere else.

# CLI: cdktf synth && python -m json.tool cdktf.out/stacks/bridged-aws-stack/cdk.tf.json
from cdktf import TerraformStack
from cdktf_cdktf_provider_aws.s3_bucket import S3Bucket

def add_protected_bucket(stack: TerraformStack, name: str) -> S3Bucket:
    bucket = S3Bucket(stack, "data", bucket=name, force_destroy=False)
    # State implication: prevent_destroy makes any plan that would delete this
    # bucket fail rather than proceed — the apply aborts and state is untouched.
    bucket.add_override("lifecycle", {"prevent_destroy": True})
    # Provider note: override_logical_id fixes the address used by terraform
    # import; change it after an import and the resource is orphaned in state.
    bucket.override_logical_id("data")
    return bucket

4. Synthesize and read the JSON

Synthesis is where bridging is proved. The output directory contains a plain Terraform configuration, and reading it is the fastest way to confirm that your Python said what you meant.

# CLI: synthesize and inspect the emitted provider and resource blocks
cdktf synth
python -m json.tool cdktf.out/stacks/bridged-aws-stack/cdk.tf.json | head -40
cdktf diff --stack bridged-aws-stack

State Management & Security Boundaries

Backend Isolation & Drift Detection

Remote state backends require strict workspace isolation. Mixing environments in a single state file causes resource collisions. Lock acquisition prevents concurrent synthesis corruption.

Bridging changes nothing about how state works — that is the point — but it does change how easy it is to write a stack that spans more environments than you intended. A Python loop over a list of regions produces resources in one state file just as readily as one region does, and the blast radius grows without anyone reviewing a new directory. Decide the state boundary first, then write the loop inside it.

# CLI: validate the synthesized configuration before touching remote state
cdktf synth
terraform -chdir=cdktf.out/stacks/bridged-aws-stack init -backend=false
terraform -chdir=cdktf.out/stacks/bridged-aws-stack validate

# CLI: python -m ci.state_backend_validator
from typing import Optional
import boto3
from botocore.exceptions import ClientError

class StateBackendValidator:
    def __init__(self, bucket: str, region: str, workspace: str) -> None:
        self.bucket = bucket
        self.region = region
        self.workspace = workspace
        self.s3 = boto3.client("s3", region_name=region)

    def verify_connectivity(self) -> bool:
        """Validates S3 backend accessibility."""
        # State implication: head_bucket is read-only; it never creates or
        # mutates the state object.
        try:
            self.s3.head_bucket(Bucket=self.bucket)
            return True
        except ClientError as e:
            error_code = e.response["Error"]["Code"]
            if error_code == "404":
                raise RuntimeError(f"State bucket {self.bucket} does not exist")
            if error_code in ("403", "NoSuchBucket"):
                raise RuntimeError(f"State backend access denied: {e}")
            raise RuntimeError(f"State backend validation failed: {e}") from e

Credential Scoping & Secret Injection

Hardcoded credentials violate infrastructure security baselines. Python modules must consume runtime environment variables or assume IAM roles dynamically. Least-privilege boundaries prevent lateral movement during synthesis.

There is a bridging-specific wrinkle here that is easy to exploit. cdktf get and cdktf synth need no cloud credentials at all — schema generation talks to the registry, and synthesis is pure code generation. Only cdktf deploy, and cdktf diff because it runs a plan, authenticate against a cloud. Splitting the CI job along that line means generation and synthesis run in a stage that holds no cloud identity whatsoever, and only the final gated stage assumes a role.

Module isolation patterns covered in Python Constructs & Modules enforce credential scoping. Use environment injection for CI/CD runners. Rotate provider tokens automatically via secret managers, and never pass a secret as a provider argument that ends up in the synthesized JSON — cdk.tf.json is a build artifact and is routinely uploaded, cached, or attached to a pull request.

Verification

Unit Testing Constructs with pytest

Unit tests validate provider schema compliance without provisioning resources. Mocking the synthesis context isolates Python logic from cloud APIs.

The assertion that matters most for bridging is not "did the resource get created" but "did the right provider block, with the right arguments and the right version pin, appear in the synthesized JSON". cdktf.Testing gives you that JSON without a cloud account, which makes the check cheap enough to run on every commit.

# CLI: pytest tests/test_bridged_stack.py -q
from typing import Dict, Any
import json
import pytest
from cdktf import App, Testing
from my_stack import BridgedStack, AWSProviderConfig

@pytest.fixture
def test_app() -> App:
    return Testing.app()

def test_provider_present_in_synthesis(test_app: App) -> None:
    """Assert AWS provider appears in synthesized JSON with correct region."""
    config: AWSProviderConfig = {"region": "eu-west-1"}
    stack = BridgedStack(test_app, "test-stack", config)
    synthesized: Dict[str, Any] = json.loads(Testing.synth(stack))

    providers = synthesized.get("provider", {})
    assert "aws" in providers, "AWS provider must appear in synthesized output"
    aws_provider = providers["aws"]
    # Provider may be a list or single dict depending on CDKTF version
    if isinstance(aws_provider, list):
        assert any(p.get("region") == "eu-west-1" for p in aws_provider)
    else:
        assert aws_provider.get("region") == "eu-west-1"

def test_required_provider_version_is_pinned(test_app: App) -> None:
    """The bridged provider constraint must reach the synthesized JSON."""
    stack = BridgedStack(test_app, "pin-stack", {"region": "us-east-1"})
    synthesized: Dict[str, Any] = json.loads(Testing.synth(stack))
    required = synthesized["terraform"]["required_providers"]["aws"]
    assert required["source"] == "hashicorp/aws"
    assert required["version"].startswith("~> 6."), required["version"]

Synthetic Plan Validation & Gatekeeping

Pre-flight checks block unsafe merges. cdktf diff compares synthesized JSON against live state. Automated drift remediation requires strict pipeline gating.

# CLI: execute synthetic plan validation before merge
cdktf synth
terraform -chdir=cdktf.out/stacks/bridged-aws-stack init
terraform -chdir=cdktf.out/stacks/bridged-aws-stack plan -json > plan_output.json
python ci/validate_plan.py plan_output.json

A useful gate does more than check an exit code. Parse the JSON plan stream, count delete and replace actions by resource type, and fail the job when a destructive change touches a protected type without an approval label on the pull request. Migration paths outlined in Converting existing Terraform HCL to CDKTF Python provide structured gatekeeping templates you can reuse directly.

Troubleshooting

ModuleNotFoundError: No module named 'cdktf_cdktf_provider_aws' — the prebuilt package is not installed in the interpreter CDKTF is invoking. Check the app command in cdktf.json: if it says pipenv run python main.py but you installed into a plain virtualenv, the import happens in a different environment than the one you tested by hand.

ModuleNotFoundError: No module named 'imports.aws' — you are using locally generated bindings and have not run cdktf get, or codeMakerOutput points somewhere other than imports. Regenerate and confirm the directory exists before debugging anything else.

TypeError: S3Bucket.__init__() got an unexpected keyword argument 'versioning' — the argument was removed from the resource schema by a provider major release. The AWS provider's v4 split moved versioning, ACL, logging, and server-side encryption out of aws_s3_bucket into standalone resources. Fix the code, not the pin; reverting the pin only defers the break to the next upgrade window.

Error: Failed to query available provider packages: ... no available releases match the given constraints — the constraint in cdktf.json names a version range that does not exist in the registry. Check published versions before widening or bumping a pin.

Error: Duplicate provider configuration ... A default provider configuration for "aws" is already present — two provider objects were instantiated without an alias. Give every provider after the first an alias and route resources explicitly, as described in using multiple Terraform providers in one CDKTF stack.

Error: spawn node ENOENT — the jsii kernel could not start because Node is missing from the PATH of the process running Python. This is the classic CI failure when a Python-only base image is used for a CDKTF job.

A jsii assembly-load error naming two different cdktf versions — the prebuilt provider package expects a runtime range that your installed cdktf falls outside of. Move them together; the pair is a single compatibility unit, not two independent dependencies.

Common Implementation Pitfalls

• Ignoring provider version constraints: Omitting version pins in cdktf.json triggers silent schema drift and synthesis failures.
• Hardcoding cloud credentials: Embedding secrets in Python files bypasses CI/CD secret managers and violates runtime injection standards.
• Skipping synthetic plan validation: Bypassing cdktf diff or pulumi preview merges untested state mutations into production branches.
• Mixing state backends across environments: Failing to isolate workspaces causes resource collisions, orphaned infrastructure, and lock contention.
• Omitting Python 3.9+ type hints: Removing TypedDict and explicit annotations degrades IDE autocomplete, static analysis, and runtime safety.
• Branching on a computed attribute: Comparing resource.arn or resource.id in Python compares a synthesis token, so the branch is decided by a placeholder string rather than the real value.
• Installing a prebuilt provider and running cdktf get for the same provider: two copies of the same classes load into one jsii kernel and type-identity checks fail in ways the traceback does not explain.

Key Takeaways

Provider bridging is the mechanism that lets Python engineers access the full Terraform provider ecosystem through typed Python classes. The key discipline is keeping cdktf.json provider pins current, running cdktf get after any version change, and validating the synthesized JSON against terraform validate before deployment. These three habits eliminate the majority of bridging failures.

FAQ

How do I handle Terraform provider version conflicts when bridging to Python IaC?

Pin exact provider versions in cdktf.json using the terraformProviders field (for example "hashicorp/aws@~> 6.0"), and pin the matching Python package in your lockfile with pip-tools or Poetry. Treat the CDKTF runtime and any prebuilt provider package as one upgrade unit — bumping either alone is the usual cause of assembly-load errors. Run cdktf get and cdktf synth after every change to validate schema compatibility before deployment.

Why does my generated class have a capital A at the end of its name?

jsii appends A when a generated class name would collide with another symbol in the same namespace, which is why the versioning resource is S3BucketVersioningA. The suffix has nothing to do with provider versions, aliases, or API generations. Open the generated module — or the prebuilt package — and read the exported names rather than guessing at the import path.

Can CDKTF and Pulumi share the same Terraform state backend?

Not directly. CDKTF writes Terraform-format state, while Pulumi keeps its own checkpoint format, so a single file cannot serve both. If you need to move an estate between them, export the resources and import them into the other tool; pointing both at the same objects without importing produces two engines that each believe they own the resource.

What is the recommended approach for testing bridged providers locally?

Use cdktf.Testing.synth() with pytest to assert against the synthesized JSON — provider blocks, required-provider pins, resource arguments — with no cloud API calls. For Pulumi providers, use pulumi.runtime.set_mocks() to intercept resource registration and return canned outputs. Both approaches run without cloud credentials, which means they are safe to run on every commit and in a pull-request pipeline.

Do I need cloud credentials to run cdktf get or cdktf synth?

No. cdktf get talks to the Terraform registry to fetch provider schemas, and cdktf synth is pure code generation against those schemas. Only cdktf diff and cdktf deploy authenticate to a cloud, which lets you run generation and synthesis in a CI stage that holds no cloud identity at all.

How do I enforce Python 3.9+ typing in bridged provider configurations?

Model provider and stack arguments with typing.TypedDict, frozen dataclasses, or Pydantic models rather than loose dictionaries, and run mypy --strict or pyright in CI. Pay particular attention to schema fields the generator typed as Any — those are exactly the arguments a type checker cannot help with, so validate them yourself before passing them into the construct.

Related

• Converting Existing Terraform HCL to CDKTF Python — migrate legacy HCL into bridged Python constructs while preserving state.
• Using Multiple Terraform Providers in One CDKTF Stack — provider aliases for multi-region and multi-account deployments in a single stack.
• State Backend Configuration for CDKTF — how bridged provider outputs flow through remote state.
• CDKTF Workflows & Terraform Synthesis — the parent workflow tying bridging to the synthesis pipeline.