aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(infra): support Terraform as an alternative to CDK for deployments
- Lingua principale
- TypeScript
- Stelle
- 143
- Fork
- 46
- Merge medio
- 3g 9h
- PR unite (30g)
- 20
Descrizione
## 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.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia da docs/design/ARCHITECTURE.md, quindi fai l’inventario di cdk/src/ e cdk/bootstrap/ insieme al lavoro di integrazione CDK esistente. Registra in un ADR la decisione relativa alla fonte autorevole, definisci la superficie Terraform dell’MVP e le lacune note, quindi aggiungi fixture Terraform validate/plan o verifiche di parità documentate. L’issue è completata quando sono soddisfatti i criteri di accettazione per il provisioning, la documentazione, il bootstrap e il controllo del drift.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- aws, terraform, typescript
- Ambito
- cloud, devops, infrastructure
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Tranquilla
- Chiarezza
- Da chiarire
- Idoneità per principianti
- 30/100