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

🏗️ 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. Each unit’s own terragrunt.hcl then only needs a terraform { source = ... } block pointing at the actual module it should run.

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

Submit

Mark as complete