Terragrunt: A Thin Wrapper for DRY Terraform

Why it exists

As Terraform projects grow, managing them becomes complex. You end up with repeated configurations, especially for backend state, and running commands across multiple modules is manual. Terragrunt exists to solve these structural problems by providing a thin wrapper around Terraform to keep your code DRY (Don't Repeat Yourself).

The mental model

Think of Terragrunt as a smart orchestrator for Terraform. You continue to write standard Terraform/OpenTofu code, but you add a terragrunt.hcl file to control the execution environment. You then run terragrunt apply instead of terraform apply, letting Terragrunt handle the boring, repetitive tasks for you.

How it works

To start, you add a terragrunt.hcl file to your Terraform project directory. You then use the terragrunt CLI for all operations. Terragrunt reads your terragrunt.hcl file, performs any configured pre-steps, and then calls the underlying terraform or tofu binary with the appropriate arguments. The simplest benefit, called Auto-init, is that Terragrunt automatically runs init for you if necessary, so you no longer have to run it manually before a plan or apply.

When to use it

Use Terragrunt when you want to manage your Terraform/OpenTofu projects more effectively. It's particularly useful as your infrastructure scales, offering features for GitOps pipelines, drift detection, automated updates, and managing stacks of modules. It helps you define configurations once and reuse them across multiple environments.

When not to use it

For a very small, single-module project with no shared state or multiple environments, Terragrunt might be overkill. If you're just learning Terraform, adding another layer of abstraction can be confusing. Master Terraform's core concepts first.

One canonical example

An engineer is working on a Terraform project. To apply changes, they must remember to run terraform init before terraform apply. By adding an empty terragrunt.hcl file to the project, they can now simply run terragrunt apply. Terragrunt's Auto-init feature detects that the project isn't initialized and automatically runs terraform init before executing the apply command, simplifying the workflow.