Terraform Modules — Best Practices for Enterprise

We started with a single large main.tf. Today we have a library of 30+ modules, CI/CD for infrastructure, and automated testing. We share the patterns that work for us.

Repository Structure¶

terraform/
  modules/          # shared modules
    vpc/
    eks-cluster/
    rds/
    s3-bucket/
  environments/     # per-environment configuration
    dev/
    staging/
    production/
  global/           # shared resources (IAM, DNS)

Module Design Principles¶

• Single responsibility: a module does one thing well
• Explicit inputs/outputs: no hardcoded values
• Sane defaults: works out of the box, customizable
• Versioning: Git tags, semantic versioning
• Documentation: README with examples for every module

Infrastructure Testing¶

Terratest (Go framework): creates real infrastructure in a test account, verifies it works, and destroys it. Slow, but reliable. Runs in the CI pipeline on merge to main.

State Management¶

Separate state per environment. S3 backend with DynamoDB locking. State encryption at rest. Minimal access to state — only CI/CD pipeline and senior engineers.

Sentinel/OPA Policies¶

Terraform plan passes through a policy check: no public S3 buckets, mandatory encryption, mandatory tags. Automatic enforcement in the CI pipeline — plans that violate policies don’t pass.

Terraform in Enterprise Requires Discipline¶