⚡ ~/naveed Interview Prep
⚡ Portfolio Home 👤 About Naveed Bio & Credentials 📫 Contact Naveed Get In Touch ✍️ Engineering Blog Deep Dives 🎯 Interview Hub 1,000+ Scenarios ☸️ Kubernetes Mastery Hub 24 Modules 🎮 DevOps Arcade & Quizzes Subnet Blitz ⚡ 🗺️ DevOps Roadmaps PDFs & Guides 🤖 Morpheus Analysis AI Quant ↗ 🛠️ Developer Tools Utilities 🧪 Labs & Experiments 📄 Interactive CV & Certs 🔗 All Links & Socials ⚡ Join The Dispatch (Weekly SRE Newsletter) →
← Back to All Terraform & IaC Interview Questions Scenario 11 of 120 in Terraform & IaC
Senior DevOps / SRE [L2] Terraform Modules & Structure Production Scenario [L2]
🎯 Target Role / Context: Terraform Scenario #6 (L2) · Modules & Structure

Q: How do you structure a large Terraform codebase for a multi-environment setup?

Recommended structure:

#Terraform #Modules & Structure #L2 #IaC #Cloud Infrastructure #IAM
🎙️ Candidate Opening & Architectural Context
"To <strong>structure a large Terraform codebase</strong> for a multi-environment setup, keep reusable logic in versioned modules, give every environment (and every blast-radius layer inside it) its own root configuration and remote state, and promote changes through CI with plan on pull request and apply on merge. Interviewers ask this because Terraform scales badly when everything lives in one state file: plans slow down, a mistake in dev can touch prod and teams block each other on locks. The strong answer shows clear decisions about module boundaries, state isolation, environment differences and how credentials and reviews flow."
Advertisement
⚡ Recommended Practice Lab

Want to master this scenario in a live sandbox? KodeKloud's HashiCorp Certified Terraform Associate (003) Interactive Labs covers this exact problem with hands-on terminal drills.

🛠️ Production Runbook & Step-by-Step Resolution

Direct Answer: To <strong>structure a large Terraform codebase</strong> for a multi-environment setup, keep reusable logic in versioned modules, give every environment (and every blast-radius layer inside it) its own root configuration and remote state, and promote changes through CI with plan on pull request and apply on merge. Interviewers ask this because Terraform scales badly when everything lives in one state file: plans slow down, a mistake in dev can touch prod and teams block each other on locks. The strong answer shows clear decisions about module boundaries, state isolation, environment differences and how credentials and reviews flow.

1️⃣

Design principles for a large Terraform codebase

Decide boundaries before directories: what changes together, who owns it and what is the damage if it goes wrong.

  • Modules are the library: one module per capability (vpc, eks-cluster, rds), with typed variables, outputs and no hard-coded environment values. Version them by Git tag or registry release.
  • Root configs are the deployments: each environment calls modules with its own inputs, so dev, staging and prod differ only in terraform.tfvars and sizing, not in code paths.
  • State per environment and layer: split by blast radius, for example network, data, platform and apps. Smaller states plan faster and limit what a bad apply can break.
  • Workspaces are not isolation: they share one backend configuration and code, so many teams prefer separate directories or accounts for prod; workspaces suit short-lived copies like feature environments.
2️⃣

Hands-on: directory layout and backend per environment

A layout where environment folders are thin and modules hold the logic, with a partial backend configuration per environment.

# Suggested repository layout
# modules/vpc/  modules/eks/  modules/rds/
# live/dev/network/main.tf      backend.hcl   terraform.tfvars
# live/dev/platform/...
# live/prod/network/...         backend.hcl   terraform.tfvars

# live/prod/network/backend.hcl
bucket         = "acme-tfstate-prod"
key            = "network/terraform.tfstate"
region         = "us-east-1"
dynamodb_table = "acme-tflock-prod"
encrypt        = true

# live/prod/network/main.tf
module "vpc" {
  source = "git::https://example.com/infra-modules.git//vpc?ref=v1.4.0"
  cidr   = var.cidr
  env    = "prod"
}

# Initialise one layer
cd live/prod/network
terraform init -backend-config=backend.hcl
terraform plan -var-file=terraform.tfvars -out=tfplan
  • Layout: modules/ for reusable code, live/<env>/<layer>/ for root configs, plus a shared .github/workflows for CI.
  • Backend: declare an empty backend "s3" {} and pass per-env values with terraform init -backend-config=backend.hcl so code stays identical.
  • Locking: the S3 backend historically uses a DynamoDB table via dynamodb_table; newer Terraform releases (1.10 and later) add native S3 locking, so check your version.
  • Cross-layer data: read other layers through terraform_remote_state or, better, data sources and published outputs such as SSM parameters to avoid tight coupling.
  • Tooling option: Terragrunt or a similar wrapper can generate backend and provider blocks to cut repetition, but plain Terraform with a consistent layout is enough for many teams.
Advertisement
3️⃣

Automation: CI flow and promotion across environments

The directory structure only works if the pipeline enforces how changes move from dev to prod.

# CI plan step (exit code 2 = changes present)
terraform init -input=false -backend-config=backend.hcl
terraform plan -input=false -detailed-exitcode -out=tfplan
# CI apply step after approval, using the exact reviewed plan
terraform apply -input=false tfplan
  • Pull request: run terraform fmt -check, validate, a linter such as TFLint and a security scan, then post terraform plan output on the PR for review.
  • Merge: apply the saved plan file so what was reviewed is exactly what runs; apply dev automatically and gate staging and prod with approvals.
  • Pin modules: prod references a released module tag while dev can track a branch, so you promote by bumping the tag per environment.
  • Detect drift: schedule a nightly terraform plan -detailed-exitcode per root; exit code 2 means changes exist and should alert.
4️⃣

Failure modes and how structure prevents them

Large estates fail in predictable ways, and structure is the main mitigation.

  • God state file: hundreds of resources in one state cause slow refreshes, long locks and risky applies. Split along ownership and change frequency.
  • Copy-paste environments: duplicated code drifts. Push differences into variables and let modules enforce standards.
  • Module sprawl: a module that wraps a single resource adds indirection without value; extract modules when reuse or an interface boundary is real.
  • Shared credentials: using one admin role everywhere defeats isolation. Use separate accounts or subscriptions per environment and one role per root, assumed via OIDC from CI.
  • Ownership: use CODEOWNERS per directory so the network team reviews network changes and application teams own their layer.
Pro Tip: Moving resources between states or modules needs <code>moved</code> blocks or <code>terraform state mv</code> with backups; plan it as a migration, not a rename.
5️⃣

Governance, naming and quality gates

A large codebase needs conventions that every contributor can follow without asking.

  • Naming and tagging: enforce a common prefix, environment and owner tag through module defaults, and use provider default_tags so nothing ships untagged.
  • Static checks: run terraform fmt, TFLint and a policy scanner on every change so reviewers focus on design, not style.
  • Module contracts: document inputs and outputs with terraform-docs, keep a CHANGELOG and treat removed variables as breaking changes that require a major version.
  • Disaster recovery: enable bucket versioning on the state bucket and restrict write access to the CI role, so state can be restored after a bad apply.
💡 The Senior SRE Gold Nugget (Key Architectural Takeaway)
"Pro-Tip: Isolate by blast radius, not just by environment: separate state for network, data and apps in each environment, deployed from versioned modules with one narrowly scoped role per root."
⚡ 60-Second Elevator Pitch Talking Points
  • I put reusable logic in versioned modules and create one thin root configuration per environment and layer, each with its own remote state and locking.
  • I verify with plan on every PR, saved plan files for apply, and a scheduled drift plan using detailed-exitcode.
  • I automate promotion through CI by bumping module tags per environment, with OIDC roles and approvals gating production.
⛔ Critical Candidate Mistakes to Avoid in This Scenario

Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:

  1. Using workspaces as the only prod/dev separation Workspaces share code and backend settings, so one wrong workspace selection can apply dev changes to prod resources.
  2. Keeping every layer in a single state A small change refreshes thousands of resources and a failed apply can leave unrelated infrastructure half modified.
  3. Hard-coding environment values inside modules The module stops being reusable and environments diverge in code rather than in input variables.
  4. Referencing modules by branch in prod Any push to that branch silently changes the next prod plan; pin to an immutable tag or version.
Advertisement
Want more Terraform & IaC scenarios?
Explore our complete collection of scenario-based Terraform & IaC interview runbooks.
Browse All Terraform & IaC Questions →