Terragrunt — DRY Orchestration Layer for Terraform & OpenTofu

What it is

Terragrunt is a thin orchestration layer built by Gruntwork that wraps Terraform and OpenTofu. It solves the DRY problem in infrastructure-as-code by letting you define shared configurations once and inherit them across environments. It also manages remote state backend configuration, dependency ordering between modules, and parallel execution of independent stacks.

Terragrunt is aimed at platform and DevOps engineers managing multi-account, multi-region infrastructure. If you find yourself copying the same backend configuration and provider blocks across dozens of Terraform root modules, Terragrunt eliminates that duplication.

How it saves time or tokens

Without Terragrunt, each Terraform root module needs its own backend config, provider config, and variable definitions -- even when they share 90% of the same values. Terragrunt's include and generate blocks let you define these once in a parent terragrunt.hcl and inherit them in child modules. When you change a shared setting, you update one file instead of fifty.

Dependency management is another time saver. Terragrunt reads dependency blocks to determine execution order and runs independent modules in parallel, reducing total apply time for large infrastructure changes.

How to use

1. Install Terragrunt:

brew install terragrunt

1. Create a root terragrunt.hcl with shared configuration:

remote_state {
  backend = "s3"
  config = {
    bucket = "my-terraform-state"
    key    = "${path_relative_to_include()}/terraform.tfstate"
    region = "us-east-1"
  }
}

1. In each module directory, create a terragrunt.hcl that includes the parent:

include "root" {
  path = find_in_parent_folders()
}

1. Run all modules:

terragrunt run-all apply

Example

# environments/prod/vpc/terragrunt.hcl
include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "../../../modules/vpc"
}

inputs = {
  cidr_block = "10.0.0.0/16"
  env_name   = "prod"
}

dependency "account" {
  config_path = "../account"
}

This module inherits remote state config from the root, sources the VPC Terraform module, passes environment-specific inputs, and declares a dependency on the account module.

Related on TokRepo

• DevOps tools -- Explore other infrastructure and deployment automation tools
• Automation tools -- Browse tools for CI/CD and workflow automation

Common pitfalls

• Terragrunt adds a layer of indirection. Debugging Terraform errors requires understanding both Terragrunt's generated configs and the underlying Terraform state. Use terragrunt render-json to see the final configuration.
• run-all commands can be dangerous. Running terragrunt run-all destroy without the --terragrunt-exclude-dir flag will destroy all infrastructure in the tree. Always use run-all plan before run-all apply.
• Terragrunt caches downloaded modules in .terragrunt-cache. This directory can grow large over time. Add it to .gitignore and clean it periodically.