Terragrunt Guides: Breaking up a Terralith with Terragrunt

As your infrastructure grows, you can find yourself in a common yet challenging situation known as the Terralith. This pattern, also called a "Megamodule" or "All In One State" configuration, happens when a large, complex infrastructure estate is managed within a single state file.

The result is a frustrating set of problems for platform engineers: tofu apply commands that drag on for minutes, and plan output that becomes a massive wall of information you have to carefully sift through just to confirm a simple change won't cause unexpected problems. A simple tag update could accidentally take down your production environment, and it might even seem safer to just make the changes manually, which only makes the problem worse.

This scenario is why we put together a Terralith to Terragrunt guide. The guide walks you through the journey of building a monolithic Infrastructure as Code (IaC) setup and then systematically breaking it down into a clean, scalable, and maintainable infrastructure setup using Terragrunt.

A Journey from Monolith to Modularity

The guide takes you on a step-by-step journey, starting with a simple, serverless web application and its IaC. The application, a fun project to view and vote on AI-generated cat images, is initially managed in a single state file: a classic Terralith pattern.

Step 1: Provisioning Initial Infrastructure

Initially, the guide will walk you through the naive approach to infrastructure management. You’ll provision infrastructure using a flat directory of IaC tracked using a single state file. You’ll have working infrastructure (which won’t change at all throughout the guide), but the business logic for your application and the infrastructure code that manages it will be tightly coupled. You won’t be able to easily reuse parts of your infrastructure code, and there won’t be well defined boundaries between parts of your infrastructure.

Step 2: Refactoring for Reusability

The first step in wrangling your infrastructure estate will be to refactor the flat configuration into a set of distinct, reusable modules for each component (S3, DynamoDB, IAM, Lambda). The guide teaches you how to use OpenTofu's moved blocks to reorganize your code without destroying and recreating existing infrastructure.

Step 3: Adding Environments

Next, you'll start to add more infrastructure to your project as an additional environment. You’ll do this by encapsulating all of the infrastructure you have as a single module, then duplicating it. You'll see how replicating infrastructure using modules like this with a monolithic state file introduces significant risk, as an update intended for dev could potentially damage your prod environment.

Step 4: Breaking the Terralith

The core of the guide is about solving this risk. You'll break the single state file into two separate ones: one for dev and one for prod. This drastically reduces the blast radius, but it comes at the cost of boilerplate and code duplication.

Step 5: Introducing Terragrunt

This is where Terragrunt comes in. It's introduced as an orchestrator to solve the boilerplate problem. You'll learn to replace duplicated files with a single, concise terragrunt.hcl file, and centralize common configurations using the include block.

Step 6: Achieving Safety Through Granularity

The guide takes modularity a step further by breaking each environment's single state file into multiple, component-specific state files. This is the ultimate level of granular control, ensuring a change to a frequently updated resource like a Lambda function has zero chance of impacting a stable resource like your database. You'll also learn about the dependency block and mock_outputs for managing inter-component relationships.

Step 7: Eliminating Boilerplate with Stacks

The guide concludes by introducing Terragrunt Stacks, one of Terragrunt's most advanced features. This pattern allows you to generate entire collections of units on-demand from a single terragrunt.stack.hcl file, eliminating the final major source of boilerplate.

Key Skills You Will Master

By following the Terralith to Terragrunt guide, you will gain hands-on experience with:

• Advanced State Manipulation: Safely refactor state without destroying and recreating critical resources. You'll use commands like state pull and state push to migrate state between different backends.
• Modular Infrastructure Design: Break down monolithic configurations into simple, reusable modules with clear APIs.
• Boilerplate Reduction: Use terragrunt.hcl to generate configurations and pass inputs dynamically.
• Dependency Management: Orchestrate complex deployments across multiple, isolated state files.
• Dynamic Stack Generation: Define and manage entire environments on-demand with a single file, resulting in infrastructure definitions that are radically simpler and easier to maintain.

Terragrunt Scale

For organizations looking to tackle their Terralith problem at scale, Terragrunt Scale is the way to do that! At Gruntwork, we’ve helped countless organizations transition from unmaintainable Terraliths to best practice IaC configurations using Terragrunt and a suite of commercial tools like Terragrunt Pipelines, Patcher and Drift Detection. These tools make it easy for infrastructure management to get out of the way of your platform teems, and keep them focused on the work that delivers value to your organization.

If you’d like to learn more about Terragrunt Scale, contact us here!