ADR-0004: Terraform for the platform foundation, CDK for workload golden paths

Status: Accepted (worked example)
Date: 2026-10-23
Deciders: Platform team, developer-experience representatives from four product teams

Context and Problem Statement

The platform team builds the foundation (accounts, networking, guardrails) and wants to give product teams golden paths: supported building blocks for common workloads. The platform team’s background is mostly operations and Terraform. Product teams are mostly TypeScript developers. Building blocks will change for years, so there has to be a way to release new versions and retire old ones without breaking teams.

Which IaC tools should we support, and how should golden-path modules be versioned and retired?

Decision Drivers

Self-service: product teams can build standard workloads in the language they already use.
Evolvability: building blocks can change without breaking consumers; old versions can be retired.
Security and auditability: every resource is created through IaC and checked by policy as code.
Fit with team skills (platform: Terraform; product teams: TypeScript).
The cost of supporting more than one tool.

Considered Options

Terraform everywhere (platform and workloads).
AWS CDK everywhere (TypeScript).
Split: Terraform for the platform foundation, CDK for workload golden paths.
CloudFormation templates (YAML) everywhere.

Decision Outcome

Chosen option: 3, the split by layer, because the platform layers have different owners, skills, and rates of change. The foundation changes rarely and is owned by the Terraform-skilled platform team. Golden paths change often and are consumed by TypeScript developers, for whom CDK’s constructs and normal code (loops, conditions, reuse) are a natural fit.

Golden-path rules:

Golden paths are published as a versioned CDK construct library with semantic versioning and a changelog.
Breaking changes use expand and contract: release the new major version, help teams migrate, then retire the old one.
Support policy: the current and previous major versions are supported; a deprecated version is retired six months after its replacement ships.
Teams can leave the golden path with a recorded reason (a short ADR in their own repo). It’s a path, not a cage.

Consequences

Good: Each group works in the tool it knows; golden paths feel like ordinary libraries to developers.
Good: CDK synthesises to CloudFormation, so workload stacks get CloudFormation’s rollback and drift detection.
Bad: Two tools, two sets of expertise, and two sets of policy checks to maintain.
Bad: Values passed from the Terraform foundation to CDK stacks (VPC IDs, subnets, bus ARNs) need a clear interface, for example SSM parameters published by the foundation.
Bad: Version support needs active work: tracking adoption, migration help, deprecation notices.

Confirmation

At least 90% of workloads are on a supported major version of the construct library (dependency scan across repos).
cdk-nag runs in every workload pipeline; Checkov or OPA checks run on every Terraform plan.
Every resource carries an IaC-managed tag; untagged resources (likely created in the console) are reported by AWS Config.
Foundation-to-workload values are read only through the published SSM parameters, never hard-coded (code search in CI).
Number and age of teams off the golden path, reviewed quarterly.

Pros and Cons of the Options

1. Terraform everywhere

Good: One tool, one policy toolchain; multi-cloud capable; matches the platform team’s skills.
Good: Control Tower’s Account Factory for Terraform (AFT) fits the foundation.
Bad: HCL is less natural for application developers; reusable abstractions are more limited than in a general-purpose language.

2. CDK everywhere

Good: One tool; strong abstractions; good developer experience.
Bad: Doesn’t match the platform team’s skills; AWS-only.

3. Split by layer

Good: Matches skills and rates of change per layer.
Bad: Two toolchains; an interface between layers to maintain.

4. CloudFormation templates

Good: Native, declarative, auditable, with built-in rollback and drift detection.
Bad: Verbose; limited reuse; poor developer experience for complex golden paths.

More Information

Revisit when:

maintaining two toolchains costs the platform team more than about 20% of its time;
golden-path adoption falls below 70% of new workloads;
the organisation adopts a second cloud provider (favouring Terraform more widely).

Sources: AWS Prescriptive Guidance, Choosing an IaC tool and Getting started with Terraform: FAQ (CDK synthesises to CloudFormation); AWS Prescriptive Guidance, Infrastructure as code (strengths of CloudFormation and CDK).