ADR 0001 agent runtime compute

ADR-0001: Agent runtime compute — AWS CodeBuild

Status: Accepted (2026-07-22)

Context

The NWAF agent is an event-triggered batch job. A nightly schedule (11:00 PM) must spin up a runtime that:

• clones the target Git repository (Terraform HCL, main branch),
• downloads the workload's tfstate from S3,
• runs the terraform CLI (terraform show) and read-only AWS SDK calls,
• invokes Claude via Amazon Bedrock and a RAG store,
• writes findings back to the AWS Well-Architected Tool, and
• emits a report to S3 and SNS.

The runtime then terminates. It is a pipeline job, not a long-lived service: finite duration (minutes to ~1 h), no inbound traffic, one invocation per night per workload.

We need to choose the compute platform that runs this job.

Decision drivers

• Native fit for ephemeral, triggered batch (no always-on cost).
• Git clone and terraform CLI are first-class needs, not incidental.
• Minimise undifferentiated setup and the number of components/IAM surfaces.
• Duration headroom well beyond Lambda's 15-minute ceiling.
• Native artifact + log handling for the "save summary to logs" flow.
• A clear, recognisable pattern a reviewer can trust.

Decision

The agent runs as an AWS CodeBuild project. The build environment is a custom container image (from ECR) with the Strands Agents SDK and the terraform CLI pre-installed. Amazon EventBridge Scheduler targets StartBuild directly — no orchestrator Lambda. The agent lifecycle is expressed as buildspec.yml phases (install → context hydration → agent analyze → deliver). The Git repository is the CodeBuild source (cloned natively); logs stream to CloudWatch and the report is written to S3 as a build artifact.

Consequences

• A component is removed. EventBridge → CodeBuild is a native integration, so the orchestrator Lambda in the original design is deleted — one fewer runtime and one fewer IAM role to govern.
• Git clone becomes configuration, not code — the CodeBuild source provider handles it; the context-hydration step largely disappears.
• buildspec phases mirror the agent lifecycle, giving a declarative, reviewable execution contract.
• Logs and artifacts are native (CloudWatch + S3), satisfying the reporting and audit flows without extra wiring.
• No VPC required. Agent 1 reads control-plane config (Describe*), not data-plane resources, so the build runs outside a VPC and avoids ENI cold-start latency. (If future data-plane probing is added, CodeBuild-in-VPC is available — see revisit trigger.)
• 8-hour timeout provides ample headroom over the expected runtime.
• Off-label optics. CodeBuild is branded as CI/CD compute; running an agent on it is a widely-used but non-obvious pattern. Mitigated by documenting it here and by the fact that terraform-in-CodeBuild is itself idiomatic.
• Coarser sizing. CodeBuild offers fixed compute classes (S/M/L/2XL) rather than Fargate's fine-grained vCPU/memory. Acceptable for a single-container job.

Alternatives considered

Option	Verdict	Why
AWS CodeBuild	Chosen	Native git clone + terraform home; EventBridge→StartBuild removes the Lambda; native logs/artifacts; 8 h timeout; no VPC needed.
Amazon ECS on Fargate	Rejected (now)	General-purpose and finer sizing, but requires cluster + task definition + exec/task roles + networking, a Lambda/Step Functions to RunTask, and hand-rolled git clone and artifact handling — more moving parts for a nightly batch. Remains the fallback for large parallel fan-out (see below).
AWS Lambda	Rejected	15-minute execution ceiling cannot cover a multi-agent RAG review; unsuitable regardless of the 10 GB image support.
Amazon EKS	Rejected	Operating a Kubernetes cluster for a once-nightly batch is disproportionate cost and complexity.

Revisit trigger

Move to ECS Fargate if any of these become true:

• Parallel fan-out across many workloads/accounts exceeds the CodeBuild concurrent-build service quota (raising the quota is a stopgap; Fargate scales more naturally beyond it).
• The agent needs fine CPU/memory tuning or a long-running / service mode.
• Data-plane probing inside a VPC becomes a hard requirement and CodeBuild's in-VPC ENI attach latency proves material.

References

• HLD diagram: ../diagrams/nwaf-agent-hld.png (v1.1, CodeBuild)
• Related: ADR-0002 (LLM provider), ADR-0003 (detection & orchestration), ADR-0004 (detection tooling — installed in the build image), the scheduling ADR