skip to content

Terragrunt Wrapper

Terragrunt wraps Terraform or OpenTofu to keep many small root modules DRY and run them in dependency order. Interviewers ask what include and dependency buy, and when plain root modules are enough.

part ofTerraformread it →
on this pageshow

questions

6

In Terragrunt, what is a unit, and what happens when you run `terragrunt apply` in a directory whose `terragrunt.hcl` sets `terraform.source` and `inputs`?

level: juniorimportance: must knowfreq 46%

answer

  1. smallest deployable directory
  2. a URL plus some values
  3. code lands in a cache folder
  4. values travel as environment variables

basics

~20 s

A Terragrunt unit is a directory with a terragrunt.hcl file, the smallest thing Terragrunt deploys. Terragrunt downloads the module named in terraform.source into a cache folder, then runs Terraform there with inputs passed as TF_VAR_ environment variables.

solid answer

~30 s

A unit is a directory containing a `terragrunt.hcl`, the smallest deployable entity in Terragrunt. That file usually holds no `.tf` code: a `terraform { source = ... }` block names a versioned module and `inputs` sets its variables. On `terragrunt apply`, Terragrunt downloads the source into `.terragrunt-cache`, copies the unit directory's files in, and runs `apply` in that temporary folder, passing each input as a `TF_VAR_` environment variable. So `live/prod/us-east-1/vpc` and `live/stage/us-east-1/vpc` can share one module and differ only in the `ref` and the inputs, and promoting a change means moving the `ref` from one environment to the next.

code

bash · 4 lines
bash
cd live/stage/us-east-1/vpc
terragrunt plan
terragrunt apply --source ../../../../modules//vpc
terragrunt plan --source-update

go deeper

for a junior

Recall the one-line definition: a unit is a directory with a terragrunt.hcl, usually just a module URL and its inputs. Be able to say that Terraform still does the work.

for a middle

Walk through the run: download into .terragrunt-cache, copy the unit's files, generate files, run Terraform with TF_VAR_ variables. Explain what that temporary folder does to relative paths.

for a senior

Show you have been caught by the cache: a moving ref stays stale until --source-update, so production units should pin immutable tags. Mention that inputs lose their types at the environment-variable boundary.

for a principal

Treat the module URL and ref as the promotion contract between environments. The question for a lead is who may move a production ref and how that review differs from a change to the module itself.

## What a unit is A **unit** in Terragrunt is a directory that contains a `terragrunt.hcl` file. Terragrunt's docs call it the smallest deployable entity: you can operate on one unit without touching the others. Terragrunt is a wrapper, not a replacement. It prepares a working directory and then calls Terraform or OpenTofu, which still do the planning and applying. The usual layout separates two kinds of code: - **A modules repository** holds ordinary Terraform modules. Anything that differs between environments is exposed as an input variable. - **A live repository** holds one directory per deployed thing, such as `live/prod/us-east-1/vpc`, each with only a small `terragrunt.hcl` in it. Two settings do most of the work: - **`terraform.source`** names the module. It uses the same syntax as a Terraform module source: `//` separates the repository from the subdirectory, and `?ref=` pins a tag, commit or branch. - **`inputs`** is a map of values for that module's variables. ```hcl # live/prod/us-east-1/vpc/terragrunt.hcl terraform { source = "git::[email protected]:example-org/modules.git//vpc?ref=v1.4.0" } inputs = { name = "prod-us-east-1" cidr = "10.10.0.0/16" } ``` ## What `terragrunt apply` does With a remote `source` set, one run goes like this: 1. Terragrunt downloads the code into `.terragrunt-cache`, the default download folder, which belongs in `.gitignore`. It fetches everything before the `//`, so relative paths between modules in that repository keep working. 2. It copies the files from the unit's directory into that temporary folder. 3. It writes any file a `generate` block asks for, such as a `provider.tf`. 4. It runs `apply` in the temporary folder, passing each entry of `inputs` as a `TF_VAR_<name>` environment variable with a JSON-encoded value. ## How a unit compares with a plain root module | | Plain root module | Terragrunt unit | |---|---|---| | Terraform code in the directory | `.tf` files calling modules | Usually none | | Module version | Set on each `module` block | `?ref=` in `terraform.source` | | Variable values | `.tfvars` files or `-var` | `inputs`, sent as `TF_VAR_` variables | | Where Terraform runs | That directory | A folder under `.terragrunt-cache` | Because a unit is little more than a URL and some inputs, promotion is a one-line change: `stage` moves to `?ref=v1.5.0` while `prod` stays on `v1.4.0`, and rolling back means moving the `ref` back. A unit does not have to use a remote source. If `main.tf` sits beside `terragrunt.hcl`, Terragrunt runs in the current directory, which is how existing root modules are converted. ## Traps from the temporary folder - **A stale cache.** A remote source is downloaded once and then reused until its URL changes. A moving ref such as `?ref=main` does not pick up new commits until `--source-update` deletes the folder and downloads again. Immutable tags avoid the question. - **Relative paths.** Terraform runs in the temporary folder, so a relative `-var-file` on the command line resolves from there. Use an absolute path on the CLI and `get_terragrunt_dir()` inside `terragrunt.hcl`. - **Lost types.** Inputs cross as environment variables, so type information is lost at the boundary. The module's variable needs a proper type constraint. - **Local development.** `--source` or `TG_SOURCE` overrides `terraform.source` with a local checkout, for example `terragrunt apply --source ../../../../modules//vpc`, so you need not edit the `ref` to test a change. - **Which binary runs.** Terragrunt looks for `tofu` on `PATH` by default and uses `terraform` when that is the only one installed. Pin the choice with `--tf-path`, `TG_TF_PATH` or the `terraform_binary` attribute. - **The lock file.** `.terraform.lock.hcl` is generated next to `terragrunt.hcl`, so commit it there even though the code runs from the cache folder. Everyday commands stay short: `terragrunt plan` and `terragrunt apply` are shortcuts for `terragrunt run plan` and `terragrunt run apply`, so day-to-day use on a single unit looks much like plain Terraform. ## Why per-environment units instead of CLI workspaces Each environment is a directory with its own `terragrunt.hcl`, so `prod` and `stage` differ visibly in a diff, and a shared root file usually gives each unit its own state path. Terragrunt's own guide encourages you not to use CLI workspaces with it, on the grounds that it already manages state isolation, and `workspace` gets no command shortcut: it has to go through `terragrunt run -- workspace ls`.

  • Why does `terragrunt workspace ls` fail, and what do you run instead?
    Since v0.88.0 Terragrunt no longer forwards unknown commands to Terraform or OpenTofu. Common commands such as `plan` and `apply` keep shortcuts, but `workspace` has none, so you run `terragrunt run -- workspace ls`. Its guide discourages workspaces anyway, because Terragrunt handles state isolation between units.
  • Where does a unit's `.terraform.lock.hcl` end up when its code comes from a remote source?
    Terragrunt generates it next to the `terragrunt.hcl`, not only in the cache folder, and you should check it into version control. That way provider selections are reviewed with the unit, even though `.terragrunt-cache` itself stays out of git.
  • What makes a unit different from an included file such as `root.hcl`?
    A unit is a directory with a file named `terragrunt.hcl` that Terragrunt can deploy. `root.hcl` is partial configuration that units merge in with `include`. It deploys nothing, which is why the recommended name is not `terragrunt.hcl`: a directory scan should not mistake it for a unit.

  • A Terragrunt unit must contain its own main.tf file to be deployable.
  • Terragrunt replaces Terraform and works out the plan by itself.
  • Terragrunt writes inputs into a terraform.tfvars file for Terraform to read.
  • Terragrunt fetches the newest commit of a branch ref on every run.
  • A relative path on the command line resolves from where you ran Terragrunt.
open as a page

In Terragrunt, how do `include` and a shared `root.hcl` keep backend and provider settings DRY, and what do `remote_state` and `generate` each do?

level: middleimportance: must knowfreq 48%

basics

~20 s

Each Terragrunt unit's include block merges a shared root.hcl, so backend and provider settings live once. remote_state configures the backend, with a per-unit key from path_relative_to_include(); generate writes any file, such as provider.tf, before Terraform runs.

open as a page

In Terragrunt, what does `run --all apply` do across the units under your working directory, and what makes it riskier than applying one unit?

level: middleimportance: should knowfreq 42%

basics

~20 s

Terragrunt's run --all apply builds a dependency graph of the units under the current directory and applies them in order, in parallel where it can. It adds -auto-approve silently, so the working directory is the blast radius.

open as a page

A Terragrunt plan for `live/dev/us-east-1/app` shows `vpc-mock` as its VPC ID because `../vpc` was never applied. What is happening, and how do you stop that value reaching a real apply?

level: seniorimportance: should knowfreq 37%

basics

~20 s

The dependency block found no outputs in the unapplied vpc unit, so Terragrunt substituted mock_outputs. With no allow-list those mocks work for every command, so set mock_outputs_allowed_terraform_commands and never apply a saved plan built on mocks.

open as a page

Your team runs about forty Terraform root modules with hand-copied backend and provider blocks. How would you decide whether to adopt Terragrunt, and what lock-in would you accept?

level: principalimportance: should knowfreq 33%

basics

~20 s

Adopt Terragrunt when repetition and ordering across many similar roots cost more than a second tool; keep plain root modules and CI when roots are few or independent. The lock-in sits in orchestration and configuration, not in state.

open as a page

In Terragrunt, how do implicit stacks differ from explicit stacks defined in `terragrunt.stack.hcl`, and when is the generated form worth it?

level: middleimportance: nice to knowfreq 27%

basics

~20 s

An implicit Terragrunt stack is a directory tree of hand-written units. An explicit stack is a terragrunt.stack.hcl blueprint that generates its units into .terragrunt-stack. Explicit pays off when the same set of units repeats across environments.

open as a page