Terragrunt Unit

We will dedicate a few lessons in our course to talk about Terragrunt Terminology. Specifically we will focus on Units and Stacks. We will understand those concepts as well as learn to apply them in our codebase.

In this lesson we will focus on Units

What is a Unit

A Unit represents a single instance of infrastructure managed by Terragrunt. Here are a few characteristics:

• It has its own state
• It is in a folder which has a terragrunt.hcl file
• It is often minimalistic and represents a small piece of infrastructure.
• A unit can interact with another unit using dependency blocks.

An example of a unit in our repository: root folder. We have a unit which creates our course root folder, this is a very minimal piece of infrastructure which other units use with dependency blocks.

Bad Practice - root terragrunt.hcl

In the past it was common to have a terragrunt.hcl file in the root of the repository. Just like in our repository: root terragrunt.hcl. That root terragrunt.hcl did not really represent a unit, it was more of a shared configuration for all the units in the repository.

Other units would include the root terragrunt.hcl using:

include "root" {
  path = find_in_parent_folders()
}

And in this file we defined providers configuration, remote state configuration and impersonation logic.

The find_in_parent_folders function would search up the directory tree from the current terragrunt.hcl file and return the absolute path to the first file it finds named terragrunt.hcl if nothing supplied to the function, or the name of the file supplied. It allowed us to easily find the parent terragrunt.hcl file without hardcoding the path and including that shared configuration. There are a few problems with this approach:

• The root terragrunt.hcl is not really a unit, it does not represent a single piece of infrastructure, and it is not runnable by itself.
• That fact will often break running terragrunt run-all commands from the root of the repository, as it will try to run the root terragrunt.hcl which is not a unit.
• The pattern might break if we have parent folders that are units and have terragrunt.hcl files in them.

This is why it is no longer recommended to name root file that represents shared logic as terragrunt.hcl - which usually represent a unit - but rather give it a different name like root.hcl or common.hcl. A name that will mark that file as shared logic and not runnable unit which defines an infrastructure piece.

Migrate to root.hcl

We will follow this migration guide and change the name of our root terragrunt.hcl to root.hcl. After we rename the file we will need to update the find_in_parent_folders function to look for root.hcl instead of terragrunt.hcl. So from:

include "root" {
  path = find_in_parent_folders()
}

To:

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

You can examine the migration in the following PR

Summary

A unit represents a single piece of infrastructure with its own state. A unit is in a folder with a terragrunt.hcl file. Since our root terragrunt.hcl file did not represent a unit, we renamed it to root.hcl and updated all the find_in_parent_folders functions to look for root.hcl instead of terragrunt.hcl.