aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

feat(infra): support Terraform as an alternative to CDK for deployments

Aperta
#644 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement infra-cdk P2 RFC-proposal
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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.