What is Terragrunt and why you need it

#terragrunt #terraform #hcl

the multi-env problem

With plain Terraform, managing multiple environments means duplicating config - same modules, different variable files, same backend boilerplate repeated everywhere.

environments/
├── dev/
│   ├── main.tf        # copy
│   ├── variables.tf   # copy
│   └── backend.tf     # copy with different key
├── staging/
│   ├── main.tf        # copy
│   ├── variables.tf   # copy
│   └── backend.tf     # copy with different key
└── prod/
    ├── main.tf        # copy
    ├── variables.tf   # copy
    └── backend.tf     # copy with different key

Any change to the module requires updating all three.

what Terragrunt does

Terragrunt is a thin wrapper around Terraform that adds:

DRY backend config - define once, inherit everywhere
dependency blocks - wire modules together without a monolith
run-all - apply/plan/destroy across multiple modules in one command
generate blocks - auto-generate files (provider configs, backend configs)
mock_outputs - unblock plan in CI when dependencies haven't been applied yet

terraform vs terragrunt

	Terraform	Terragrunt
Backend config	per-module	inherited from root
Multi-module apply	manual	`run-all`
Module wiring	`terraform_remote_state`	`dependency` block
DRY config	variables only	full config inheritance

installation

asdf plugin-add terragrunt
asdf install terragrunt 0.67.0
asdf local terragrunt 0.67.0

or developer.hashicorp.com/terraform/tutorials/automation/terragrunt

what the structure looks like

Instead of duplicated .tf files, you get one root.hcl and small terragrunt.hcl files per unit that only define what's different:

root.hcl
environments/
├── dev/
│   ├── vpc/
│   │   └── terragrunt.hcl   # 5 lines: include + inputs
│   ├── rds/
│   │   └── terragrunt.hcl
│   └── eks/
│       └── terragrunt.hcl
└── prod/
    ├── vpc/
    │   └── terragrunt.hcl
    ├── rds/
    │   └── terragrunt.hcl
    └── eks/
        └── terragrunt.hcl

A typical leaf terragrunt.hcl:

include "root" {
  path = find_in_parent_folders("root.hcl")
}

terraform {
  source = "git::https://github.com/org/tf-modules.git//vpc?ref=v1.2.0"
}

inputs = {
  name       = "prod-vpc"
  cidr_block = "10.0.0.0/16"
}