terragrunt command: options and 10 examples

What it does

With many environments (dev, staging, prod) and many parts (network, cluster, database) plain Terraform gets repetitive: the same backend block and variables again and again. terragrunt puts the shared parts in a root terragrunt.hcl; every folder only says which module to use and its inputs.

terragrunt run-all plan runs plan in every folder in the right order (dependencies first).

How to write it

terragrunt COMMAND [OPTIONS]
terragrunt run-all COMMAND

Main parts

Commands

plan / apply / destroy: Like Terraform, for this folder.
run-all plan|apply: In all folders below, in dependency order.
init: Init with the generated backend.
output / validate / fmt: Like Terraform.
hclfmt: Format terragrunt.hcl files.
graph-dependencies: Show the order of modules.
render-json: Show the final config.

Options 6

Most used

Options

--terragrunt-non-interactive: No questions (CI).
--terragrunt-working-dir DIR: Run in another folder.
--terragrunt-include-dir GLOB: Only these folders in run-all.
--terragrunt-parallelism N: Limit parallel modules.
--terragrunt-source PATH: Use a local module copy (development).
TERRAGRUNT_TFPATH=tofu: Use OpenTofu instead of Terraform.

Examples 10

$ run as a normal user# run as root (or with sudo)

1The folder layout

$tree live
live/
├── terragrunt.hcl
├── prod
│   ├── network/terragrunt.hcl
│   └── aks/terragrunt.hcl
└── dev
    ├── network/terragrunt.hcl
    └── aks/terragrunt.hcl

2The root file: one backend for all

$cat live/terragrunt.hcl
remote_state {
  backend = "azurerm"
  generate = { path = "backend.tf", if_exists = "overwrite" }
  config = {
    resource_group_name  = "rg-tfstate"
    storage_account_name = "sttfstateacme"
    container_name       = "tfstate"
    key                  = "${path_relative_to_include()}/terraform.tfstate"
  }
}

3One module with its inputs

$cat live/prod/aks/terragrunt.hcl
include "root" { path = find_in_parent_folders() }
terraform { source = "git::https://github.com/acme/tf-modules.git//aks?ref=v2.1.0" }
dependency "network" { config_path = "../network" }
inputs = { subnet_id = dependency.network.outputs.subnet_id, node_count = 3 }

4Plan one module
```
$cd live/prod/aks
$terragrunt plan
```
5Plan a whole environment
```
$cd live/prod
$terragrunt run-all plan
```

6Apply everything in CI

$terragrunt run-all apply --terragrunt-non-interactive

7Use OpenTofu
```
$TERRAGRUNT_TFPATH=tofu terragrunt plan
```
8See the order
```
$terragrunt graph-dependencies
```

9Test a local module change

$terragrunt plan --terragrunt-source ../../../../tf-modules//aks

10Format all files
```
$terragrunt hclfmt
```

Watch out

run-all apply and run-all destroy change many modules at once — review the plans first.
Pin module sources with ?ref=TAG.

Files

terragrunt.hcl: Config of a folder (and the root).
.terragrunt-cache/: Downloaded code; add to .gitignore.

Exit codes

`0`	OK.
`1`	Error.

`terragrunt`

What it does

How to write it

Main parts

Commands

Options 6

Options

Examples 10

1The folder layout

2The root file: one backend for all

3One module with its inputs

4Plan one module

5Plan a whole environment

6Apply everything in CI

7Use OpenTofu

8See the order

9Test a local module change

10Format all files

Watch out

Files

Exit codes

Full manual

terragrunt

What it does

How to write it

Main parts

Commands

Options 6

Options

Examples 10

1The folder layout

2The root file: one backend for all

3One module with its inputs

4Plan one module

5Plan a whole environment

6Apply everything in CI

7Use OpenTofu

8See the order

9Test a local module change

10Format all files

Watch out

Files

Exit codes

Related commands

Used in these lessons

Full manual

`terragrunt`