Terragrunt HCL and the Root Config

The idea in one sentence

A Terragrunt unit is one deployable piece of infrastructure with its own terragrunt.hcl and its own Terraform state, and a shared root.hcl file above it holds the configuration every unit needs without any of them repeating it.

What a Terragrunt unit actually is

In the Modules module you saw that a Terraform root module is just the directory you run terraform apply in directly. Terragrunt reuses that exact idea and gives it its own name: a unit. A unit is a directory containing its own terragrunt.hcl file, wrapping one Terraform root module, tracked by its own separate state file. A vnet unit, a vm unit, and a database unit are three independent units — three directories, three terragrunt.hcl files, three state files — even though in a single-Terraform-project world you might have been tempted to manage all three resources from one root module and one shared state file.

Splitting infrastructure into units this way is a deliberate trade: smaller, independently applied pieces of state mean a mistake in one unit cannot corrupt or lock the state of another, and a plan for vm does not have to evaluate every resource inside vnet and database just to show you what changed. The cost is that units now need a way to share the configuration they all still have in common — which is exactly what root.hcl is for.

root.hcl: the config every unit stands on

Picture a directory layout with one config file at the very top of a subscription or environment tree, and a terragrunt.hcl file inside every unit directory beneath it. That top-level file used to be named terragrunt.hcl too, since Terragrunt never required any particular name for it. That naming still works today, and plenty of existing repositories and tutorials still use it, but it is ambiguous the moment someone says “check terragrunt.hcl” — do they mean the shared root file, or the specific unit you happen to be standing in.

The current recommended convention names that shared parent file root.hcl instead, precisely to remove that ambiguity: root.hcl is unmistakably the one shared file at the top, and terragrunt.hcl is unambiguously a specific unit’s own config. This course uses root.hcl throughout.

remote_state and generate: one backend, not copy-pasted per unit

Every unit needs a Terraform backend — in an Azure setup, an Azure Storage Account container holding the state blob. Declaring that backend by hand inside every single unit is exactly the kind of repetition Terragrunt exists to remove. Instead, root.hcl declares it once with a remote_state block, and its generate sub-block tells Terragrunt to write out a backend.tf file into each unit right before Terraform runs there:

root.hcl

remote_state {
  backend = "azurerm"

  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }

  config = {
    resource_group_name  = "rg-terraform-state"
    storage_account_name = "acmetfstate"
    container_name       = "tfstate"
    key                  = "${path_relative_to_include()}/terraform.tfstate"
    subscription_id      = "00000000-0000-0000-0000-000000000000"
  }
}

path_relative_to_include() gives each unit its own unique key inside the shared container, based on where that unit sits relative to the file that includes this one, so the vnet unit and the vm unit automatically land at different state paths without either of them writing that path out literally. if_exists = "overwrite_terragrunt" tells Terragrunt it is safe to overwrite a backend.tf it generated on a previous run. Notice there is no lock-table argument anywhere in this block — unlike some other clouds’ backends, the azurerm backend needs no separate locking resource, since it uses Azure Blob Storage’s built-in blob-lease locking.

A top-level generate block works the same way for provider configuration — commonly placed right alongside remote_state in root.hcl:

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "azurerm" {
  features {}
  subscription_id = "00000000-0000-0000-0000-000000000000"
}
EOF
}

Both blocks produce ordinary .tf files — backend.tf and provider.tf — sitting next to the actual Terraform code Terragrunt runs. Terraform itself never knows those files were generated; from its perspective they are just configuration that happened to already be there. The empty features {} block is required by the azurerm provider even when there is nothing to configure inside it — Terraform will refuse to run without it.

The terraform block’s source: pointing a unit at its module

remote_state and the provider generate block live in root.hcl because every unit shares them. What differs per unit is which actual Terraform module it runs, and that lives in the unit’s own terragrunt.hcl, inside a terraform block:

vnet/terragrunt.hcl

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

terraform {
  source = "git::[email protected]:acme/infrastructure-modules.git//vnet?ref=v1.4.0"
}

inputs = {
  address_space = ["10.0.0.0/16"]
}

source can point at a local relative path during development or, as above, a Git URL pinned to a tag — the same module addressing you already know from a Terraform module block’s source argument, just expressed at the unit level instead of inside main.tf. The include line is what pulls in everything root.hcl defined — the full mechanics of include are the subject of the next lesson; for now, just notice that this three-line unit config gets a working Azure Storage backend and azurerm provider for free, without repeating a single line of either.

flowchart TD
  root["root.hcl (remote_state + generate)"]
  root --> vnet["vnet/terragrunt.hcl"]
  root --> vm["vm/terragrunt.hcl"]
  root --> database["database/terragrunt.hcl"]
  vnet --> vnetmod["terraform.source: modules//vnet"]
  vm --> vmmod["terraform.source: modules//vm"]
  database --> dbmod["terraform.source: modules//database"]
  vnet -.->|inherits generated backend.tf + provider.tf| root
  vm -.->|inherits generated backend.tf + provider.tf| root
  database -.->|inherits generated backend.tf + provider.tf| root

One root.hcl feeding several units, each pointing at its own module

Proof: terragrunt render resolving find_in_parent_folders for real

The claims above are not asserted — they come from a real Terragrunt 1.1.0 unit tree. root.hcl at the top of a scratch tree:

root.hcl

remote_state {
  backend = "azurerm"

  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }

  config = {
    resource_group_name  = "rg-terraform-state"
    storage_account_name = "acmetfstate"
    container_name       = "tfstate"
    key                  = "${path_relative_to_include()}/terraform.tfstate"
    subscription_id      = "00000000-0000-0000-0000-000000000000"
  }
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "azurerm" {
  features {}
  subscription_id = "00000000-0000-0000-0000-000000000000"
}
EOF
}

And vnet/terragrunt.hcl, using find_in_parent_folders("root.hcl") — Terragrunt walks up from the current unit directory looking for a file with that exact name, so vnet/ never has to hardcode how many directories separate it from the root:

vnet/terragrunt.hcl

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

terraform {
  source = "."
}

inputs = {
  address_space = ["10.0.0.0/16"]
}

Running terragrunt render --format json from inside vnet/ (no apply, no network — render only parses and evaluates HCL) prints the fully resolved config Terragrunt is about to hand to Terraform, real output trimmed:

$ terragrunt render --format json
{
  "remote_state": {
    "backend": "azurerm",
    "config": {
      "container_name": "tfstate",
      "key": "vnet/terraform.tfstate",
      "resource_group_name": "rg-terraform-state",
      "storage_account_name": "acmetfstate",
      "subscription_id": "00000000-0000-0000-0000-000000000000"
    },
    "generate": { "if_exists": "overwrite_terragrunt", "path": "backend.tf" }
  },
  "generate": {
    "provider": {
      "contents": "provider \"azurerm\" {\n  features {}\n  subscription_id = \"00000000-0000-0000-0000-000000000000\"\n}\n",
      "if_exists": "overwrite_terragrunt",
      "path": "provider.tf"
    }
  },
  "inputs": { "address_space": ["10.0.0.0/16"] },
  "terraform": { "source": "." }
}

The proof is in "key": "vnet/terraform.tfstate" — path_relative_to_include() evaluated to the literal string "vnet" because that’s where this unit sits relative to the root.hcl it includes, and it got interpolated into the key with zero hardcoding on the unit’s side. A vm/terragrunt.hcl unit with the exact same three-line body would resolve to "key": "vm/terraform.tfstate" instead — same root.hcl, different key, purely from directory position.

The module itself is real, too — azurerm_resource_group + azurerm_virtual_network with address_space = var.address_space, validated with a real terraform init -backend=false && terraform validate against hashicorp/azurerm ~> 5.0:

$ terraform validate
Success! The configuration is valid.

The real backend.tf that generate writes

generate does not call Azure. It writes an ordinary .tf file into the unit’s working copy before Terraform ever runs. Real content, captured from Terragrunt’s own .terragrunt-cache working directory (never initialized against a real storage account — this course has no Azure credentials, and this lesson proves the file, not a live backend):

backend.tf

# Generated by Terragrunt. Sig: nIlQXj57tbuaRZEa
terraform {
  backend "azurerm" {
    container_name       = "tfstate"
    key                  = "vnet/terraform.tfstate"
    resource_group_name  = "rg-terraform-state"
    storage_account_name = "acmetfstate"
    subscription_id      = "00000000-0000-0000-0000-000000000000"
  }
}

That # Generated by Terragrunt comment and signature line are real — Terragrunt writes them so a later run can recognize a file it owns and safely if_exists = "overwrite_terragrunt" it, without ever touching a backend.tf a human wrote by hand under a different name or signature. Trying to actually run this (terragrunt plan) reaches a real, expected wall: unable to build authorizer for Resource Manager API: could not configure AzureCli Authorizer: could not parse Azure CLI version: launching Azure CLI: exec: "az": executable file not found in $PATH — a genuine Azure authentication failure, not a fake error, proving generate really did hand a correctly-shaped backend off to Terraform before stopping at the one wall this course cannot cross (no Azure credentials, no az CLI installed).

remote_state auto-create on Azure — and the version boundary that matters here

remote_state does more than generate a backend file — for a subset of backends, Terragrunt will also create the storage resource itself the first time a unit runs, if it doesn’t already exist. This is the single most important version fact for this course, so it is worth being exact, not hand-wavy, quoting the Terragrunt experiments registry directly:

“Terragrunt manages lifecycle operations for the Azure Storage (azurerm) remote state backend, matching what it already does for S3 buckets and GCS buckets: Bootstrap: creates the resource group (when allowed), storage account, and blob container backing the state, and converges blob versioning and optional soft delete on both new and pre-existing accounts. Delete: removes state blobs or entire containers, with confirmation prompts. Migrate: moves state blobs within the same storage account.”

But on the Terragrunt 1.1.0 installed for this course, that bootstrap/delete/migrate lifecycle is still gated, per docs.terragrunt.com/features/state-backend: “azurerm backend … <Before version="v1.2.0"> (experimental; bootstrap, delete, and migrate require the azure-backend experiment)”. It graduated to on-by-default only in Terragrunt 1.2.0. Proven above, ordinary generate+init against azurerm works with zero extra flag on this installed 1.1.0 (the run reached a real Azure auth error, not an “experiment not enabled” error) — but auto-creating the resource group/storage account/container specifically needs --experiment azure-backend explicitly until 1.2.0. For comparison, since this differs meaningfully by cloud: S3 and GCS auto-create their bucket with no extra flag at all (GCS additionally needs project/location keys to know where to create it) — azurerm is the one backend of the three where the bootstrap lifecycle itself is still behind an experiment flag on this installed version.

🏗️ The one-line takeaway

A Terragrunt unit is one directory with its own terragrunt.hcl and its own state, wrapping one Terraform module; the shared parent config sits one level up and is now conventionally named root.hcl (not terragrunt.hcl) specifically to avoid confusing “the shared root file” with “this unit’s own file” — older repos that still call it terragrunt.hcl continue to work. root.hcl declares a remote_state block with a generate sub-block so every unit gets an identical, centrally defined Azure Storage backend.tf (with no separate lock-table resource needed, since azurerm uses blob-lease locking) — and, via a top-level generate "provider" block, a provider.tf with the required (even if empty) features {} block — instead of that boilerplate being hand-copied into every unit, proven above with a real terragrunt render --format json and the real generated backend.tf content. Auto-creating the storage account itself, though, is gated on this installed 1.1.0: proven above with a docs quote and a real run, azurerm’s bootstrap/delete/migrate lifecycle needs --experiment azure-backend until Terragrunt 1.2.0, unlike S3/GCS which auto-create with no extra flag. Each unit’s own terragrunt.hcl then only needs a terraform { source = ... } block pointing at the actual module it should run.

Reading AI-generated code

When reviewing generated root.hcl/unit configs, check for:

• A hardcoded key in remote_state.config instead of "${path_relative_to_include()}/terraform.tfstate" — proven below, this makes every unit that includes the same root silently share one state blob, and a second unit’s apply can destroy the first unit’s resources without ever raising an error about it.
• generate blocks missing if_exists = "overwrite_terragrunt" — the default is "error", so a second run of a fresh checkout fails immediately with “file already exists” the moment a previous run already wrote that backend.tf.
• An azurerm remote_state block that assumes the storage account/resource group get created automatically with no extra flag on Terragrunt 1.1.0 — proven above, bootstrap needs --experiment azure-backend on this course’s installed version.
• A missing empty features {} block in a generated provider "azurerm" {} — the azurerm provider refuses to run without it, even with nothing inside it to configure.
• terraform { source = "..." } with no ?ref= pin on a Git URL — every unit resolves against whatever the default branch currently contains, so two apply runs an hour apart can pull genuinely different module code with no diff visible in the unit’s own terragrunt.hcl.

🐛 Spot the bug

# root.hcl — shared by every unit
remote_state {
backend = "azurerm"

generate = {
  path      = "backend.tf"
  if_exists = "overwrite_terragrunt"
}

config = {
  resource_group_name  = "rg-terraform-state"
  storage_account_name = "acmetfstate"
  container_name       = "tfstate"
  key                  = "terraform.tfstate"
  subscription_id      = "00000000-0000-0000-0000-000000000000"
}
}

Show the answer

The bug is key = "terraform.tfstate" — a literal string, not "${path_relative_to_include()}/terraform.tfstate". Proven above, path_relative_to_include() is what makes the vnet unit resolve to "vnet/terraform.tfstate" and a vm unit resolve to "vm/terraform.tfstate"; with a hardcoded literal, both units resolve to the exact same blob key inside the same container. Terragrunt never warns about this — nothing about a container+key pair “already being state for another unit” is checked. The first symptom is usually vm’s apply reporting it wants to destroy resources nobody remembers creating: those are actually vnet’s resources, because both units have been reading and overwriting the same state blob the entire time.

Mental Model

root.hcl is not magic inheritance — it is one file that include copies into every unit’s evaluated config, the same way a shared header gets #included into multiple C source files. Nothing is shared at runtime; each unit still runs its own independent terraform init/plan/apply against its own generated backend.tf. The key’s uniqueness (via path_relative_to_include()) is the only thing standing between “independent units with independent state” and “units that silently corrupt each other’s state” — proven directly above. Treat a Terragrunt unit exactly the way you’d treat a Terraform root module, because that is literally what it is: terragrunt.hcl plus include just automates writing the backend and provider blocks that a hand-run root module would otherwise need typed out by hand, every time.

Trade-offs

Choice	Benefit	Cost
Splitting infrastructure into units (own state per directory)	A mistake or lock in one unit cannot touch another; smaller plans	Cross-unit references need dependency blocks (next lesson) instead of a same-state resource reference
remote_state + generate centralizing the backend	One place to change the storage account/container for every unit; zero copy-pasted backend blocks	The generated file is invisible until you go look for it in .terragrunt-cache — a terraform init run directly inside a unit directory (bypassing Terragrunt) will not see it
Azure auto-create gated behind --experiment azure-backend on 1.1.0	Explicit opt-in before Terragrunt is allowed to create real Azure billing resources (a storage account) on your behalf	Proven above: getting this wrong looks like a real Azure auth failure, not a missing-flag failure, unless you already know to check for the experiment gate

Common Misconceptions

• “root.hcl and terragrunt.hcl are different file formats.” They are the same HCL dialect — proven above, this course’s own root.hcl uses remote_state/generate blocks, identical blocks to what a unit’s terragrunt.hcl can also contain. The name is pure convention to avoid ambiguity, nothing enforces it.
• “generate writes directly into my unit directory, so I’ll see backend.tf right there.” Proven above: the real backend.tf this lesson captured lives inside .terragrunt-cache/HASH/HASH/backend.tf, Terragrunt’s working copy — not the source directory you edit.
• “Every cloud backend Terragrunt supports auto-creates its storage the same way.” Proven above with the docs quote and a real run: S3 and GCS auto-create with no extra flag (GCS needs project/location); azurerm on this course’s installed Terragrunt 1.1.0 needs --experiment azure-backend for the bootstrap/delete/migrate lifecycle specifically, graduating to on-by-default only in 1.2.0.
• “The azurerm backend needs a separate lock resource, the way some other clouds’ backends need a lock table.” It does not — Azure Blob Storage’s own lease mechanism provides locking, so there is no lock-table equivalent anywhere in the remote_state.config shown above.

What is a Terragrunt unit?

A single Azure resource such as one virtual machine A directory with its own terragrunt.hcl file, wrapping one Terraform module and tracked by its own separate state A synonym for a Terraform provider A folder that only contains variables.tf

Why is the shared parent config file now conventionally named root.hcl instead of terragrunt.hcl?

Terragrunt refuses to run if the root file is named terragrunt.hcl root.hcl is required syntax and terragrunt.hcl no longer works for a root file The distinct name avoids ambiguity between the one shared root file and any individual unit own terragrunt.hcl, though naming it terragrunt.hcl still works root.hcl enables a feature that terragrunt.hcl cannot use

What does a remote_state block with a generate sub-block actually produce, and what does the azurerm backend need that some other backends require separately?

It only validates that a storage account exists, and it still needs a separate lock-table resource It writes out a backend.tf file for the unit from one centrally defined configuration, and needs no separate lock-table argument since azurerm uses built-in blob-lease locking It deletes the existing Terraform state for the unit It replaces the need for a terraform.source attribute

Where does the terraform source attribute pointing at the actual module code belong?

In root.hcl, shared by every unit In each unit own terragrunt.hcl, since different units typically run different modules It cannot be set in Terragrunt at all Inside the generated backend.tf file

A root.hcl sets key = "terraform.tfstate" (a literal string) instead of "${path_relative_to_include()}/terraform.tfstate". What actually happens when two units, vnet and vm, both include this root.hcl?

Terragrunt detects the collision and refuses to run the second unit Both units resolve to the exact same blob key inside the same container and silently share one state file, with no warning from Terragrunt Terragrunt automatically appends the unit name to make the key unique Only the first unit that runs gets a valid state file; the second fails immediately

On this course's installed Terragrunt 1.1.0, what happens if you configure an azurerm remote_state block with no storage account created yet, and no --experiment azure-backend flag?

Terragrunt automatically creates the resource group, storage account, and container exactly like it does for S3 Terragrunt refuses to parse the config at all generate still writes backend.tf and Terraform still attempts to init against azurerm, but Terragrunt will not auto-create the storage account — that bootstrap lifecycle needs the azure-backend experiment flag before Terragrunt 1.2.0 Terragrunt silently falls back to a local backend

Submit

Mark as complete