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

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

Open
#644 0 comments 0 reactions 0 assignees View on GitHub
enhancement infra-cdk P2 RFC-proposal
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.