Terragrunt — DRY Orchestration Layer for Terraform & OpenTofu

Introduction

Terragrunt sits in front of terraform (or tofu) and solves the three biggest pain points of infrastructure-at-scale: repeated backend config, duplicated provider blocks, and orchestrating dozens of root modules across accounts and regions. It is the de-facto tool for Gruntwork-style "live infrastructure" repositories.

What Terragrunt Does

• Generates backend.tf and provider.tf files from a single root terragrunt.hcl
• Expresses dependencies between root modules (dependency blocks)
• Runs run-all plan/apply/destroy across many modules in dependency order
• Fetches remote source modules via Git, HTTP, or registry URLs
• Supports hooks, locals, include, and arbitrary HCL for custom logic

Architecture Overview

Terragrunt is a thin Go CLI that reads terragrunt.hcl files, generates the final Terraform config in a temporary directory, and shells out to terraform/tofu. Remote state backends (S3, GCS, Azure) are created on the fly if missing. Dependency graphs are walked in topological order with configurable concurrency. The tool itself is stateless — all state lives in Terraform backends.

Self-Hosting & Configuration

• Drop-in: keep existing .tf modules, add terragrunt.hcl wrappers
• include { path = find_in_parent_folders() } pulls shared config into leaves
• Use dependency { config_path = "../vpc" } to wire outputs between stacks
• Hooks: before_hook, after_hook, error_hook for policy or notifications
• CI: set TERRAGRUNT_PARALLELISM and run terragrunt run-all apply --terragrunt-non-interactive

Key Features

• DRY backends and providers across hundreds of modules
• Dependency-aware run-all for whole-estate plans and applies
• Works with Terraform and OpenTofu (via TERRAGRUNT_TFPATH=tofu)
• First-class support for Gruntwork's Infrastructure-as-Code Library
• Configurable parallelism for fast full-estate plans

Comparison with Similar Tools

• Terraform workspaces — built-in, but one state per workspace, no cross-module deps
• Terramate — similar goal, uses code generation; different DSL
• Atlantis — PR automation, not DRY orchestration; pairs with Terragrunt
• Pulumi — different language and state model entirely
• Spacelift / env0 — commercial stacks with orchestration + UI

FAQ

Q: Does Terragrunt work with OpenTofu? A: Yes. Set TERRAGRUNT_TFPATH=tofu (or terraform_binary = "tofu" in HCL).

Q: Can I migrate gradually? A: Yes — terragrunt can wrap one module at a time; untouched modules keep using raw Terraform.

Q: How are dependencies passed between stacks? A: dependency { config_path = "../vpc" } reads that module's outputs and exposes them as inputs.

Q: Is state locking handled? A: Yes. The generated S3/DynamoDB backend uses the same locking you get with native Terraform.

Sources

• https://github.com/gruntwork-io/terragrunt
• https://terragrunt.gruntwork.io