Q: How do you structure a large Terraform codebase for a multi-environment setup?
Recommended structure:
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.
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.tfvarsand sizing, not in code paths. - State per environment and layer: split by blast radius, for example
network,data,platformandapps. 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.
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/workflowsfor CI. - Backend: declare an empty
backend "s3" {}and pass per-env values withterraform init -backend-config=backend.hclso 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_stateor, 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.
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 postterraform planoutput 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-exitcodeper root; exit code 2 means changes exist and should alert.
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.
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_tagsso 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.
- 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.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- 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.
- Keeping every layer in a single state A small change refreshes thousands of resources and a failed apply can leave unrelated infrastructure half modified.
- Hard-coding environment values inside modules The module stops being reusable and environments diverge in code rather than in input variables.
- Referencing modules by branch in prod Any push to that branch silently changes the next prod plan; pin to an immutable tag or version.