Apache-2.0built on CDK TerrainTerraform + OpenTofu

Infrastructure as data
is not the same as code.

TerraConstructs is an open-source L2 construct library for Terraform and OpenTofu. It gives you the AWS CDK programming model — the asset pipeline, the IAM grant SDK, Step Functions ASL — on top of the providers and state you already run.

Take the guided tour terraconstructs/base AWS workshop

26: lines of TypeScript
230: lines of HCL, synthesized
0: IAM statements hand-written

The actual distinction

It was never declarative versus imperative.

HCL and a CDK program are both declarative. Both describe a desired end state; both hand that description to an engine that figures out how to get there. A for loop that builds a list of subnets is no less declarative than a for_each that does the same thing.

The real split is how infrastructure is modelled: as a document to be merged, looked up and templated — or as typed objects with behaviour.

A Terraform module's interface is exactly its variables and outputs — it's a document, not a type. Two resources can't hand each other permission to talk; something has to sit outside both and wire up the rule.
In an object-oriented model, that wiring is the object graph. A construct that implements a capability interface — TerraConstructs’ port of AWS CDK’s IConnectable, IGrantable and IPrincipal — can be handed to any other construct's connection or grant method, regardless of what either one actually is underneath.
That's polymorphism, and a document has no place to put it.

declarative vs. imperative→document-oriented vs. object-oriented

Aspect

Document

Object

The unit
A module — a directory of files.
A construct — a class you can instantiate.
Its interface
Exactly its variables and outputs. A shape, checked late.
A TypeScript type. Checked before you ever run a plan.
Composition
Nest a module, then re-declare every variable you want to pass through.
Pass the object. It carries its own behaviour with it.
Reuse
Copy the block, change the strings. Or a for_each and a lookup map.
Subclass it, or wrap it in a construct that means something to your team.
Cross-cutting concerns
Something outside both resources must know about both and wire the rule.
One asks the other for a grant. Neither needs to know what the other is.
Where logic lives
In the templating layer: locals, ternaries, try(), merge(), jsonencode().
In methods, on the object that owns the invariant.

Guided tour

Read the input. Then read what it became.

Nothing here is a mock-up. The HCL on the right is the real synthesized output of the TypeScript on the left, pre-compiled at build time. Step through it and watch which lines each construct is responsible for.

Workshop — Lambda + API Gateway

L2 constructs, the asset pipeline, and the IAM wiring the framework derives for you.

Input · TypeScriptobjects

src/main.ts26 lines

1import { Construct } from "constructs";
2import { AwsStack, AwsStackProps } from "terraconstructs/lib/aws";
3import {
4  Code,
5  LambdaFunction,
6  Runtime,
7  LambdaRestApi,
8} from "terraconstructs/lib/aws/compute";
9
10export class CdkWorkshopStack extends AwsStack {
11  constructor(scope: Construct, id: string, props: AwsStackProps) {
12    super(scope, id, props);
13
14    const hello = new LambdaFunction(this, "HelloHandler", {
15      runtime: Runtime.NODEJS_22_X,
16      code: Code.fromAsset("lambda"),
17      handler: "hello.handler",
18    });
19
20    new LambdaRestApi(this, "Endpoint", {
21      handler: hello,
22      registerOutputs: true,
23      cloudWatchRole: false,
24    });
25  }
26}

Output · HCL230 lines synthesized

cdktn.out/stacks/workshop/cdk.tf.hcl230 lines

1terraform {
2  required_providers {
3    aws = {
4      version = "5.100.0"
5      source  = "aws"
6    }
7  }
8}
9
10provider "aws" {
11  region = "us-east-1"
12}
13
14data "aws_caller_identity" "CallerIdentity" {
15  provider = "aws"
16}
17data "aws_partition" "Partitition" {
18  provider = "aws"
19}
20data "aws_iam_policy_document" "HelloHandler_ServiceRole_AssumeRolePolicy_7561E865" {
21  statement {
22    actions = [
23      "sts:AssumeRole",
24    ]
25    effect = "Allow"
26    principals = [
27      {
28        identifiers = [
29          "${data.aws_service_principal.aws_svcp_default_region_lambda.name}",
30        ]
31        type = "Service"
32      },
33    ]
34  }
35}
36resource "aws_iam_role" "HelloHandler_ServiceRole_11EF7C63" {
37  assume_role_policy = data.aws_iam_policy_document.HelloHandler_ServiceRole_AssumeRolePolicy_7561E865.json
38  managed_policy_arns = [
39    "arn:${data.aws_partition.Partitition.partition}:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
40  ]
41  name_prefix = "demo-uuid-HelloHandlerServiceRole"
42  tags = {
43    "grid:EnvironmentName" = "demo"
44    "grid:UUID"            = "demo-uuid"
45    Name                   = "demo-HelloHandler"
46  }
47}
48data "aws_iam_policy_document" "HelloHandler_ServiceRole_DefaultPolicy_8633F352" {
49  statement {
50    actions = [
51      "xray:PutTraceSegments",
52      "xray:PutTelemetryRecords",
53    ]
54    effect = "Allow"
55    resources = [
56      "*",
57    ]
58  }
59}
60resource "aws_iam_role_policy" "HelloHandler_ServiceRole_DefaultPolicy_ResourceRoles0_5982DDFD" {
61  name   = "HelloHandlerServiceRoleDefaultPolicyB2AAA7FD"
62  policy = data.aws_iam_policy_document.HelloHandler_ServiceRole_DefaultPolicy_8633F352.json
63  role   = aws_iam_role.HelloHandler_ServiceRole_11EF7C63.name
64}
65resource "aws_cloudwatch_log_group" "HelloHandler_LogGroup_49850324" {
66  name              = "/aws/lambda/demo-uuid-HelloHandler"
67  retention_in_days = 7
68  tags = {
69    "grid:EnvironmentName" = "demo"
70    "grid:UUID"            = "demo-uuid"
71    Name                   = "demo-HelloHandler"
72  }
73}
74resource "aws_lambda_function" "HelloHandler_2E4FBA4D" {
75  architectures = [
76    "x86_64"
77  ]
78  function_name = "demo-uuid-HelloHandler"
79  handler       = "hello.handler"
80  memory_size   = 128
81  role          = aws_iam_role.HelloHandler_ServiceRole_11EF7C63.arn
82  runtime       = "nodejs22.x"
83  s3_bucket     = aws_s3_bucket.AssetBucket.bucket
84  s3_key        = aws_s3_object.FileAsset_S3.key
85  tags = {
86    "grid:EnvironmentName" = "demo"
87    "grid:UUID"            = "demo-uuid"
88    Name                   = "demo-HelloHandler"
89  }
90  timeout = 3
91  environment {
92    variables = {
93
94    }
95  }
96  tracing_config {
97    mode = "Active"
98  }
99  depends_on = [
100    "aws_cloudwatch_log_group.HelloHandler_LogGroup_49850324",
101    "data.aws_iam_policy_document.HelloHandler_ServiceRole_AssumeRolePolicy_7561E865",
102    "aws_iam_role.HelloHandler_ServiceRole_11EF7C63",
103    "data.aws_iam_policy_document.HelloHandler_ServiceRole_DefaultPolicy_8633F352",
104    "data.aws_iam_policy_document.HelloHandler_ServiceRole_AssumeRolePolicy_7561E865",
105    "aws_iam_role.HelloHandler_ServiceRole_11EF7C63",
106    "data.aws_iam_policy_document.HelloHandler_ServiceRole_DefaultPolicy_8633F352",
107  ]
108}
109resource "aws_s3_bucket" "AssetBucket" {
110  bucket = "demo-uuid-${data.aws_caller_identity.CallerIdentity.account_id}-us-east-1"
111}
112resource "aws_s3_object" "FileAsset_S3" {
113  bucket      = aws_s3_bucket.AssetBucket.bucket
114  key         = "ac628f13c88c233682e5ac4270a6063b0f3ef8dc2a12061e9d762bad947a292e.zip"
115  source      = "assets/FileAsset/ac628f13c88c233682e5ac4270a6063b0f3ef8dc2a12061e9d762bad947a292e/archive.zip"
116  source_hash = "ac628f13c88c233682e5ac4270a6063b0f3ef8dc2a12061e9d762bad947a292e"
117}
118resource "aws_api_gateway_rest_api" "Endpoint_EEF1FD8F" {
119  name = "Endpoint"
120  policy = {
121    isBlock          = false
122    type             = "simple"
123    storageClassType = "string"
124  }
125  tags = {
126    "grid:EnvironmentName" = "demo"
127    "grid:UUID"            = "demo-uuid"
128    Name                   = "demo-Endpoint"
129  }
130}
131resource "aws_api_gateway_deployment" "Endpoint_Deployment_318525DA" {
132  description = "Automatically created by the RestApi construct"
133  rest_api_id = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id
134  depends_on = [
135    "aws_api_gateway_resource.Endpoint_proxy_39E2174E",
136    "aws_api_gateway_method.Endpoint_ANY_485C938B",
137    "aws_api_gateway_method.Endpoint_proxy_ANY_C09721C5",
138    "aws_api_gateway_resource.Endpoint_proxy_39E2174E",
139    "aws_api_gateway_method.Endpoint_ANY_485C938B",
140    "aws_api_gateway_method.Endpoint_proxy_ANY_C09721C5",
141    "aws_api_gateway_integration.Endpoint_proxy_ANY_Integration_3EA10C81",
142    "aws_api_gateway_integration.Endpoint_ANY_Integration_21F74837",
143  ]
144  lifecycle {
145    create_before_destroy = true
146  }
147  triggers = {
148    redeployment = "21b9f7b3fb6c94640a9065f699fde4c6"
149  }
150}
151resource "aws_api_gateway_stage" "Endpoint_DeploymentStageprod_B78BEEA0" {
152  deployment_id = aws_api_gateway_deployment.Endpoint_Deployment_318525DA.id
153  rest_api_id   = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id
154  stage_name    = "prod"
155  tags = {
156    "grid:EnvironmentName" = "demo"
157    "grid:UUID"            = "demo-uuid"
158    Name                   = "demo-Endpoint"
159  }
160}
161resource "aws_api_gateway_resource" "Endpoint_proxy_39E2174E" {
162  parent_id   = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.root_resource_id
163  path_part   = "{proxy+}"
164  rest_api_id = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id
165}
166resource "aws_lambda_permission" "Endpoint_proxy_ANY_ApiPermissionEndpointANYproxy_5077F498" {
167  action        = "lambda:InvokeFunction"
168  function_name = aws_lambda_function.HelloHandler_2E4FBA4D.arn
169  principal     = "apigateway.amazonaws.com"
170  source_arn    = "arn:${data.aws_partition.Partitition.partition}:execute-api:us-east-1:${data.aws_caller_identity.CallerIdentity.account_id}:${aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id}/${aws_api_gateway_stage.Endpoint_DeploymentStageprod_B78BEEA0.stage_name}/*/*"
171}
172resource "aws_lambda_permission" "Endpoint_proxy_ANY_ApiPermissionTestEndpointANYproxy_53B9BBE7" {
173  action        = "lambda:InvokeFunction"
174  function_name = aws_lambda_function.HelloHandler_2E4FBA4D.arn
175  principal     = "apigateway.amazonaws.com"
176  source_arn    = "arn:${data.aws_partition.Partitition.partition}:execute-api:us-east-1:${data.aws_caller_identity.CallerIdentity.account_id}:${aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id}/test-invoke-stage/*/*"
177}
178resource "aws_api_gateway_method" "Endpoint_proxy_ANY_C09721C5" {
179  authorization = "NONE"
180  http_method   = "ANY"
181  resource_id   = aws_api_gateway_resource.Endpoint_proxy_39E2174E.id
182  rest_api_id   = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id
183}
184resource "aws_api_gateway_integration" "Endpoint_proxy_ANY_Integration_3EA10C81" {
185  http_method             = aws_api_gateway_method.Endpoint_proxy_ANY_C09721C5.http_method
186  integration_http_method = "POST"
187  resource_id             = aws_api_gateway_resource.Endpoint_proxy_39E2174E.id
188  rest_api_id             = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id
189  type                    = "AWS_PROXY"
190  uri                     = "arn:${data.aws_partition.Partitition.partition}:apigateway:us-east-1:lambda:path/2015-03-31/functions/${aws_lambda_function.HelloHandler_2E4FBA4D.arn}/invocations"
191}
192resource "aws_lambda_permission" "Endpoint_ANY_ApiPermissionEndpointANY_0F391E45" {
193  action        = "lambda:InvokeFunction"
194  function_name = aws_lambda_function.HelloHandler_2E4FBA4D.arn
195  principal     = "apigateway.amazonaws.com"
196  source_arn    = "arn:${data.aws_partition.Partitition.partition}:execute-api:us-east-1:${data.aws_caller_identity.CallerIdentity.account_id}:${aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id}/${aws_api_gateway_stage.Endpoint_DeploymentStageprod_B78BEEA0.stage_name}/*/"
197}
198resource "aws_lambda_permission" "Endpoint_ANY_ApiPermissionTestEndpointANY_A9F55FBA" {
199  action        = "lambda:InvokeFunction"
200  function_name = aws_lambda_function.HelloHandler_2E4FBA4D.arn
201  principal     = "apigateway.amazonaws.com"
202  source_arn    = "arn:${data.aws_partition.Partitition.partition}:execute-api:us-east-1:${data.aws_caller_identity.CallerIdentity.account_id}:${aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id}/test-invoke-stage/*/"
203}
204resource "aws_api_gateway_method" "Endpoint_ANY_485C938B" {
205  authorization = "NONE"
206  http_method   = "ANY"
207  resource_id   = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.root_resource_id
208  rest_api_id   = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id
209}
210resource "aws_api_gateway_integration" "Endpoint_ANY_Integration_21F74837" {
211  http_method             = aws_api_gateway_method.Endpoint_ANY_485C938B.http_method
212  integration_http_method = "POST"
213  resource_id             = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.root_resource_id
214  rest_api_id             = aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id
215  type                    = "AWS_PROXY"
216  uri                     = "arn:${data.aws_partition.Partitition.partition}:apigateway:us-east-1:lambda:path/2015-03-31/functions/${aws_lambda_function.HelloHandler_2E4FBA4D.arn}/invocations"
217}
218
219output "EndpointOutputs" {
220  value = {
221    restApiId             = "${aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id}"
222    restApiName           = "Endpoint"
223    restApiRootResourceId = "${aws_api_gateway_rest_api.Endpoint_EEF1FD8F.root_resource_id}"
224    url                   = "https://${aws_api_gateway_rest_api.Endpoint_EEF1FD8F.id}.execute-api.us-east-1.${data.aws_partition.Partitition.dns_suffix}/${aws_api_gateway_stage.Endpoint_DeploymentStageprod_B78BEEA0.stage_name}/"
225  }
226  description = "Outputs for demo-Endpoint"
227}
228data "aws_service_principal" "aws_svcp_default_region_lambda" {
229  service_name = "lambda"
230}

Both files above are real: 26 lines of TypeScript on the left, the 230 lines of HCL cdktn synth produced from them on the right. Highlighted regions are clickable, or step through them in order.

Where the object graph pays for itself

One call site. Whatever it takes underneath.

table.grantReadWriteData(target)

It accepts an IGrantable and asks it for a principal. What it takes to produce that principal is entirely the implementation’s business — sometimes one role, sometimes three chained resources, sometimes nothing at all.

src/main.ts

// whatever you construct here…
const target = new LambdaFunction(this, "Worker", { /* … */ })

// …this line never changes
table.grantReadWriteData(target)

synthesizes to2 addresses

cdk.tf.hcl

01
aws_iam_role.Worker_ServiceRolecreated lazily
execution role, materialized on first use — this is the identifier that crosses the interface
02
aws_iam_role_policy.Worker_ServiceRole_Defaultwired up
the statement this grant contributed

Note how little the call site knows. It never named a role, a profile, a security group or a rule — and for ArnPrincipal there was no resource to name at all. In a document model each of these is a separate wiring problem, solved outside both parties. Here it is one method, resolved by the graph.

What works today

Not a thin wrapper. The parts of CDK that were hard to build.

Anyone can generate HCL from a template. These are the subsystems that make the programming model actually feel different — each one ported and in use.

Ported in full

The AWS CDK asset pipeline

Code.fromAsset() and DockerImageAsset work the way you remember them — except the bundling, hashing, upload and lifecycle are handled by Terraform providers and Terraform state. Bundle a TypeScript Lambda handler and ship it via S3, or build and publish a container to ECR, without writing any of the glue.

code: Code.fromAsset("lambda")

Ported in full

The IAM grant SDK

IPrincipal, IGrantable and IGrant, implemented on top of terraform-provider-aws IAM resources. Cross-service policy is generated from the object graph: a queue can grant a function permission to consume it, and neither construct needs to know the other’s type.

table.grantReadWriteData(handler)

Ported in full

Step Functions ASL

Compose state machine fragments as objects instead of hand-editing a large JSON DSL. Because fragments are IGrantable-aware, the IAM actions each task needs bubble up and aggregate onto the state machine role automatically.

definition: submit.next(waitFor).next(publish)

Roadmap

Beyond AWS

The construct model is provider-agnostic; the current library covers the ported AWS CDK surface. L2 constructs for GCP and Azure are the next milestone — and the contribution path is open.

// terraconstructs/lib/gcp — in progress

The stack underneath

No new engine. No new state format. No new vendor.

The output is plain terraform-provider-aws — the same resource types your modules already declare. Nobody has to sign a new contract, stand up a new control plane, or learn to lint and operate CloudFormation.

Your platform team keeps the engine, the state, the providers and the entire toolchain they have been running for years. TerraConstructs sits above all of it and hands them HCL.

Your existing gates just work

Linters and SAST

tflint
Checkov
OPA / Conftest
Terrascan
Trivy
Sentinel

They read HCL and provider resources, which is exactly what synthesis emits. Every OPA bundle your security team has accumulated keeps evaluating the same resource addresses.

Automation and collaboration

Atlantis
Terraform Cloud
env0
Scalr
Spacelift
Terrateam
Digger

None of them need to know TerraConstructs exists. They see plain Terraform — or OpenTofu — and plan and apply it the way they always have.

And one thing you could not do before

Policy-as-code runs after the document exists: you emit HCL, then a scanner tells you it was wrong. Because there is now an object graph, platform teams get a hook that runs before synthesis.

// visit every node, before any HCL is written
Aspects.of(app).add(
  new EncryptionAtRest(),
  new RequireTagsAspect(taxonomy),
)

An Aspect visits every construct and can mutate it — turning on encryption, attaching a tag taxonomy, forcing a log retention floor. You stop failing builds for drift from a standard and start applying the standard.

Hardening becomes a library your teams inherit, not a wiki page they are audited against. And your scanners still run afterwards, unchanged, as the backstop.

Why this matters now

The cheapest tokens are the ones you never spend.

The constraint on adopting AI in 2026 is not access to frontier models — it is what they cost to run. Plenty of organisations spent an annual budget in six months and are now re-forecasting. So the question stops being “can an agent do this?” and becomes “how much iteration does this task require before it converges?”

An agent can absolutely author raw provider configuration for every resource. It will just have to validate its way there.

least-privilege IAM policy, authored by reading the module

0/11 found|~0 min CI

Policy written by enumerating what the module “obviously” needs.
Step through what a real deployment actually demanded.

Enumerated by hand or by agent

Every action, every resource ARN, every condition key — transcribed, then corrected against reality one denial at a time. Nothing about the policy states why any of it is there.

{
  "Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:DeleteObject",
    "s3:ListBucket",
    "kms:Decrypt",
    "kms:GenerateDataKey",
    /* … 25 more, some invalid, */
    /* one wildcard too broad  */
  ]
}

Derived from intent

The constructs already know they are encrypted, already know their own ARNs. The agent picks an intent; the library owns the transcription — and the KMS grant nobody remembered comes along with it.

const state = new Bucket(this, "TfMigrate", {
  encryption: BucketEncryption.KMS,
});
const config = new StringParameter(this, "Cfg", {
  secure: true,
});

state.grantReadWrite(deployRole);
config.grantRead(deployRole);

The loop is the line item

A model that cannot know an action exists has to discover it by failing. Every discovery is a full apply, a parsed error, a re-plan and a re-validate — context re-read from scratch each time. That is where the budget goes, and it buys knowledge thousands of teams have already paid for.

Intent-oriented, not resource-oriented

grantReadWrite is a decision. Thirty-one policy actions across four services is a transcription. Models are markedly more reliable choosing among a few well-typed intents than emitting hundreds of interdependent low-level fields, and a typed surface makes an invalid action a compile error rather than a silent no-op.

Deterministic and already tested

The constructs are end-to-end tested and synthesis is deterministic: the same program yields the same HCL, so an agent’s output is reviewable as a diff. The library carries the AWS trivia — which actions ignore resource scoping, which APIs tag on create — so nobody rediscovers it per repository.

Spend the context window on the problem nobody has solved yet — not on re-validating what every other infrastructure team has already re-validated, one denial at a time.

Open source, all the way down

There is no paid tier. There is a community.

TerraConstructs is Apache-2.0 with no commercial offering and no enterprise edition. If it is useful to you, the way to repay it is to ask good questions in public and send patches.

Infrastructure as data
is not the same as code.

It was never declarative versus imperative.

Read the input. Then read what it became.

One call site. Whatever it takes underneath.

Not a thin wrapper. The parts of CDK that were hard to build.

The AWS CDK asset pipeline

The IAM grant SDK

Step Functions ASL

Beyond AWS

No new engine. No new state format. No new vendor.

TerraConstructs

CDK Terrain (cdktn)

terraform-provider-aws

Terraform / OpenTofu

Your existing gates just work

And one thing you could not do before

The cheapest tokens are the ones you never spend.

The loop is the line item

Intent-oriented, not resource-oriented

Deterministic and already tested

There is no paid tier. There is a community.

Get help on cdk.dev

Work through the AWS workshop

Contribute a construct

Infrastructure as datais not the same as code.

It was never declarative versus imperative.

Read the input. Then read what it became.

One call site. Whatever it takes underneath.

Not a thin wrapper. The parts of CDK that were hard to build.

The AWS CDK asset pipeline

The IAM grant SDK

Step Functions ASL

Beyond AWS

No new engine. No new state format. No new vendor.

TerraConstructs

CDK Terrain (cdktn)

terraform-provider-aws

Terraform / OpenTofu

Your existing gates just work

And one thing you could not do before

The cheapest tokens are the ones you never spend.

The loop is the line item

Intent-oriented, not resource-oriented

Deterministic and already tested

There is no paid tier. There is a community.

Get help on cdk.dev

Work through the AWS workshop

Contribute a construct

Infrastructure as data
is not the same as code.