Back to GitHub Projects
    Open Source · Go

    tfdrift

    Recursive Terraform & Terragrunt drift detector — scans all root modules in parallel, runs init+plan, and reports which directories have drifted from recorded state.

    Terraform
    Go
    DevOps
    CI/CD
    View on GitHub
    Architecture
    architecture-diagram.png
    tfdrift Architecture

    About

    tfdrift is a Go CLI tool that solves a common pain point in multi-module Terraform repositories: knowing which directories have drifted from their recorded state without running plan across each one manually. It recursively discovers every Terraform and Terragrunt root module under a given path, then executes init and plan across all of them concurrently using a bounded worker pool. Results are aggregated and surfaced as a human-readable console table, machine-readable JSON, or styled HTML/PDF reports — with exit codes that mirror Terraform's own -detailed-exitcode convention so CI pipelines can gate on drift without any extra scripting.

    Key Features

    Recursive module discovery — finds every *.tf and terragrunt.hcl root
    Parallel execution with configurable worker pool (--parallelism)
    Supports both Terraform and Terragrunt via --tool flag
    Per-resource drift detail with --detailed flag (plan JSON parsing)
    HTML report with client-side search and status filter buttons
    PDF report via pure-Go engine — no external binary required
    JSON stdout for machine-readable CI integration
    Exit codes mirror terraform -detailed-exitcode (0/1/2)
    Per-module timeout (--timeout) so a hung plan never blocks the run
    Pre-built binaries for linux/darwin/windows × amd64/arm64

    Engineering Challenges

    Safely fanning out across dozens of modules without one failure aborting the whole run
    Parsing plan JSON to extract per-resource change actions and raw diff blocks accurately
    Generating PDF reports without shelling out to an external binary (pure-Go constraint)
    Keeping stdout clean for JSON mode while routing structured logs to stderr

    Results & Impact

    Single command to audit an entire Terraform monorepo for drift
    CI pipeline can gate deployments on drift with a standard exit-code check
    HTML report gives engineers a searchable, filterable view of every drifted resource
    Pre-built binaries mean zero Go toolchain dependency for operators