Terraform architecture review: the definitive 2026 guide
5+ years AWS engineering · Open-source contributor
Last reviewed: 2026-05-27
A Terraform architecture review is a structured assessment of an Infrastructure-as-Code workload against architectural best practices — typically the AWS Well-Architected Framework’s pillars for security, reliability, cost optimization, and operational excellence. This guide covers how to run one, what to look for, the tools that help, and a checklist you can use immediately.
What is a Terraform architecture review?
A Terraform architecture review evaluates your infrastructure code as a system — reading relationships between resources, assessing cross-service blast radius, and checking whether the configuration as a whole is appropriate for its intended workload. It produces a prioritised list of findings, each mapped to an AWS Well-Architected Framework control and assigned a severity based on workload context.
How it differs from a Terraform security scan
Tools like Checkov, tfsec, and Trivy apply deterministic rules to individual resource attributes — they check whether a specific attribute is set to a known-good value. Fast, reproducible, and free of false negatives for the conditions they cover. A Terraform architecture review goes beyond: it evaluates relationships between resources, blast radius, absent resources (things that should be there but aren’t), and workload context. The two are complementary. Run your linter in CI on every commit; run an architecture review at the review events described below.
How it differs from a code review
A code review checks readability, DRY violations, module structure, and variable naming. An architecture review checks whether the infrastructure the code produces is sound for its operational purpose: does it fail gracefully? Is the blast radius bounded? Does it cost what we expect? A well-structured Terraform file can still fail an architectural review.
When you need one
- ·Before the first production deployment of a new service
- ·Before major infrastructure changes — new VPC, new account structure, new data store
- ·After inheriting infrastructure you did not build
- ·Before a compliance audit or investor due diligence
- ·After AI tools wrote a significant portion of your Terraform
- ·On a recurring schedule (annually minimum, quarterly for high-risk workloads)
The four pillars of a Terraform architecture review
Identity, detection, infrastructure protection, data protection, incident response.
- ·IAM roles with overly broad permissions
- ·No CloudTrail multi-region trail
- ·S3 buckets without TLS-required bucket policy
- ·Security groups allowing broad CIDR ingress
Automatic recovery, scale horizontally, manage change in automation, test recovery procedures.
- ·Single-AZ RDS for production databases
- ·ASG min_size=1 in a single AZ
- ·Lambda async events without Dead Letter Queue
- ·No load balancer health check tuning
Cloud financial management, expenditure awareness, cost-effective resources.
- ·Resources missing cost allocation tags
- ·No S3 lifecycle policies
- ·Over-provisioned EC2 instance types
- ·Missing CloudWatch billing alarms
Operations as code, frequent small changes, anticipate failure, learn from events.
- ·No CloudWatch alarms on critical-path services
- ·Lambda without Dead Letter Queue for async processing
- ·CloudWatch Log Groups without retention period
- ·No SNS topic for alarm actions
Triggers: when to run a Terraform architecture review
Pre-production launch
Architectural debt is cheapest to fix before it is deployed. A review at this stage catches reliability and security patterns that would require disruptive changes to fix in production.
Post-hire infrastructure audit
New CTOs, new platform leads, and acquired-company onboarding all involve taking ownership of an environment built under different constraints. A structured review surfaces the risk before you are accountable for it.
Investor due diligence preparation
Series A and B technical DD now includes cloud infrastructure review. AWS Well-Architected findings in IAM, encryption, and observability are flagged by DD teams. Getting ahead of this with a review first is faster than remediating under time pressure.
Post-incident retrospective
After an outage or security event, an architecture review of the affected workload identifies the structural conditions that made the incident possible and prevents recurrence.
AI-generated infrastructure review
AI-generated Terraform is syntactically valid and often architecturally unsound. Models generate what they were trained on, not what your specific workload requires. A review after significant AI-assisted infrastructure work is a new, high-value trigger for 2026.
How to run a Terraform architecture review (step by step)
Inventory the workload
Gather all .tf files, module directories, and the relevant tfvars file for the environment under review. Document the workload context: service type, environment, SLA, data sensitivity, which WAFR pillars matter most.
Run linters in CI first
Run Checkov, tfsec (via Trivy), or equivalent. Resolve Critical and High linter findings before the architectural review begins. An architecture review is most useful when the baseline configuration is already clean — mixing linter findings with architectural findings in the same report makes prioritisation harder.
Review against each WAFR pillar
Work through Security, Reliability, Cost Optimization, and Operational Excellence systematically. For each pillar, evaluate the Terraform against the high-impact controls. See the checklist at /blog/terraform-architecture-review-checklist for a starting list mapped to CIS AWS Foundations Benchmark v3.0.0.
Assign severity using workload context
Critical: finding that could result in data breach, regulatory breach, or complete service unavailability. High: materially increases risk or would result in extended downtime. Medium: should be remediated before the next major release. Low: best-practice gap with no immediate risk. Severity is a function of both likelihood and blast radius.
Document findings with remediation HCL
Each finding needs: the WAFR control it violates, the current state in Terraform, the recommended change, and estimated effort. Separate "fix before next deploy" (Critical/High) from "backlog" (Medium/Low).
Produce a stakeholder report
Executive summary (overall posture, pillar scores, top three findings), findings section organised by pillar, appendix listing all Terraform files reviewed. The report must be readable by a non-technical stakeholder without losing the technical detail needed by the implementing engineer.
Tools for Terraform architecture review
No single tool covers the full scope of a Terraform architecture review. The table below is honest about what each tool does and what it doesn’t do. The right answer for most teams is both linting and architectural review layers.
| Tool | Type | Coverage | Output | Price |
|---|---|---|---|---|
| Checkov | Config linter | Security (partial) | CLI / JSON / SARIF | Free (OSS) |
| tfsec | Config linter (deprecated) | Security (partial) | CLI / JSON | Free → use Trivy |
| Trivy | Multi-scanner | Security (partial) | CLI / JSON | Free (OSS) |
| AWS WA Tool | Interview-driven | All 6 WAFR pillars | Console + report | Free |
| AWS WA IaC Analyzer | GenAI OSS | WAFR pillars | Web UI + assembled PDF | Free + Bedrock usage |
| ArchGuard | Hosted arch review | 4 WAFR pillars | Branded PDF | $49–$399/mo |
Common findings in real-world Terraform reviews
These patterns appear consistently in production Terraform. All pass standard linting. All carry real architectural risk. Each is mapped to its AWS WAFR control.
Multi-region without failover
Terraform that deploys to multiple regions but has no Route 53 health checks, no ALB cross-region routing, and no RDS read replica in the secondary region. Deploying to multiple regions without failover logic does not improve availability — it creates the illusion of resilience without the substance.
AWS Well-Architected Reliability Pillar, REL 6: Scale workload resources.
S3 buckets without lifecycle policies
S3 buckets accumulating objects indefinitely without S3 Intelligent-Tiering or explicit lifecycle rules. For buckets used as log targets, artifact stores, or data pipelines, this is a slow-growing cost issue that compounds over months. Checkov has no rule for the absence of lifecycle policies.
AWS Well-Architected Cost Optimization Pillar, COST 5: Select the correct resource type.
NAT Gateway in every AZ
Three NAT Gateways (one per AZ) can cost $100+/month before data transfer. For development environments or low-traffic workloads, a single NAT Gateway with cross-AZ routing is appropriate — the reliability tradeoff is acceptable and the cost is a third. Document the decision; don't make it by accident.
AWS Well-Architected Cost Optimization Pillar, COST 3: Implement cloud financial management.
Hardcoded account IDs in resource ARNs
Terraform that hardcodes the AWS account ID in IAM policy ARNs, S3 bucket ARNs, or KMS key ARNs. When the account changes (migration, multi-account, workload isolation), every hardcoded reference must be updated. Use data.aws_caller_identity.current.account_id instead.
AWS Well-Architected Operational Excellence Pillar, OPS 6: Perform operations as code.
IAM roles with overly broad permissions (not wildcards)
CKV_AWS_40 catches wildcard actions. It does not catch a role with 12 specific actions where the workload only needs 3. Every extra permission extends the blast radius if the role is compromised. Architectural review maps what the Lambda or EC2 actually calls versus what the role allows.
AWS Well-Architected Security Pillar, SEC 2: Grant least privilege.
Reporting and deliverables
A credible Terraform architecture review report contains three parts:
- 1
Executive summary
Overall posture score, per-pillar scores, top three findings with one-sentence summaries, recommended immediate actions. Readable by a non-technical stakeholder in under five minutes.
- 2
Findings section
Each finding with: WAFR pillar, control reference (e.g. SEC 2), severity, current state in Terraform, remediation HCL, and estimated effort. Organised by pillar, sorted by severity within each pillar.
- 3
Appendix
Full list of Terraform files reviewed, module versions, review date, workload context parameters (environment, SLA, data sensitivity).
For a worked example, see the ArchGuard sample report or the Terraform architecture review checklist.
Frequently asked questions
How long does a Terraform architecture review take?↓
Manual reviews by an experienced engineer typically take 4–8 hours for a mid-sized workload (20–50 Terraform files). Automated tools like ArchGuard return results in under an hour. A full report with remediation HCL takes another 2–4 hours to compile manually, or is produced automatically.
Do I need to give the reviewer my AWS credentials?↓
No. A Terraform architecture review reads the HCL files only — it does not need AWS account access, read-only IAM roles, or Terraform state. The review is entirely code-based.
How is this different from running Checkov in CI?↓
Checkov runs rule-based checks on individual resource attributes. A Terraform architecture review evaluates the workload as a system — relationships between resources, cross-service blast radius, absent resources (things that should be there but aren't), and workload context (is this prod or dev?). The two are complementary. Run Checkov in CI on every commit; run an architecture review before launches, after inheritance, and annually for production workloads.
Can I do this review myself, or do I need a consultant?↓
You can run through the framework yourself using the AWS Well-Architected Framework documentation and this guide. For a structured deliverable you can share with stakeholders, ArchGuard produces a PDF report automatically. For complex multi-account or multi-team programs, a consultant adds value on top of the structured analysis.
What's the cost of a Terraform architecture review?↓
Manual review by an AWS consultant: $5K–$25K per engagement. AWS Well-Architected Tool: free (but interview-driven, no Terraform input). ArchGuard: $49–$399/month, or $50–$66 per review with Credit Packs.
How often should we run a Terraform architecture review?↓
At minimum: before the first production deployment of a new service, before major infrastructure changes (new VPC, new account structure), and annually for stable production workloads. AWS recommends re-running after any significant workload change. Quarterly is appropriate for higher-risk workloads (payments, healthcare, multi-tenant SaaS).
Run your Terraform architecture review in under an hour
ArchGuard reads your Terraform and produces a Well-Architected PDF across Security, Reliability, Cost, and Operational Excellence — with findings, severity, and remediation HCL.