Terragrunt Stacks: What terragrunt.stack.hcl Actually Does

Terragrunt exists because people got tired of copying backend.tf into forty directories. Stacks exist because people then got tired of copying terragrunt.hcl into forty directories.

If you've run Terragrunt for a while, you know the shape of it. live/dev/us-east-1/vpc/terragrunt.hcl, then the same thing under staging, then under prod, each one a near-identical file whose only real content is a source, an include, and a handful of inputs. Adding a region means copying a tree. Changing the pattern means a find-and-replace across every copy, and missing one is how dev and prod drift apart.

Explicit stacks are Terragrunt's answer to that. You write the pattern once and let Terragrunt generate the directories.

What is a Terragrunt stack?

A stack is a collection of related units that Terragrunt manages together, so one command deploys the set and Terragrunt works out the dependency order between them. That much has always been true of a well-organized Terragrunt repo.

What's newer is that stacks now come in two flavors. An implicit stack is the one you already have: units arranged in a directory structure, no extra file involved. An explicit stack is declared in a terragrunt.stack.hcl file, which Terragrunt reads as a blueprint and uses to generate the unit configurations at runtime.

Terragrunt's own guidance is to start implicit and reach for explicit stacks when you've got reusable patterns, several environments that differ only in values, or a catalog other teams consume. That's sensible. If you have six units and one environment, a terragrunt.stack.hcl buys you nothing but indirection.

What goes in a terragrunt.stack.hcl file?

Two block types, both taking the same three arguments: source, path, and values.

A unit block defines one deployable piece of infrastructure:

unit "vpc" {
  source = "git::[email protected]:acme/infrastructure-catalog.git//units/vpc?ref=v0.0.1"
  path   = "vpc"
}

source says where the unit's configuration comes from, path is the directory name to generate it into, and values is a map of inputs handed to the unit. Each generated unit directory ends up with two files: a terragrunt.hcl and a terragrunt.values.hcl carrying that unit's values.

A stack block does the same thing one level up. Its source points at another terragrunt.stack.hcl, so what gets generated is itself a stack. Inside the referenced file, the values you passed are readable as values.<name>. That's the mechanism that lets a single environment pattern produce both dev and prod from one definition, which is the whole reason most teams look at explicit stacks in the first place.

One structural rule catches people early: a directory is either a unit or a stack, never both. A unit can't contain a terragrunt.stack.hcl, and a stack can't contain a terragrunt.hcl. Terragrunt uses exactly that to tell the two apart, so the files can't coexist in one directory.

What does terragrunt stack generate do?

It walks the current directory and everything beneath it, finds every terragrunt.stack.hcl, and writes a .terragrunt-stack directory with one subdirectory per unit path. Each of those holds the generated terragrunt.hcl. Generation runs in parallel, governed by GOMAXPROCS or --parallelism.

terragrunt stack generate
terragrunt stack run apply

You don't always have to run the first one. Commands that deploy units generate the stack automatically when it's missing. Running it explicitly is useful when you want to look at what you're about to apply before applying it, which on a first stack is time well spent.

Generation validates as it goes, checking that each unit's target directory contains a terragrunt.hcl and each nested stack's contains a terragrunt.stack.hcl. --no-stack-validate turns that off, though it's hard to think of a good reason to on a stack you're still building. Absolute paths get rejected, so everything stays relative to the working directory.

Where do stacks bite?

Two things, and the first one costs people an afternoon.

Generation doesn't clean up after itself. terragrunt stack generate won't remove files in .terragrunt-stack that your current configuration no longer produces. Rename a unit from vpc to network and you now have both directories sitting there, the old one holding a perfectly valid generated config pointing at infrastructure you thought you'd moved. The fix is terragrunt stack clean followed by terragrunt stack generate, or regenerating with --source-update. Make that reflex rather than something you remember after a confusing plan.

.terragrunt-stack is build output, so treat it that way. Gitignore it and regenerate. Committing generated directories recreates exactly the copy-paste sprawl the stack was supposed to remove, with the added pleasure of merge conflicts in files no human wrote.

How do Terragrunt stacks run on a managed platform?

This is where stacks get genuinely awkward for CI, and it's worth understanding why before you debug it.

With a conventional Terragrunt repo, your pipeline clones the repo and the unit directories are right there. With an explicit stack, they aren't. The repository holds a terragrunt.stack.hcl and some sources; the actual tree the tooling expects doesn't exist until something runs generation. Any pipeline step that assumes a unit directory is present (a lint pass, a formatting check, a plan) hits a tree that hasn't been built yet and fails in a way that reads like a broken config rather than a sequencing problem.

A platform that supports stacks properly has to generate the stack and discover its units before anything else runs. Scalr's runners do that generation and unit discovery ahead of the lint, plan, and apply steps, so those steps see a complete tree. Scalr requires Terragrunt 0.80.0 or later for native stacks, and versions below that now return a validation error rather than failing confusingly further along. Self-hosted agent pools need agent 1.6.0; Scalr-managed runners picked this up automatically. If you're rolling your own pipeline instead, the takeaway is the same: make generation an explicit first step, before anything that reads the tree.

Stacks are a different model from Terragrunt's run-all, which Scalr also supports and which comes with its own constraints around backends and unit state. They solve overlapping problems from different directions, and you'll usually pick one.

Should you move to explicit stacks?

Not reflexively. The test is whether you're maintaining copies of the same terragrunt.hcl that differ only in a few values, and whether the number of copies is growing. If it is, a stack converts that duplication into one definition plus a values map, and new environments stop being a copy operation.

If your tree is small, or your units genuinely differ from each other, you're trading a directory you can read for a blueprint you have to generate. That's a real cost. Terragrunt's own documentation recommending implicit stacks for smaller setups is good advice and not just a gentle on-ramp.

Start with one pattern you've already copied three times. Write it as a terragrunt.stack.hcl, run terragrunt stack generate, and read what comes out before you run anything against real infrastructure. If the generated tree matches what you'd have written by hand, you've found the right first candidate. For the groundwork underneath all of this, our beginner's guide to Terragrunt covers the include and dependency patterns stacks are built on top of.