Introduction
Terraform has become one of the most widely adopted Infrastructure as Code (IaC) tools for provisioning cloud infrastructure. With just a few lines of code, we can deploy complete environments in AWS, from networking and compute to databases, Kubernetes clusters, and serverless applications.
But there is an important reality that is often overlooked:
Terraform does not automatically create well-architected infrastructure.
A Terraform deployment can succeed while still introducing security vulnerabilities, single points of failure, unnecessary operational complexity, poor cost efficiency, or infrastructure that becomes difficult to maintain as it grows. In other words, valid Terraform code is not always good architecture.
Throughout my experience working with cloud infrastructure and enterprise platforms, I've noticed that many Terraform projects share the same recurring issues. Interestingly, most of these problems are not caused by incorrect syntax or provider bugs—they are design decisions that quietly violate the principles of the AWS Well-Architected Framework.
Examples include:
- Storing Terraform state locally instead of using a secure remote backend.
- Granting overly permissive IAM permissions for the sake of convenience.
- Deploying production databases into public subnets.
- Building monolithic Terraform projects that become difficult to maintain.
- Ignoring validation, policy checks, and security scanning before deployment.
- Forgetting tagging strategies, making governance and cost allocation significantly harder.
None of these mistakes will necessarily cause Terraform to fail during terraform apply. In fact, the deployment may complete successfully. However, these decisions often become expensive technical debt that surfaces later during production incidents, security reviews, compliance audits, or rapid infrastructure growth.
This is exactly where the AWS Well-Architected Framework becomes invaluable.
Rather than focusing only on how to provision infrastructure, the framework encourages us to evaluate why we design it in a particular way. It provides a structured approach for building cloud environments that are secure, reliable, operationally efficient, high performing, cost optimized, and sustainable.
In this article, we'll examine ten of the most common Terraform mistakes that can undermine those principles. For each mistake, we'll cover:
- Why it happens.
- Which AWS Well-Architected pillar it impacts.
- Why it becomes a problem in real production environments.
- Practical recommendations and Terraform best practices to address it.
This isn't another "how to write Terraform" tutorial. Instead, the goal is to bridge the gap between Infrastructure as Code and Cloud Architecture, helping you write Terraform that not only works—but also aligns with the engineering practices expected in modern production environments.
Whether you're a DevOps Engineer, Cloud Engineer, Site Reliability Engineer, Platform Engineer, or Cloud Architect, I hope this article helps you recognize common pitfalls before they reach production and provides practical guidance for building infrastructure that is both automated and well architected.
Recap about the AWS Well-Architected pillars
The AWS Well-Architected Framework provides a set of design principles and best practices for building secure, reliable, efficient, and sustainable cloud workloads. Rather than evaluating Terraform syntax, it helps us evaluate the quality of the infrastructure that Terraform provisions.
Throughout this article, we'll map each Terraform mistake to one or more of the following six pillars:
1. Operational Excellence: Operating, monitoring, and continuously improving workloads.
2. Security: Protecting systems, data, and identities through defense in depth and least privilege.
3. Reliability: Designing systems that recover gracefully from failures and continue to meet business requirements.
4. Performance Efficiency: Selecting the right resources and architectures to maximize performance.
5. Cost Optimization: Eliminating unnecessary costs while delivering business value.
6. Sustainability: Minimizing the environmental impact of cloud workloads through efficient resource utilization.
The goal isn't simply to deploy infrastructure successfully—it's to deploy infrastructure that remains secure, resilient, cost-effective, and maintainable throughout its lifecycle.
10 Terraform Mistakes That Break the AWS Well-Architected Framework
Mistake #1 — Using a Local Terraform Backend in Production
❌ The Mistake:
Keeping the Terraform state file (terraform.tfstate) on a local machine.
🎯 Why It Happens:
- Easier to get started
- Common in tutorials
- Teams postpone remote state configuration
⚠ Why It's Risky:
- State corruption
- No collaboration
- No state locking
- Difficult disaster recovery
- Risk of exposing sensitive information
🏛 AWS Well-Architected Pillars:
- Operational Excellence
- Security
- Reliability
✅ Recommended Approach:
- S3 Backend
- State Locking
- Versioning
- Encryption
Mistake #2 — Granting AdministratorAccess to Terraform
❌ The Mistake:
Running Terraform with AdministratorAccess.
🎯 Why It Happens:
- Faster initial setup
- Avoids IAM permission errors
⚠ Why It's Risky:
- Excessive privileges
- Larger attack surface
- Compliance issues
- Difficult auditing
🏛 AWS Well-Architected Pillars:
- Security
✅ Recommended Approach:
- Least Privilege
- Permission Boundaries
- Separate Deployment Role
Mistake #3 — Putting Everything in One main.tf
❌ The Mistake:
Managing an entire infrastructure in a single Terraform file.
🎯 Why It Happens:
- Small projects grow over time
- No modular design from the beginning
⚠ Why It's Risky:
- Difficult maintenance
- Poor scalability
- Hard code reviews
- Low reusability
🏛 AWS Well-Architected Pillars:
- Operational Excellence
✅ Recommended Approach:
- Modules
- Reusable Components
- Environment Separation
Mistake #4 — Hardcoding Values
❌ The Mistake:
Embedding account IDs, regions, AMIs, ARNs, passwords, or environment-specific values directly in the code.
🎯 Why It Happens:
- Quick testing
- Copying examples
⚠ Why It's Risky:
- Difficult deployments
- Human errors
- Poor portability
- Secret exposure
🏛 AWS Well-Architected Pillars:
- Operational Excellence
- Security
✅ Recommended Approach:
- Variables
- Locals
- Data Sources
- Terraform Cloud Variables
- AWS Secrets Manager
- AWS Systems Manager Parameter Store
Mistake #5 — Ignoring Version Pinning
❌ The Mistake:
Not locking Terraform or provider versions.
🎯 Why It Happens:
- Simplicity
- Lack of awareness
⚠ Why It's Risky:
- Breaking changes
- Inconsistent deployments
- Unpredictable CI/CD pipelines
🏛 AWS Well-Architected Pillars:
- Operational Excellence
- Reliability
✅ Recommended Approach:
- Required Providers
- Required Terraform Version
- Lock File
Mistake #6 — Skipping Validation and Security Checks
❌ The Mistake:
Running terraform apply without validating the code.
🎯 Why It Happens:
- Pressure to deploy quickly
- Missing CI/CD quality gates
⚠ Why It's Risky:
- Security vulnerabilities
- Invalid configurations
- Failed deployments
- Compliance issues
🏛 AWS Well-Architected Pillars:
- Operational Excellence
- Security
✅ Recommended Approach:
- terraform fmt
- terraform validate
- TFLint
- Checkov
- tfsec
- Trivy
Mistake #7 — Building Public Infrastructure by Default
❌ The Mistake:
Deploying databases, Kubernetes nodes, or internal services into public subnets.
🎯 Why It Happens:
- Easier connectivity
- Tutorial-driven implementations
⚠ Why It's Risky:
- Larger attack surface
- Increased security risk
- Compliance violations
🏛 AWS Well-Architected Pillars:
- Security
- Reliability
✅ Recommended Approach:
- Private Subnets
- Security Groups
- NACLs
- AWS Secrets Manager
- AWS Systems Manager Parameter Store
- Bastion or Session Manager
Mistake #8 — Ignoring Tagging and Resource Governance
❌ The Mistake:
Creating AWS resources without a consistent tagging strategy.
🎯 Why It Happens:
- Considered optional
- Overlooked during development
⚠ Why It's Risky:
- Difficult cost allocation
- Poor ownership tracking
- Weak automation
- Governance challenges
🏛 AWS Well-Architected Pillars:
- Cost Optimization
- Operational Excellence
✅ Recommended Approach:
- Default Tags
- Mandatory Tags
- Cost Center
- Owner
- Environment
Mistake #9 — Designing for Success Instead of Failure
❌ The Mistake:
Deploying infrastructure without considering failures.
🎯 Why It Happens:
- Focus on deployment success
- Limited production experience
⚠ Why It's Risky:
- Single points of failure
- Poor recovery
- Downtime
- Weak disaster recovery
🏛 AWS Well-Architected Pillars:
- Reliability
✅ Recommended Approach:
- Multi-AZ
- Auto Scaling
- Health Checks
- Backups
- Route 53 Failover
Mistake #10 — Treating Terraform as an Architecture Tool Instead of an Implementation Tool
❌ The Mistake:
Starting with Terraform before designing the architecture.
🎯 Why It Happens:
- Infrastructure as Code is mistaken for infrastructure design
- Pressure to deliver quickly
⚠ Why It's Risky:
- Technical debt
- Frequent redesigns
- Inconsistent infrastructure
- Solutions that violate Well-Architected principles
🏛 AWS Well-Architected Pillars:
- All Six Pillars
💻 Common Anti-Pattern:
✅ Recommended Approach:
Top comments (0)