Terragrunt

Terragrunt is a command-line tool that sits on top of Terraform and OpenTofu to solve the problems that show up once infrastructure-as-code grows past a single module: repeated provider/backend boilerplate, manual ordering of interdependent applies, and hand-copied remote-state configuration. It parses a tree of terragrunt.hcl files, lets child configs inherit shared settings from parent configs via include blocks, and reads outputs from one module into another via dependency blocks so multi-module stacks apply in the right order automatically.

Beyond configuration inheritance, Terragrunt generates and manages remote-state backends (S3+DynamoDB, GCS, Azure Blob) so teams never hand-write the same backend block dozens of times, and it can discover every unit in a directory tree and drive plan/apply/destroy across all of them as a single dependency-ordered run --all operation. It works with either the Terraform or OpenTofu binary, integrates SOPS for secret decryption, and ships a catalog command plus a DAG visualizer so teams can browse reusable modules and see the dependency graph they’re about to run.

What You Get

• DRY include/dependency HCL blocks that eliminate copy-pasted provider, backend, and variable configuration across environments
• A dependency-graph-driven run --all command for planning, applying, or destroying many modules in the correct topological order
• Automatic remote-state backend generation and management for AWS S3/DynamoDB, GCS, and Azure Blob
• Native OpenTofu and Terraform binary detection with per-module version pinning
• Built-in SOPS secrets decryption and cloud-SDK-backed authentication for AWS, Azure, and GCP
• A dag graph visualizer and module catalog for browsing and scaffolding reusable modules

Common Use Cases

• Running one HCL-defined stack across dozens of AWS accounts and regions without duplicating backend configuration
• Migrating a single large Terraform state (a “terralith”) into independently-applied modules with correct apply ordering
• Driving plan/apply for only the changed units in a CI/CD pipeline instead of one monolithic state
• Wiring outputs from a shared VPC/network module into downstream application modules automatically
• Managing separate remote-state backends across multiple clouds from a single repository

Under The Hood

Architecture Terragrunt’s main.go wires a CLI built in internal/cli (app.go plus a commands and flags tree, not a third-party CLI framework) that dispatches subcommands such as run, run --all, dag, and catalog. Configuration parsing lives in pkg/config, which reads terragrunt.hcl files (backed by internal/hclparse/internal/hclhelper on top of HashiCorp’s HCL parser) and resolves include inheritance and dependency output-wiring. internal/discovery walks the repository to find units and builds a dependency graph (phase_graph.go), which internal/runner and internal/runner/graph then execute, invoking the Terraform or OpenTofu binary selected by internal/tf through internal/shell. internal/remotestate owns backend generation for S3/GCS/Azure. This is a modular, layered CLI: parsing, graph construction, and process execution are cleanly separated internal packages, and the core abstraction other layers depend on is the unit dependency graph — changing it would ripple through discovery, runner, and stacks.

Tech Stack A Go 1.27 module with no third-party CLI framework; HCL parsing goes through hashicorp/hcl/v2, module fetching through hashicorp/go-getter/v2, and parts of hashicorp/terraform are vendored directly since Terraform stopped exposing a usable library surface after v0.15.3. Cloud backend and auth support comes from the AWS SDK (v1 and v2), Azure SDK, and Google Cloud storage/auth libraries; getsops/sops handles encrypted values; hashicorp/go-plugin backs an external “engine” plugin system; and charm.land’s bubbletea/bubbles/lipgloss/glamour stack renders terminal UI. A separate Astro+Bun+Tailwind site under docs/ serves the public documentation, decoupled from the Go binary.

Code Quality The repository contains roughly 589 _test.go files and a correspondingly deep CI setup: dedicated integration-test, oidc-integration-test, sandboxed-test, fuzz, flake, and coverage-compare/coverage-weekly workflows alongside lint, go-fix-check, go-mod-tidy-check, gopls, markdownlint, and codespell jobs. Errors are routed through dedicated errorconfig and multierror internal packages rather than left as ad hoc panics, and a strict package gates opt-in breaking changes behind explicit flags/version signaling. Package layout follows conventional Go naming with one concern per internal/ directory.

What Makes It Unique Terragrunt’s differentiator isn’t the Terraform/OpenTofu execution itself but the DX layered on top of it: include blocks give genuine config inheritance that plain Terraform has no equivalent for, dependency blocks read a remote module’s real outputs instead of requiring hand-copied variable values, and run --all turns a directory of otherwise-independent modules into an ordered, dependency-aware batch operation. Combined with automatic backend generation and a DAG visualizer, it removes most of the manual bookkeeping that large multi-module Terraform/OpenTofu setups otherwise require by hand.