aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(infra): support Terraform as an alternative to CDK for deployments
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Component
CDK / infrastructure, bootstrap, deploy docs, CI deploy path
## Describe the feature
Today ABCA is a **CDK-only** deployable application (`cdk/` stacks, Blueprint constructs, least-privilege bootstrap template, `mise //cdk:*` tasks). Operators who standardize on **Terraform** cannot adopt the platform without introducing CDK into their org, or manually reverse-engineering the CloudFormation output.
Add a supported path to provision and update ABCA with Terraform **in addition to** CDK — not as a replacement of the CDK source of truth in the near term.
## Use case
- Enterprises with Terraform as the mandated IaC tool cannot run ABCA without an exception for CDK.
- Partners and sample consumers often want HCL modules they can compose with existing landing zones, state backends, and policy-as-code gates (OPA/Sentinel), rather than a TypeScript CDK app.
- Separating “platform deploy” from “application/runtime updates” (see related RFCs) is easier to express for some operators as Terraform modules + a thinner runtime update path.
## Context
- Architecture explicitly positions ABCA as a **deployable CDK application / reference architecture**, not a published construct library ([ARCHITECTURE.md](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/design/ARCHITECTURE.md)).
- Deploy topology, bootstrap policies, Blueprint → `RepoConfig` DynamoDB writes, and compute-variant IAM (`ComputeTypes=agentcore,ecs`) are all CDK-centric today (`cdk/src/`, `cdk/bootstrap/`).
- Related: [#377](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/issues/377) (separate infra deploy from app/runtime updates), [#120](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/issues/120) (least-privilege bootstrap), [#73](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/issues/73) (GHA deploy gates).
## Proposed solution
Treat this as an **RFC first**, then implement incrementally:
1. **Parity inventory** — Enumerate CDK stacks/constructs, custom resources, Blueprint semantics, bootstrap policies, and deploy-time DynamoDB/SSM side effects that Terraform must reproduce.
2. **Source-of-truth decision (ADR)** — Choose one of:
- **A.** CDK remains canonical; publish a **generated or hand-maintained Terraform module** that mirrors the deployed resource graph (accept drift risk + dual-maintain cost).
- **B.** Extract a shared intermediate (e.g. CloudFormation templates / CDK8s-style assets) consumed by both CDK and Terraform.
- **C.** Terraform becomes a second first-class tree under e.g. `terraform/` with explicit parity tests against CDK synth/deploy.
3. **MVP module scope** — Core control plane (API, orchestrator, DynamoDB, Cognito/auth, secrets wiring, AgentCore default compute) with documented gaps vs full CDK app (ECS compute variant, optional adapters, observability extras).
4. **Operator UX** — Document `terraform init/plan/apply`, required providers/versions, state backend expectations, and how Blueprint/repo onboarding works without the CDK `Blueprint` construct (variables → `RepoConfig` writer, or a small companion CLI/Lambda).
5. **CI guardrails** — Parity checks (resource inventory diff, policy equivalence, or deploy-smoke against both paths) so the two IaC surfaces do not silently diverge.
## Acceptance criteria
- [ ] ADR records the IaC dual-support decision (canonical source, drift policy).
- [ ] Operators can provision a working ABCA control plane with Terraform sufficient to submit a task and open a PR (AgentCore path at minimum).
- [ ] Docs cover install, upgrade, teardown, and known gaps vs the CDK app.
- [ ] Bootstrap / least-privilege story is documented for the Terraform path (even if initially coarser than CDK bootstrap policies).
- [ ] CI or documented checklist prevents unbounded drift between CDK and Terraform for the MVP surface.
- [ ] CDK path remains fully supported; Terraform is additive.
## Out of scope (initially)
- Rewriting the Python agent or orchestrator business logic.
- Feature-complete parity with every optional CDK construct on day one (ECS compute, every adapter, full observability suite) — track follow-ups.
- Publishing to the Terraform Registry (nice-to-have after MVP stability).
- Supporting other IaC tools beyond what falls out of the chosen approach.
## Tests
- Terraform`validate` + plan fixtures in CI for the MVP module.
- Optional: integ smoke (deploy → health → tear down) gated like existing CDK integ work.
- Docs/sidebar updates via the normal `mise //docs:sync` path when guides change.
Contributor guide
Research direction
Begin with docs/design/ARCHITECTURE.md, then inventory cdk/src/ and cdk/bootstrap/ along with the existing CDK integration work. Record the source-of-truth decision in an ADR, define the MVP Terraform surface and known gaps, and add Terraform validate/plan fixtures or documented parity checks. The issue is complete when the acceptance criteria for provisioning, documentation, bootstrap, and drift control are met.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, terraform, typescript
- Domain
- cloud, devops, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100