Terragrunt

The problem it solves

Terraform at scale produces repetition. Every module needs backend configuration, provider blocks and the same variables threaded through, and keeping dev, staging and production consistent means copying those blocks and remembering to change them in every place when something moves.

Terragrunt wraps Terraform and generates that configuration from a hierarchy of terragrunt.hcl files. Backend settings live once at the root and apply downward. An environment becomes a directory with the differences spelled out, not a copy of everything with three lines changed.

run-all

The second capability is orchestration. terragrunt run-all apply walks a tree of modules, works out the dependency order from declared dependencies, and applies them in sequence. A VPC applies before the subnets that reference it without anyone sequencing it by hand.

For infrastructure split across dozens of state files — which is the usual advice, to limit blast radius — this is the difference between one command and a runbook.

Working with OpenTofu

Terragrunt supports both Terraform and OpenTofu, which matters for teams that moved after HashiCorp's licence change. The wrapper is largely agnostic to which binary sits underneath.

The cost of a layer

Terragrunt sits between you and Terraform, and when something breaks the error can come from either. Debugging means knowing whether you are looking at a Terragrunt problem, a generated-configuration problem, or a Terraform problem — and the generated config is not what you wrote, so reading it is an extra step.

Teams adopting it should also check what they actually need. Native Terraform has absorbed some of the original motivation over the years, and if the pain is only backend boilerplate in a handful of modules, the abstraction may cost more than it saves. The case gets strong around the point where module count reaches the dozens and dependency ordering stops being manageable manually.

Gruntwork maintains it alongside commercial offerings, but Terragrunt itself is MIT licensed with no paid tier gating its features.

What the layout looks like

A typical repository separates module definitions from environment instantiations. Modules live in one tree, each environment is a directory of terragrunt.hcl files pointing at those modules with its own inputs, and a root terragrunt.hcl holds the backend configuration and provider generation that every child inherits.

Adding a staging environment then means a directory and a set of input values, not a copy of the module tree. The difference compounds: with three environments and twenty modules, the copy-paste approach has sixty places where backend configuration can drift and the Terragrunt approach has one.

Dependency declarations

dependency blocks make ordering explicit and also pass outputs between modules, so a subnet module reads the VPC id from the VPC module's state rather than having it threaded through as a hardcoded variable. mock_outputs keep plan working before dependencies exist, which is what makes planning a whole environment from scratch possible.

Those mocks are also a common source of confusion — a plan that succeeds against mock values can still fail on apply when the real outputs differ in shape.