Terragrunt Configuration, In Depth: Every Block, Function & Hook in terragrunt.hcl

You already know why Terragrunt exists — to delete the copy-pasted backend, provider, and input wiring that breeds across environments — and you have stood up a live tree, wired a couple of dependency blocks, and run run --all against it. This lesson is the other half of that knowledge: a precise, field-by-field reference for the terragrunt.hcl configuration language itself. Not “here is the block you usually use,” but every block Terragrunt understands, every attribute inside each block, what its default is, what each accepted value does, and the gotcha that bites people. The same exhaustive treatment for the built-in function catalogue — exact signatures, every argument, what each returns — and for hooks, the errors retry/ignore machinery, and the generate-versus-init mechanics that make the magic work.

Think of this as the terragrunt.hcl equivalent of a language spec written for working engineers. The two companion lessons stay deliberately at a working altitude: Terragrunt Fundamentals teaches the blocks well enough to be productive, and Scaling Terragrunt Monorepos teaches orchestration at 200 units. Neither enumerates every attribute, because that would bury the narrative. Here we do exactly that enumeration, so when you hit include_in_copy, mock_outputs_merge_strategy_with_state, if_disabled, the errors block, or read_tfvars_file in a real repository — or an interviewer asks “what does path_relative_from_include return and when would you use it?” — you have the complete map. Everything targets a current Terragrunt release (2026, on the road to 1.0), Terraform 1.9+/OpenTofu, and works identically against either engine.

Learning objectives

By the end of this lesson you will be able to:

• Name every block that is valid in a terragrunt.hcl (and a terragrunt.stack.hcl) and state what each one is for.
• Recite the full attribute set of the heavy blocks — terraform, remote_state, generate, include, dependency — including the less-known options (include_in_copy, copy_terraform_lock_file, disable_dependency_optimization, mock_outputs_merge_strategy_with_state, if_disabled, hcl_fmt).
• Write hooks (before_hook, after_hook, error_hook) using every attribute (commands, execute, working_dir, run_on_error, suppress_stdout, if, on_errors).
• Use the modern errors block (retry/ignore) and explain why it replaced the deprecated retryable_errors/skip attributes.
• Use the built-in function catalogue correctly — path, repo, env, AWS, and config-reading functions — with exact arguments.
• Distinguish the newer config blocks — feature, exclude, unit/stack — and place Terragrunt Stacks against Terraform/OpenTofu Stacks.
• Understand generate vs init: when files are written, the if_exists/if_disabled collision rules, and what ends up in the working directory.

Prerequisites

This is an advanced reference, so it assumes the working knowledge from Terragrunt Fundamentals: DRY Configurations, Remote State & Dependencies — what a unit is, the live/modules split, that remote_state and generate write .tf files Terragrunt then hands to the engine, and the basic shape of include and dependency. It also assumes solid Terraform: HCL syntax (blocks, arguments, expressions, for, the type system), backends and state locking, and module sources/versioning. If the orchestration side is what you are after — the DAG, run --all/run --graph, --filter-affected, parallelism, CI — read Scaling Terragrunt Monorepos with Dependency Graphs and run-all instead; this lesson deliberately stays inside the config file and points there for execution. In the KloudVin Terraform & DevOps Zero-to-Hero course this sits in the Terragrunt module as the deep reference between the fundamentals and the multi-environment capstone. You need only a free local toolchain — terragrunt plus terraform or tofu — and the hands-on lab runs entirely on the local backend, so it costs nothing and touches no cloud.

Core concepts: how Terragrunt reads a config

Before the field tables, hold three mechanics in your head, because every attribute below makes sense only against them.

1. Terragrunt parses HCL, then shells out. A terragrunt.hcl is HCL — same lexer, same expression language, same type system as Terraform. Terragrunt evaluates it (resolving includes, locals, functions, and dependency outputs), uses the result to prepare a working directory (download the module named by source, write generated files, fetch dependency outputs into -var values), and then runs terraform/tofu inside that directory. The config language is therefore a preparation language; it never provisions anything itself.

2. The working directory is a copy, in a cache. When terraform { source = ... } points at a module, Terragrunt copies that module into .terragrunt-cache/<hash>/<hash>/ and runs there — not in your unit directory. This is why generated backend.tf/provider.tf land in the cache, why include_in_copy/exclude_from_copy exist (to control what extra files come along), and why get_terragrunt_dir() (your unit) differs from get_working_dir() (the cache).

3. Evaluation order matters. locals are computed first and can read functions and other locals. include brings in a parent and (with expose = true) its evaluated contents. dependency blocks run the target unit’s output to fetch values. inputs is assembled last and exported as TF_VAR_*. Knowing this order explains why you can reference local.x in inputs but must use dependency.x.outputs.* (not a local) for cross-unit values, and why a mock_outputs exists at all (the producer may have no state yet when its outputs are read).

A quick map of the whole vocabulary, grouped by what it does, before we take each in turn:

The terraform block: every attribute

The terraform block tells a unit which module to run and wraps that module with hooks and extra CLI arguments. It is the one block almost every unit has.

extra_arguments — its own attributes

extra_arguments is a named sub-block that conditionally appends CLI flags. It is how you attach a -var-file to only plan/apply, or a default -lock-timeout everywhere.

terraform {
  source = "git::git@github.com:frachtline/infra-modules.git//rds?ref=v1.4.0"

  extra_arguments "common_vars" {
    commands           = get_terraform_commands_that_need_vars()  # all var-taking cmds
    required_var_files = ["${get_parent_terragrunt_dir()}/common.tfvars"]
    optional_var_files = ["${get_terragrunt_dir()}/override.tfvars"]
    arguments          = ["-lock-timeout=20m"]
  }
}

Hooks: before_hook, after_hook, error_hook — exhaustively

Hooks run arbitrary shell commands around a Terraform command. They live inside the terraform block. Use them for cross-cutting concerns: a tflint/policy check before plan, a notification after apply, a diagnostic dump on failure. All three kinds share the same attributes (with on_errors being meaningful only on error_hook).

terraform {
  source = "../../../modules//app"

  # Lint the module before any plan/apply; suppress its chatter.
  before_hook "tflint" {
    commands        = ["plan", "apply"]
    execute         = ["tflint", "--chdir", get_terragrunt_dir()]
    suppress_stdout = true
  }

  # Notify only on a successful apply (run_on_error defaults to false).
  after_hook "notify_success" {
    commands     = ["apply"]
    execute      = ["bash", "-c", "echo applied ${path_relative_to_include()}"]
    run_on_error = false
  }

  # Always run cleanup after apply, success or failure.
  after_hook "cleanup" {
    commands     = ["apply"]
    execute      = ["bash", "-c", "rm -f /tmp/${path_relative_to_include()}.lock"]
    run_on_error = true
  }

  # Capture diagnostics only when plan/apply errors.
  error_hook "diagnose" {
    commands  = ["plan", "apply"]
    execute   = ["bash", "-c", "echo 'failed — dumping TF_LOG context'"]
    on_errors = [".*"]
  }
}

Two subtleties. First, multiple hooks of the same kind run in declaration order (and before_hooks all run before the command, after_hooks all after). Second, hooks execute arbitrary shell during plan — that is power and risk; treat a terragrunt.hcl’s hooks as code to review, and never run untrusted Terragrunt repositories blindly.

remote_state: generate the backend once

remote_state declares the backend once (usually in the root) and writes a backend block into every unit at init time, computing the per-unit state key from the path. It is the block that deletes backend duplication.

# live/root.hcl
remote_state {
  backend      = "s3"
  disable_init = false                     # let TG create the bucket/table on first run
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"      # manage only TG-generated files
  }
  config = {
    bucket       = "frachtline-tfstate-${local.env.locals.environment}"
    key          = "${path_relative_to_include()}/terraform.tfstate"   # path IS the key
    region       = "ap-south-1"
    encrypt      = true
    use_lockfile = true                      # S3-native locking; no DynamoDB table
  }

  # Optional: OpenTofu state encryption, defined once for every unit.
  encryption = {
    key_provider = "aws_kms"
    kms_key_id   = local.account.locals.state_kms_key_arn
  }
}

The headline is key = "${path_relative_to_include()}/terraform.tfstate": the unit’s path relative to the included parent becomes its unique state key, so live/prod/vpc lands at prod/vpc/terraform.tfstate with zero hard-coding. The fundamentals lesson covers why this DRY-s the backend; the point here is the full attribute set — particularly disable_init (stop auto-bootstrap), disable_dependency_optimization (a stale-output escape hatch), and encryption (DRY state encryption), which the working-altitude lessons do not enumerate.

generate: write any file — every attribute

remote_state is really a specialised generate. The general block writes any file into the working directory at runtime — most commonly the provider, so it too lives in one place. This block has the richest collision/lifecycle surface, and it is where people get surprised.

# live/root.hcl  (continued)
generate "provider" {
  path              = "provider.tf"
  if_exists         = "overwrite_terragrunt"
  if_disabled       = "remove_terragrunt"
  comment_prefix    = "# "
  disable_signature = false
  contents          = <<-EOF
    provider "aws" {
      region = "${local.env.locals.aws_region}"
      assume_role { role_arn = "${local.account.locals.role_arn}" }
      default_tags { tags = { managed_by = "terragrunt", env = "${local.env.locals.environment}" } }
    }
    terraform {
      required_providers {
        aws = { source = "hashicorp/aws", version = "~> 5.60" }
      }
    }
  EOF
}

The two attributes worth memorising beyond the fundamentals are if_disabled and disable: together they let you turn a generated file off and clean up the stale file it left behind — without that pair, disabling a generate block leaves an orphaned .tf in the cache that can break the next run. hcl_fmt is the other quiet one: it formats generated HCL so a terragrunt hclfmt --check in CI does not trip over machine-written files.

generate vs init: when files actually appear

A frequent confusion: when do generated files get written, and where? The sequence on any command that prepares a working dir (init, plan, apply, …):

1. Terragrunt resolves config and copies the source module into .terragrunt-cache/<hash>/<hash>/.
2. It writes every generate block’s file (and the remote_state-generated backend.tf) into that cache copy, applying if_exists/if_disabled rules.
3. It runs terraform init in the cache (creating backend resources unless disable_init), then your command.

So generated files live in the cache, not your unit directory — which is why you .gitignore .terragrunt-cache/ and why a remote_state with no generate attribute still works (it passes backend settings as -backend-config CLI flags to init rather than writing a file). If you want the backend as an on-disk file you can read, use the generate form; if you only need init to succeed, the flag form is enough.

include: inheriting and merging parents

include is how a unit pulls in shared parent config (the root, and often an env/region layer) so it does not repeat backend, provider, or common inputs. A unit may have several named includes.

# live/prod/rds/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}
include "env" {
  path           = find_in_parent_folders("env.hcl")
  expose         = true            # so we can read include.env.locals.*
  merge_strategy = "deep"          # deep-merge env inputs under root inputs
}

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

inputs = {
  instance_class = "db.r6g.large"  # overrides any inherited default (child wins)
}

The three things the fundamentals lesson does not spell out: the default merge_strategy is shallow (not no_merge), expose is what makes a parent’s locals visible (without it you can only inherit its emergent config, not read its values), and you can layer multiple includes — a root plus an env plus a region — each merged in turn, which is the idiomatic way to build per-account/per-region/per-env configuration without repetition.

dependency and dependencies: wiring units

These two build the DAG and pass data. The distinction is load-bearing: dependencies is ordering only; dependency is ordering plus the target’s outputs. The orchestration of that graph — how run --all walks it, mock_outputs_merge_strategy_with_state at scale, run --graph — lives in the monorepo lesson; here is the complete attribute table for the blocks themselves.

dependencies (plural) has exactly one attribute:

dependency "<name>" (singular) exposes the target’s outputs as dependency.<name>.outputs.* and accepts:

# live/prod/app/terragrunt.hcl
dependency "vpc" {
  config_path = "../vpc"
}
dependency "rds" {
  config_path  = "../rds"
  mock_outputs = { endpoint = "mock-endpoint:5432" }
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
  mock_outputs_merge_strategy_with_state  = "shallow"
}

# Ordering only — wait for the IAM baseline, consume nothing from it.
dependencies {
  paths = ["../../_baseline/iam"]
}

inputs = {
  vpc_id      = dependency.vpc.outputs.vpc_id
  db_endpoint = dependency.rds.outputs.endpoint
}

The attributes the working lessons gloss: enabled (drop an edge conditionally — pairs beautifully with feature flags), skip_outputs (“always mock,” distinct from mock_outputs’s “mock only as fallback”), and the deprecation of the boolean mock_outputs_merge_with_state in favour of the three-valued mock_outputs_merge_strategy_with_state. Mocks are for shape (so validate/plan parse), never for values you depend on at apply time.

inputs and locals

Two small but constant blocks.

inputs is a single map (not a labelled block) that Terragrunt converts into TF_VAR_* environment variables for the module — the Terragrunt equivalent of a .tfvars. Inputs from an included parent and from the unit merge per the include’s merge_strategy, child winning. Because it becomes env vars, every value must be expressible as a string/JSON — complex objects are JSON-encoded automatically.

locals declares local values, exactly like Terraform’s locals, evaluated before the rest of the config. They are where you call read_terragrunt_config(...) to load shared .hcl files and where you compute derived values. A unit can read its own local.*; to read a parent’s locals you must include it with expose = true and reference include.<name>.locals.*.

locals {
  account = read_terragrunt_config(find_in_parent_folders("account.hcl"))
  env     = read_terragrunt_config(find_in_parent_folders("env.hcl"))
  name    = "${local.env.locals.environment}-frachtline"   # derived
}

inputs = {
  name_prefix = local.name
  tags        = { environment = local.env.locals.environment }
}

The errors block: retry and ignore (and what it replaced)

Transient failures — an API throttle, an eventually-consistent IAM role, a flaky registry — used to be handled by top-level retryable_errors, retry_max_attempts, and retry_sleep_interval_sec attributes, plus a skip flag. Those are deprecated (slated for removal in Terragrunt 1.0) in favour of a structured errors block with retry and ignore sub-blocks. The new model is strictly more capable: multiple retry rules, per-rule attempt/sleep settings, ignoring expected errors, and signalling external systems.

errors contains any number of retry "<name>" and ignore "<name>" sub-blocks:

# live/root.hcl — applies to every unit that includes it
errors {
  retry "transient_cloud" {
    retryable_errors   = [".*RequestLimitExceeded.*", ".* throttl.*", ".*timeout.*"]
    max_attempts       = 3
    sleep_interval_sec = 5
  }
  retry "eventual_iam" {
    retryable_errors   = [".*NoSuchEntity.*", ".*role .* does not exist.*"]
    max_attempts       = 4
    sleep_interval_sec = 10
  }
  ignore "known_benign" {
    ignorable_errors = [".*does not need to be updated.*"]
    message          = "Ignoring benign no-op error"
    signals          = { ignored = "true" }
  }
}

When several retry blocks are present, Terragrunt collects all their retryable_errors patterns for matching and applies the matching block’s own max_attempts/sleep_interval_sec. You can seed the patterns with Terragrunt’s built-in defaults via get_default_retryable_errors() and append your own. Migrate any legacy retryable_errors = [...] you find to a retry block now — it will stop working at 1.0, and terragrunt info / deprecation warnings in your logs are flagging exactly this.

feature and exclude: conditional configuration

Two newer blocks (part of the road to 1.0) that make config conditional without resorting to clever locals gymnastics.

feature "<name>" declares a feature flag with a default, overridable at the CLI (--feature name=value) or via TG_FEATURE. Read it as feature.<name>.value. It is the clean way to toggle a hook, a generate block, or a dependency edge per run.

exclude dynamically removes a unit from a run based on a condition — the modern, in-config replacement for scattering --queue-exclude-dir flags or the deprecated skip = true.

feature "enable_waf" {
  default = false
}

# Skip this unit's apply in ephemeral preview environments, but keep its
# outputs readable so dependents can still plan.
exclude {
  if      = local.env.locals.environment == "preview"
  actions = ["all_except_output"]
}

# Use the flag to toggle a generate block (via disable):
generate "waf" {
  path     = "waf.tf"
  disable  = !feature.enable_waf.value
  contents = "# ... WAF resources ..."
}

exclude’s all_except_output is the subtle, valuable mode: the unit will not apply in this run, but its existing outputs remain readable so dependency consumers still get real values — exactly what you want when freezing one tier while iterating on another.

Stacks: unit and stack (and vs Terraform Stacks)

The classic model is a hand-built tree of terragrunt.hcl units wired by dependency. Terragrunt’s newer Stacks let you generate that tree from a declaration: a terragrunt.stack.hcl file lists unit (and nested stack) blocks, and terragrunt stack generate stamps them into a .terragrunt-stack/ directory from values — so a reusable “VPC + RDS + app” bundle is described once and instantiated per environment.

# terragrunt.stack.hcl
unit "vpc" {
  source = "${get_repo_root()}/units/vpc"
  path   = "vpc"
  values = { cidr = "10.20.0.0/16" }
}
unit "app" {
  source = "${get_repo_root()}/units/app"
  path   = "app"
  values = { replicas = 3 }
}

Crucially, do not confuse Terragrunt Stacks with Terraform/OpenTofu Stacks. They are different layers from different vendors: Terragrunt Stacks (terragrunt.stack.hcl, unit/stack blocks, a Gruntwork feature) generate Terragrunt units; HashiCorp’s Terraform Stacks (*.tfstack.hcl + *.tfdeploy.hcl, deployments/components, a HCP feature) are a native Terraform construct for multi-deployment orchestration. They solve overlapping problems by different means; an interviewer asking “Terragrunt vs Terraform Stacks” wants you to know they are not the same thing. The block/function fundamentals in this lesson carry straight into Terragrunt Stacks; Terraform Stacks are a separate model entirely.

The built-in function catalogue

Terragrunt config is dynamic because of its built-in functions — and it supports every Terraform/OpenTofu built-in function too (merge, lookup, jsonencode, format, try, the for machinery, startswith/endswith/strcontains, etc.), so you have both vocabularies available. Below is the Terragrunt-specific catalogue with exact signatures.

Path and directory functions

Repository functions

Environment, command, and execution functions

AWS helper functions

Config-reading, secrets, and version functions

Two standing cautions for the dynamic functions. First, get_env, run_cmd, and the AWS/sops functions make a config’s behaviour depend on the environment it runs in — powerful for CI, but “the same code” can differ per machine, so document those dependencies and assert the blast radius with get_aws_account_id()/get_aws_caller_identity_arn(). Second, prefer find_in_parent_folders("<name>") with an explicit filename — the no-argument form is deprecated.

Architecture overview

The diagram lays the whole config surface out at once: a single root.hcl carrying remote_state, generate, and errors; a unit’s terragrunt.hcl with its terraform block (and the before_hook/after_hook/error_hook ring around the Terraform command), include arrows up to the root and an env layer, dependency edges to sibling units feeding inputs, and the built-in functions (find_in_parent_folders, path_relative_to_include, read_terragrunt_config, get_env) annotated where each is used. It is the mental index for everything tabulated above — which block holds which attribute, and which function feeds which field.

Hands-on lab

This lab exercises the config language itself — include with expose/merge_strategy, generate with if_disabled/disable, a full set of hooks, the errors block, a feature flag, and a handful of functions — all on the local backend with the null/random providers, so it runs offline, costs nothing, and needs no cloud account. You need terragrunt and terraform (or tofu) on your PATH.

1. Scaffold.

mkdir -p tg-cfg-lab/modules/app tg-cfg-lab/live/dev/app
cd tg-cfg-lab

2. A tiny module. Create modules/app/main.tf:

variable "name"     { type = string }
variable "replicas" { type = number }
resource "random_id" "id" { byte_length = 4 }
resource "null_resource" "app" { triggers = { name = var.name, replicas = var.replicas } }
output "app_id" { value = "app-${random_id.id.hex}" }

3. Shared env locals. Create live/dev/env.hcl:

locals {
  environment = "dev"
  replicas    = 1
}

4. The DRY root — generate provider, an errors retry rule, a feature flag. Create live/root.hcl:

locals {
  env = read_terragrunt_config(find_in_parent_folders("env.hcl"))
}

remote_state {
  backend  = "local"
  generate = { path = "backend.tf", if_exists = "overwrite_terragrunt" }
  config   = { path = "${get_terragrunt_dir()}/terraform.tfstate" }
}

generate "versions" {
  path        = "versions.tf"
  if_exists   = "overwrite_terragrunt"
  if_disabled = "remove_terragrunt"
  contents    = <<-EOF
    terraform {
      required_providers {
        random = { source = "hashicorp/random" }
        null   = { source = "hashicorp/null" }
      }
    }
  EOF
}

feature "noisy_hooks" {
  default = true
}

errors {
  retry "transient" {
    retryable_errors   = [".*timeout.*", ".*temporarily unavailable.*"]
    max_attempts       = 2
    sleep_interval_sec = 1
  }
}

inputs = {
  name = "frachtline-${local.env.locals.environment}"
}

5. The unit — two includes (one exposed), hooks using if/suppress_stdout/run_on_error, and inputs that mix inherited and derived values. Create live/dev/app/terragrunt.hcl:

include "root" {
  path = find_in_parent_folders("root.hcl")
}
include "env" {
  path           = find_in_parent_folders("env.hcl")
  expose         = true
  merge_strategy = "deep"
}

terraform {
  source = "../../../modules//app"

  before_hook "announce" {
    commands        = ["plan", "apply"]
    execute         = ["bash", "-c", "echo '>> preparing ${path_relative_to_include()}'"]
    suppress_stdout = false
    if              = feature.noisy_hooks.value          # gated by the flag
  }
  after_hook "done" {
    commands     = ["apply"]
    execute      = ["bash", "-c", "echo '<< applied, run_on_error=true'"]
    run_on_error = true
  }
  error_hook "oops" {
    commands  = ["plan", "apply"]
    execute   = ["bash", "-c", "echo 'an error occurred'"]
    on_errors = [".*"]
  }
}

inputs = {
  replicas = include.env.locals.replicas    # read the exposed parent local
}

6. Plan — watch the hook, the generated files, and the functions resolve.

cd live/dev/app
terragrunt plan

Expected: the before_hook prints >> preparing dev/app (proving path_relative_to_include() and the feature-gated if), and the plan shows replicas = 1 (the exposed include.env.locals.replicas) and name = "frachtline-dev" (inherited from the root’s inputs).

7. Apply — confirm after_hook and the generated files in the cache.

terragrunt apply -auto-approve
ls .terragrunt-cache/*/*/backend.tf .terragrunt-cache/*/*/versions.tf

Expected: the after_hook prints << applied..., and both generated files exist inside the cache (not the unit dir) — the generate-vs-init mechanic made visible.

8. Toggle the feature flag off — the hook disappears.

terragrunt plan --feature noisy_hooks=false

Expected: the >> preparing ... line is gone, because the before_hook’s if = feature.noisy_hooks.value is now false.

9. Cleanup.

terragrunt destroy -auto-approve
cd ../../..
rm -rf tg-cfg-lab

Cost note: zero. The lab uses the local backend and the null/random providers — nothing is created in any cloud, so there is nothing to bill; cleanup is deleting the directory.

Common mistakes & troubleshooting

Best practices

• Put remote_state, generate, and errors in the root and include it everywhere — that single source of truth is the whole point; never copy a backend or provider into a unit.
• Derive, don’t hard-code. key = "${path_relative_to_include()}/terraform.tfstate"; build paths with get_parent_terragrunt_dir()/get_repo_root(); let the directory be the identity.
• Always pass a filename to find_in_parent_folders and pin every source with ?ref=/?version=.
• Use if_exists = "overwrite_terragrunt" so Terragrunt manages only the files it generated, and pair disable with if_disabled = "remove_terragrunt" to clean up disabled generates.
• Wrap hook shell logic in ["bash","-c", ...], keep noisy linters behind suppress_stdout, and gate optional hooks with if (often a feature flag).
• Migrate to the errors block now — the legacy retry/skip attributes are removed at 1.0; seed patterns with get_default_retryable_errors().
• Prefer dependency over hand-wired terraform_remote_state data sources for cross-unit values — ordering for free, one place to mock; use mock_outputs_merge_strategy_with_state = "shallow" to survive added outputs.
• Reach for feature/exclude instead of clever locals when config must be conditional — they are readable and CLI-overridable.
• Format the config: terragrunt hclfmt for .hcl and hcl_fmt = true on generates so machine-written files pass a --check.

Security notes

• Generated files and inputs can leak secrets. Anything interpolated into a generate "provider" contents or into inputs lands in a .tf/env in the cache. Pull secrets at runtime with sops_decrypt_file/get_env, never commit them, and .gitignore .terragrunt-cache/ and generated files.
• Hooks, run_cmd, and sops_decrypt_file execute arbitrary code at config time — during init/plan, before any human approves an apply. Review changes to root/unit config like code and never run untrusted Terragrunt repositories.
• Assert the blast radius in config. Use get_aws_account_id()/get_aws_caller_identity_arn() (and constraint_check on tool versions) to fail fast when a unit is being applied against the wrong account or an unexpected binary.
• State stays sensitive — and Terragrunt does not change where it lives. Use an encrypted, access-controlled, locked backend; the remote_state.encryption block lets you make OpenTofu state/plan encryption DRY across every unit. The lab’s local backend is for offline learning only.
• Least-privilege per environment. Generate a per-environment assume_role in the provider so dev credentials cannot touch prod.

Interview & exam questions

1. What is the difference between get_terragrunt_dir() and get_working_dir()? get_terragrunt_dir() is your unit’s directory (where its terragrunt.hcl lives); get_working_dir() is the .terragrunt-cache/... directory Terragrunt copies the module into and actually runs the engine in. Generated files land in the latter.

2. path_relative_to_include() vs path_relative_from_include()? The first returns the unit’s path relative to the included parent (e.g. prod/vpc) — used to derive the state key. The second is the inverse, the parent’s path relative to the unit (e.g. ../../..) — used to build relative source paths back to a shared modules directory.

3. Name the three hook kinds and the attribute that makes an after_hook fire on failure. before_hook, after_hook, error_hook. run_on_error = true makes an after_hook run even when the command (or a prior hook) failed. error_hook runs only on failure, matching on_errors regexes.

4. What replaced retryable_errors/retry_max_attempts, and why? The structured errors block with retry/ignore sub-blocks. It allows multiple rules with per-rule max_attempts/sleep_interval_sec, plus ignoring expected errors and signalling external systems — capabilities the flat attributes lacked. The legacy attributes are deprecated, with removal planned for 1.0.

5. What does if_exists = "overwrite_terragrunt" mean, and how does it differ from overwrite? overwrite_terragrunt only manages/overwrites files Terragrunt itself generated (it will not clobber a hand-written file); overwrite clobbers any file. The other choices are skip (never touch an existing file) and error (fail if it exists).

6. You disable a generate block. What stops the previously-generated file breaking the next run? Setting if_disabled = "remove_terragrunt" (alongside disable = true) so Terragrunt removes the stale file it generated, rather than leaving an orphan in the cache.

7. skip_outputs vs mock_outputs on a dependency? skip_outputs = true means never call output on the target (always use mocks / no data) while keeping the ordering edge. mock_outputs provides fallback values used only when real outputs are unavailable. They answer different questions; do not expect skip_outputs to mean “mock only if absent.”

8. What does mock_outputs_merge_strategy_with_state solve, and what’s the sensible value? When you add a new output to an already-applied dependency, no_merge (the default) makes every downstream plan fail until you re-apply the producer. shallow lets the plan use the mock for just the new key while using real values for the rest. deep_map_only recurses into map outputs.

9. How do you read a parent’s locals from a child unit? include the parent with expose = true and reference include.<name>.locals.*. Without expose, you inherit the parent’s emergent config but cannot read its values.

10. Difference between Terragrunt Stacks and Terraform Stacks? Terragrunt Stacks (terragrunt.stack.hcl, unit/stack blocks) are a Gruntwork feature that generates Terragrunt units from a declaration. Terraform/OpenTofu Stacks (*.tfstack.hcl/*.tfdeploy.hcl, components/deployments) are a native HashiCorp construct for multi-deployment orchestration. Different vendors, different layers — not interchangeable.

11. What is extra_arguments for, and how do you apply a -var-file to only the var-taking commands? It conditionally appends CLI flags/var-files to specific commands. Set commands = get_terraform_commands_that_need_vars() and list the file under required_var_files (must exist) or optional_var_files (only if present).

12. Why is remote_state without a generate attribute still valid? Without generate, Terragrunt passes the backend settings to terraform init as -backend-config=... flags instead of writing a backend.tf. The generate form is only needed when you want the backend block as an on-disk file.

Quick check

1. Where do generate/remote_state write their files — your unit directory or somewhere else?
2. Which include attribute lets a child read the parent’s locals?
3. Name the modern block that replaced the deprecated retryable_errors attribute.
4. Which dependency attribute (and value) lets a newly-added output not break every downstream plan?
5. Which function returns the unit’s path relative to the included parent, used to build the state key?

Answers

1. The cache — .terragrunt-cache/<hash>/<hash>/, the working dir Terragrunt runs the engine in (not the unit dir). .gitignore it.
2. expose = true — then reference include.<name>.locals.*.
3. The errors block (with retry/ignore sub-blocks).
4. mock_outputs_merge_strategy_with_state = "shallow" (the default no_merge is what breaks them).
5. path_relative_to_include() — used as key = "${path_relative_to_include()}/terraform.tfstate".

Exercise

Take the lab’s dev/app unit and exercise the rest of the config surface:

1. Add a second unit, net, and wire app to it with a dependency that has mock_outputs, mock_outputs_allowed_terraform_commands = ["validate","plan"], and mock_outputs_merge_strategy_with_state = "shallow". Prove with terragrunt run --all plan that app plans on the mock before net is applied, then on the real output after.
2. Add an extra_arguments block to app’s terraform block that appends a -lock-timeout=10m to every var-taking command (use get_terraform_commands_that_need_vars()), and confirm it in TF_LOG=debug output.
3. Add an exclude block to net with actions = ["all_except_output"] gated on a feature flag, and show that with the flag on, run --all apply skips net’s apply but app still reads its real outputs.
4. Convert the root’s single retry into two retry blocks (one for throttling, one for eventual-consistency) seeded with get_default_retryable_errors(), and a generate "provider" whose disable is driven by a feature flag with if_disabled = "remove_terragrunt"; toggle the flag and confirm the generated file appears and disappears in the cache.

Success looks like: a working dependency with merge-aware mocks, a -lock-timeout injected via extra_arguments, an exclude that freezes a unit while keeping its outputs readable, two targeted retry rules, and a feature-flag-driven generate block that cleans up after itself.

Certification mapping

This lesson supports the HashiCorp Certified: Terraform Associate (003) objectives — with the caveat that Terragrunt is a third-party tool and the exam tests Terraform itself; Terragrunt is the production wrapper that exercises those concepts:

• Objective 8 (read, generate, and modify configuration): the entire terragrunt.hcl surface — generate/remote_state file generation, locals, inputs, functions — is configuration generation and composition taken to production.
• Objective 7 (state): remote_state (backend, disable_init, encryption) and per-unit path-derived keys are the exam’s remote-state/locking topics applied for real; know the plain-Terraform backend/-backend-config equivalents.
• Objective 4 (modules): the terraform { source } attribute, extra_arguments, and Stacks are module consumption/composition at scale.
• Objective 5 (core workflow): hooks wrap the init/plan/apply workflow; the errors block adds retry/ignore around it.
• Cloud DevOps certs (AWS DOP-C02, Azure AZ-400, Google Cloud DevOps Engineer) test multi-environment IaC where this config language is directly applicable.

For the exam, be crisp on the Terraform primitives Terragrunt wraps: backends and locking, the terraform_remote_state data source (the manual alternative to dependency), -backend-config/-var-file flags (what extra_arguments injects), and module source pinning.

Glossary

• Working directory / cache — the .terragrunt-cache/<hash>/<hash>/ directory Terragrunt copies the source module into and runs the engine in; where generated files land. get_working_dir() returns it.
• terraform block — points a unit at a module (source) and wraps it with extra_arguments and hooks; also include_in_copy/exclude_from_copy/copy_terraform_lock_file/mutable.
• Hook (before_hook/after_hook/error_hook) — a shell command run around a Terraform command, with commands, execute, working_dir, run_on_error, suppress_stdout, if, and (errors only) on_errors.
• remote_state block — declares the backend once and (optionally) generates backend.tf per unit; attributes include backend, config, generate, disable_init, disable_dependency_optimization, encryption.
• generate block — writes any file into the working dir; path, contents, if_exists, if_disabled, disable, comment_prefix, disable_signature, hcl_fmt.
• if_exists / if_disabled — collision rules for generated files: overwrite_terragrunt/overwrite/skip/error, and on disable remove/remove_terragrunt/skip.
• include block — inherits a parent config; path, expose (read parent locals), merge_strategy (no_merge/shallow/deep, default shallow).
• dependency block — references another unit and exposes its outputs; config_path, enabled, skip_outputs, mock_outputs, mock_outputs_allowed_terraform_commands, mock_outputs_merge_strategy_with_state.
• dependencies block — ordering-only edges (paths); no data passing.
• mock_outputs — fallback outputs used when a dependency’s real outputs are unavailable; gated by the allowed-commands list, merged with state per the strategy.
• errors block — structured retry/ignore handling (retry/ignore sub-blocks) that replaced the deprecated retryable_errors/skip attributes.
• feature block — a CLI-overridable feature flag (default), read as feature.<name>.value.
• exclude block — dynamically excludes a unit from a run (if, actions incl. all_except_output, exclude_dependencies, no_run).
• unit / stack blocks — Terragrunt Stacks vocabulary (in terragrunt.stack.hcl) that generate a tree of units from source/path/values.
• Terraform Stacks — HashiCorp’s native multi-deployment construct (*.tfstack.hcl/*.tfdeploy.hcl); distinct from Terragrunt Stacks.
• find_in_parent_folders("name") — returns the nearest ancestor file of that name (always pass the name).
• read_terragrunt_config(path) — parses another .hcl file into an object you can read (.locals, .inputs).

Next steps

You now have the complete terragrunt.hcl reference — every block and its attributes, every built-in function, hooks end to end, the errors retry/ignore model, and the generate-vs-init mechanics. To put the fundamentals in narrative context (the live/modules split, the DRY rationale, the on-ramp), see Terragrunt Fundamentals: DRY Configurations, Remote State & Dependencies. For the orchestration side — how run --all/run --graph walk the DAG, change-aware selective execution, parallelism, and CI at 200 units — read Scaling Terragrunt Monorepos with Dependency Graphs and run-all. Then apply all of it end to end in Multi-Environment 3-Tier Infrastructure with Terragrunt & CI/CD Approval Gates, where this config language drives a real dev→uat→staging→prod promotion pipeline behind graduated approval gates.