Best Practice

Best practice guides from production experience — including anti-patterns to avoid and strategies for managing Terraform at scale.

What Will You Learn? #

This section collects wisdom from the experience of teams running Terraform in production. From frequently occurring anti-patterns to scaling and lifecycle management strategies, these guides help you avoid common traps.

Articles in This Section #

Article	Main Topic
Anti-Pattern: Over-Complex Module	Overly complex modules and how to simplify them
Anti-Pattern: Production Failure Scenario	Real production failure scenarios and the lessons learned
Anti-Pattern: Terraform as CM	Using Terraform for configuration management (which you shouldn’t)
Monorepo vs Multirepo	Terraform code organization strategies for various team sizes
Lifecycle Management	Managing resource lifecycles from creation to decommission
Performance Optimization	Speeding up plans and applies for large infrastructure
Scale Terraform	Strategies for running Terraform in large organizations

Anti-Pattern Overview #

flowchart TD
    subgraph OverComplex["Over-Complex Module"]
        OC["100+ variables<br/>500+ resources<br/>Nested 5 levels"]
        OC_FIX["Split into\nsmaller modules"]
    end

    subgraph AsCM["Terraform as CM"]
        CM["Running scripts\non instances\nManaging configs"]
        CM_FIX["Use Ansible/Chef\nfor config mgmt"]
    end

    subgraph ProdFail["Production Failure"]
        PF["No plan review\nDirect to prod\nNo rollback"]
        PF_FIX["Plan review\nStaged rollout\nBackup state"]
    end

    OverComplex --> OC_FIX
    AsCM --> CM_FIX
    ProdFail --> PF_FIX

    style OverComplex fill:#ffebee
    style AsCM fill:#ffebee
    style ProdFail fill:#ffebee
    style OC_FIX fill:#e8f5e9
    style CM_FIX fill:#e8f5e9
    style PF_FIX fill:#e8f5e9

Monorepo vs Multirepo #

flowchart LR
    subgraph Mono["Monorepo"]
        M_PRO["✅ Easy to share\nmodules"]
        M_PRO2["✅ Single source\nof truth"]
        M_CON["❌ Large blast\nradius"]
    end

    subgraph Multi["Multirepo"]
        MT_PRO["✅ Independent\ndeployments"]
        MT_PRO2["✅ Clear ownership"]
        MT_CON["❌ Module version\nmanagement"]
    end

    Mono -->|"Small-Medium Team"| Multi
    Multi -->|"Large Org"| Mono

    style Mono fill:#e3f2fd
    style Multi fill:#e8f5e9

Scaling Strategy #

flowchart TD
    subgraph Small["Small Team (1-5)"]
        S["Single repo<br/>Simple modules<br/>Manual approval"]
    end

    subgraph Medium["Medium Team (5-20)"]
        M["Multi repo<br/>Module registry<br/>CI/CD pipeline"]
    end

    subgraph Large["Large Org (20+)"]
        L["Platform team<br/>Self-service<br/>Policy as code"]
    end

    Small -->|"Growth"| Medium -->|"Scale"| Large

    style Small fill:#e8f5e9
    style Medium fill:#fff3e0
    style Large fill:#e3f2fd

These best practices are the result of real experience. Apply what’s relevant to your context.