Picture this: it's 2 AM, a replica of your staging environment is needed urgently for a client demo, and the only person who knows which security groups were manually clicked into place three months ago is on a flight to Singapore. This scenario plays out constantly at software companies that still treat infrastructure as a series of console clicks and tribal knowledge. Infrastructure as code with Terraform is the systematic answer — it turns your cloud environment into a versioned, reviewable, repeatable artifact that anyone on the team can understand and redeploy.
What "Infrastructure as Code" Actually Means in Practice
The phrase gets used loosely, so let's be precise. Infrastructure as code (IaC) means declaring the desired state of your systems in configuration files — servers, networks, DNS records, IAM policies, databases — and letting a tool reconcile reality with that declaration. Terraform, built by HashiCorp, is the dominant IaC tool for multi-cloud environments because it works across AWS, GCP, Azure, and dozens of other providers through a plugin model called providers.
The core loop is simple: you write .tf files describing resources, run terraform plan to preview what will change, then terraform apply to make it so. Terraform tracks what it has created in a state file — more on that in a moment — so it can calculate the diff on every subsequent run.
The practical payoff isn't just reproducibility. It's auditability. Every infrastructure change becomes a pull request. Your team can review it, test it in a lower environment, and merge it with the same discipline applied to application code.
Module Structure: The Difference Between a Mess and a Platform
A single flat directory of .tf files works fine for a personal project. It breaks down fast for anything with multiple environments (dev, staging, prod) or multiple teams. The answer is Terraform modules — reusable, encapsulated units that accept input variables and return output values.
A sensible structure for a mid-sized SaaS product looks like this:
- modules/ — shared, versioned building blocks (e.g., vpc, rds-postgres, ecs-service)
- environments/dev/ — instantiates modules with dev-appropriate sizing
- environments/staging/ — same modules, closer to prod sizing
- environments/prod/ — production config, often with stricter IAM and backup policies
Each module should expose only what callers need to configure. Hide the implementation details. A good rds-postgres module, for example, accepts instance_class, storage_gb, and backup_retention_days as inputs but manages subnet groups, parameter groups, and the security group ingress rules internally.
Version-pin your modules. If you're pulling from a Git-tagged registry or Terraform Cloud's private registry, always reference a specific tag (ref=v1.4.2, not ref=main). An upstream change should never silently break a production apply.
State Management: The Part That Bites Teams Most Often
Terraform's state file is the source of truth about what resources exist and which Terraform identifiers map to which cloud resource IDs. Losing it, or corrupting it, is painful — you may have to import resources manually or, in the worst case, rebuild from scratch.
Three rules to follow from day one:
- Never store state locally in production. Use a remote backend: S3 + DynamoDB for AWS, GCS + a lock table for GCP, or Terraform Cloud. Remote backends enable state locking — only one apply runs at a time, preventing concurrent modifications.
- Enable versioning on your state bucket. S3 bucket versioning costs almost nothing and means a botched apply can be rolled back by restoring the previous state file version.
- Separate state per environment. A
terraform workspaceor separate backend config per environment means a mistake in dev can never corrupt prod state. Many teams prefer explicit backend config files over workspaces for this reason — workspaces can become confusing when environments diverge significantly.
Writing Terraform That Doesn't Drift
Drift happens when someone makes a manual change in the AWS console that isn't reflected in code. Over time, drift turns your beautiful IaC setup back into the same tribal-knowledge problem you were trying to escape.
| Problem | Cause | Prevention |
|---|---|---|
| Console drift | Engineers make hotfixes in the UI | SCPs or IAM policies blocking manual changes; terraform plan in CI to detect drift |
| State corruption | Concurrent applies or interrupted runs | Remote backend with DynamoDB locking |
| Dependency cycles | Resources referencing each other | Use depends_on sparingly; restructure modules to break cycles |
| Secrets in state | Passwords/keys in resource attributes | Use AWS Secrets Manager or Vault; mark sensitive outputs with sensitive = true |
Running terraform plan in your CI pipeline on every pull request is one of the highest-value automation investments you can make. If the plan shows unexpected changes, the PR fails — a forcing function that keeps the codebase and the real infrastructure in sync.
Variables, Locals, and the Art of Not Repeating Yourself
Terraform gives you three mechanisms for avoiding repetition: input variables (values passed in from outside), local values (computed within a module), and data sources (values read from the provider at runtime). Using them well is what separates readable Terraform from spaghetti.
A common pattern: define a locals.tf in each environment that derives tags, name prefixes, and CIDR blocks from a small set of input variables. Every resource then references those locals rather than hard-coding strings. When the environment name or region changes, one variable changes, and everything cascades correctly.
Avoid putting logic in variable defaults. Defaults should be safe, obvious values — not computed expressions. Compute in locals, expose simple values as variables.
Testing and Validating Terraform Code
Terraform introduced native test blocks in version 1.6, allowing you to write automated checks against a terraform apply output in a real or mocked provider. Before that, tools like Terratest (Go-based) and terraform-compliance (policy-as-code) filled the gap.
A minimal testing strategy for most teams:
terraform validateandterraform fmt --checkon every commit (seconds to run, catches syntax errors)tflintfor provider-specific rules (catches things like invalid instance types before apply)checkovortfsecfor security policy checks (public S3 buckets, unencrypted volumes, open security groups)- Integration tests against a real dev/sandbox environment for any new module before merging
Frequently Asked Questions
Is Terraform still the right choice now that AWS CDK and Pulumi exist?
Terraform's HCL is deliberately declarative and non-procedural, which makes plans predictable and diffs readable. CDK and Pulumi use general-purpose languages (TypeScript, Python, Go) — powerful for complex logic, but easier to write code that has unpredictable side effects. For teams managing infrastructure across multiple cloud providers, Terraform's provider ecosystem is still unmatched. That said, if your team is heavily invested in a single cloud and prefers typed code, CDK or Pulumi are legitimate alternatives worth evaluating.
How do you manage secrets in Terraform without storing them in state?
The safest approach is to never pass secrets as Terraform variables at all. Instead, reference existing secrets by ARN or ID — for example, look up an AWS Secrets Manager secret by name using a data source, then pass its ARN to the resource that needs it. The actual secret value never appears in your state file. For database passwords specifically, the aws_db_instance resource supports the manage_master_user_password flag which delegates password rotation entirely to Secrets Manager.
What's the right way to handle Terraform across a large team without stepping on each other?
Remote state with locking (S3 + DynamoDB or Terraform Cloud) prevents concurrent applies from corrupting state. Beyond that, organizing infrastructure into small, independently applicable root modules — each with its own state — reduces blast radius and contention. Many teams adopt Atlantis or Terraform Cloud's VCS-driven workflow so that applies only happen through pull request comments after review, eliminating the "someone applied from their laptop" problem entirely.
How long does it typically take to migrate an existing manually-managed environment to Terraform?
Realistically, importing a medium-complexity environment (say, 50-100 cloud resources) takes two to four weeks with a dedicated engineer who knows the environment well. The terraform import command imports individual resources into state; newer versions support bulk import blocks. The harder part is writing accurate .tf configurations that match the existing resource configuration without triggering unwanted changes on the first apply — which is why a phased approach, importing non-critical resources first, is strongly recommended.
When you're ready to build this, Mexilet can help — explore our cloud & DevOps services and software engineering team.
If your team is sitting on a manually managed environment and the drift is becoming a liability, the lowest-risk path forward is a time-boxed pilot: pick one non-critical service, bring it under Terraform management, and establish your module patterns and CI pipeline before tackling the rest. Reach out to Mexilet Technologies to scope a focused IaC migration sprint — a small, well-defined engagement is the right way to de-risk the transition before committing to a full infrastructure overhaul.