Forem: Jeancy Joachim Mukaka

Stop Putting Everything in One Terraform State: Use Terragrunt Dependency Blocks

Jeancy Joachim Mukaka — Wed, 29 Apr 2026 15:40:49 +0000

Prerequisites

Before getting started, make sure you have the following:

Basic knowledge of Terraform (HCL syntax, resources, variables, remote state)
Terraform >= 1.11 installed - Download
Terragrunt installed - Installation guide
An AWS CLI configured with sufficient permissions to create S3 buckets and EC2 instances
Visual Studio Code with the HashiCorp Terraform extension for syntax hightlighting and autocompletion
Read Part 1 of this series: Stop Copy-Pasting Terraform State Configs: Use Terragrunt Instead

Introduction

In Part 1 of this series, we saw how Terragrunt eliminates the repetition of remote state backend configurations across environments. if you haven't read it yet, I recommend starting there - Stop Copy-Pasting Terraform State Configs: Use Terragrunt Instead.
Today, we go one step further.
Most of Terraform projects start the same way: everything in one state file. Your VPC, your security groups, your EC2 instances, your RDS database, all managed together. It feels simple and convenient at first. But as your infrastructure grows, this approach becomes a hidden risk.
Imagine this: a developer runs terraform apply to redeploy an EC2 instance that is rebuilt multiple times a day. Because everything is in the same state file, that single command now has access to your VPC configuration, your production database, and your security groups, resources that should never be touched during a routine EC2 redeployment.
One wrong move, one bad variable, one interrupted apply, and you could accidentally destroy or corrupt critical infrastructure that takes hours to rebuild.
In this article, we'll explore how Terragrunt's dependency blocks allow you to split your Terraform state between infrastructure components, so that frequently changed resources never put your critical infrastructure at risk.

The Problem: One State File to Rule Them All

When everything lives in a single Terraform state file, your infrastructure looks like this:

single state file
├── VPC                ← modified once a month
├── Subnets            ← modified once a month
├── Security Groups    ← modified occasionally
├── RDS Database       ← critical, rarely modified
└── EC2 Instances      ← modified 10x per day

Every terraform apply, no matter how small, touches this single state file. This creates three serious problems:

Problem 1: Blast radius: If something goes wrong during a routine EC2 redeployment, the entire state file is at risk. A corrupted state means Terraform loses track of all your resources, VPC, database, everything.
Problem 2: No separation of concerns: A junior developer redeploying an EC2 instance has the same Terraform access as a senior engineer modifying the VPC. There is no natural boundary between critical and non-critical infrastructure.
Problem 3: Slow operations As your infrastructure grows: Terraform has to refresh the state of every single resource on every terraform plan or terraform apply, even if you're only changing one EC2 instance. This makes operations increasingly slow. The solution is to split your state between infrastructure components, and Terragrunt dependency blocks make this both simple and elegant.

The Solution: Separate States with Dependency Blocks

Instead of one monolithic state file, Terragrunt allows you to give each infrastructure component its own isolated state:

vpc/                    ← state 1 — modified rarely
security-groups/        ← state 2 — modified occasionally
rds/                    ← state 3 — critical, rarely modified
ec2/                    ← state 4 — modified daily

Each component lives in its own folder with its own terragrunt.hcl file and its own state file in S3:

s3://my-terraform-state/
├── dev/vpc/terraform.tfstate
├── dev/security-groups/terraform.tfstate
├── dev/rds/terraform.tfstate
└── dev/ec2/terraform.tfstate

Now when a developer runs terraform apply on the EC2 component, only the EC2 state is touched. The VPC, the database, and the security groups are completely isolated and protected.
But here's the challenge: if components are separated, how does the EC2 module know the subnet ID from the VPC module? How does the security group know the VPC ID?
This is where Terragrunt's dependency block comes in.
The dependency block allows a component to read the outputs of another component without sharing the same state file:

# ec2/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

# Declare dependency on VPC component
dependency "vpc" {
  config_path = "../vpc"

  mock_outputs = {
    subnet_id = "subnet-00000000"
  }
}

# Declare dependency on security groups component
dependency "security_groups" {
  config_path = "../security-groups"

  mock_outputs = {
    sg_id = "sg-00000000"
  }
}

# Use outputs from dependencies as inputs
inputs = {
  subnet_id      = dependency.vpc.outputs.subnet_id
  security_group = dependency.security_groups.outputs.sg_id
  instance_type  = "t2.micro"
  environment    = "dev"
}

Two things to notice here:
First, config_path points to the folder of the dependency, not a specific file. Terragrunt knows where to find the outputs.
Second, mock_outpouts provides fake values for when you run terragrunt plan without the dependencies being deployed yet. this allows you to validate your configuration before deploying anything.

The Complete Project Structure

Here is the complete project structure for a dev environment with separated state files:

project/
├── terragrunt.hcl                    # Root — remote state defined once
└── dev/
    ├── vpc/
    │   ├── terragrunt.hcl
    │   └── main.tf                   # VPC + Subnets
    ├── security-groups/
    │   ├── terragrunt.hcl
    │   └── main.tf                   # Security Groups
    ├── rds/
    │   ├── terragrunt.hcl
    │   └── main.tf                   # RDS Database
    └── ec2/
        ├── terragrunt.hcl
        └── main.tf                   # EC2 Instances

Each component exposes its key values through Terraform outputs, which are then consumed by dependent components via the dependency block.
Here is how the dependency chain flows:

vpc/
  └── outputs: vpc_id, subnet_id
        │
        ├─────────────────────────┐
        ▼                         ▼
security-groups/                 ec2/
  inputs: vpc_id            inputs: subnet_id
  outputs: sg_id                  │
        │                         │
        └─────────────────────────┘
                    ▼
                  ec2/
             inputs: sg_id

Terragrunt reads this dependency graph automatically and deploys components in the correct order: VPC first, then security groups, then EC2. You never have to think about the deployment order manually.
The VPC component is the simplest, it has no dependencies:

# dev/vpc/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

inputs = {
  environment = "dev"
  vpc_cidr    = "10.0.0.0/16"
}

And its main.tf exposes the values that other components need:

# dev/vpc/main.tf

output "vpc_id" {
  value = aws_vpc.main.id
}

output "subnet_id" {
  value = aws_subnet.public.id
}

The outputs are what the dependency block reads when EC2 asks for dependency.vpc.outputs.subnet_id.

The full code for this project structure is available in the GitHub repository

Deploying with Dependency Blocks

Once your structure is in place, deploying is as simple as one command from the dev/ folder:

terragrunt run-all apply

Terragrunt automatically:

Reads the dependency graph across all components
Deploys in the correct order — VPC → Security Groups → EC2
Passes outputs from one component as inputs to the next
Creates a separate state file in S3 for each component

You can also target individual components:

# Redeploy only EC2 — VPC and Security Groups are untouched
cd dev/ec2/
terragrunt apply

# Check outputs of a specific component
cd dev/vpc/
terragrunt output

# Destroy in reverse order automatically
cd dev/
terragrunt run-all destroy

Notice the power here: when you run terragrunt apply in dev/ec2/ only, Terraform touches only the EC2 state file. Your VPC and database state files are completely safe, even if something goes wrong.

The mock_outputs - Why They Matter

When you run terragrunt plan on EC2 component before the VPC is deployed, Terragrunt needs values for subnet.id and sg.id to validate the configuration. Since the real values don't exist yet, mock_outputs provides temporary placeholders:

dependency "vpc" {
  config_path = "../vpc"

  mock_outputs = {
    subnet_id = "subnet-00000000"
  }

  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

The mock_outputs_allowed_terraform_commands parameter ensures that mock values are only used during validate and plan, never during apply. This prevents accidental deployments with fake values.

A Note on Security
Before wrapping up, a quick but important note on security, raised by Paul Marcelin in the comments of Part 1.
When your state files are separated by component, you have a natural opportunity to apply different IAM permissions per component. For example:

Developers can have read/write access to the EC2 state file
Only senior engineers or CI/CD pipelines can access the VPC and RDS state files
Production state files can be encrypted with dedicated KMS keys per environment.

This is a significant security improvement over a single state file where everyone has access to everything. Separating state files is the first step, securing them with IAM policies and KMS encryption is the natural next step.
For a deep dive on Terraform state file security, I recommend this LinkedIn post by Yaroslav Naumenko: "Your Terraform state file is a secret. Most teams don't treat it that way."

Conclusion

Let's recap what we covered in this article:

The problem: a monolithic state file creates a dangerous blast radius where routine operations can accidentally affect critical infrastructure
The solution: Terragrunt dependency blocks allow each component to have its own isolated state file
The dependency block reads outputs from other components without sharing their state
mock_outputs allow you to validate configurations before dependencies are deployed
terragrunt run-all apply automatically respects the dependency order
Separating state files is also the foundation for better security, different IAM permissions per component.

Together, Part 1 and Part 2 give you a complete Terragrunt workflow:

Part 1 → One root terragrunt.hcl    = No repeated backend configs
Part 2 → Dependency blocks          = No more monolithic state files

If you found this helpful, share it and follow me for the next article in the series.
The code for this article is available on my GitHub.

Stop Copy-Pasting Terraform State Configs: Use Terragrunt instead

Jeancy Joachim Mukaka — Mon, 13 Apr 2026 14:31:31 +0000

Prerequisites
Before getting started, make sure you have the following:

Basic knowledge of Terraform (HCL Syntax, resources, variables, remote state), the full prerequisite code is available in the GitHub repository
Terraform installed on your machine (v0.12 or higher)
Terragrunt installed, check the official installation guide
An AWS account with suffficient permissions to create S3 buckets and DynamoDB tables
AWS CLI configured with your credentials (aws configure)
Visual Studio Codes as your code editor, with the HashiCorp Terraform extension for syntax highlighting and autocompletion.

Introduction

If you have been working with Terraform for a while, you have probably faced this situation: you have a working configuration for your dev environment, and now you need to deploy the same infrastructure to staging and prod. So you copy the folder, update a few values, including the remote state backend configuration, and repeat. It works, but something feels wrong.
That "something" is a violation of the DRY principle, don't repeat yourself. Every time you duplicate your backend configuration, you create a new opportunity for error and a new file to maintain.
In this article, we will explore how Terragrunt solves this problem by allowing you to define your remote state configuration once and reuse it across all your environments.
If you are new to terraform, I recommend exploring prerequisite code on GitHub before diving in.

The Problem: Repeat Remote State

When managing multiple environments with Terraform, most developers end up with a structure like this:

environments/
├── dev/
│   └── main.tf
├── staging/
│   └── main.tf
└── prod/
    └── main.tf

And inside each main.tf, the same backend block appears with only one line changing:

# dev/main.tf
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "dev/terraform.tfstate"
    region         = "us-west-2"
    use_lockfile   = true 
    encrypt        = true
  }
}

The same block is then copy-pasted into staging/main.tf and prod/main.tf, with only the key value changing (staging/terraform.tfstate, prod/terraform.tfsate). That's three files, three times the same configuration. And if you ever need to change the bucket name, the region, or encryption, you have to update every single file manually. This is exactly the kind of repetition that leads to human error and maintenance nightmares.

What is Terragrunt?

Terragrunt is a thin wrapper around Terraform, developed by Gruntwork, It doesn't replace Terraform, it enhances it by providing additional tools to keep your configurations DRY, manageable, and consistent across environments.
Think of it this way: Terraform is the engine, and Terragrunt is the intelligent framework built around it. You still write the same HCL code you know, but Terragrunt handless the repetitive parts for you.
With Terragrunt you can:

Define your remote state configuration once and reuse it across all environments
Automatically create your S3 bucket and DynamoDB table if they don't exist
Deploy multiple environments with a single command
Keep your codebase clean, readable, and easy to maintain The key concept we'll focus on in this article is the remote_state block — the feature that eliminates repeated backend configurations across environments.

The Solution: Centralized Remote State with Terragrunt

Instead of repeating the backend configuration in every environment, Terragrunt lets you define it once in a root terragrunt hcl file:

project/
├── terragrunt.hcl        ← defined once here
├── dev/
│   └── terragrunt.hcl    ← only what changes
├── staging/
│   └── terragrunt.hcl    ← only what changes
└── prod/
    └── terragrunt.hcl    ← only what changes

The root terragrunt.hcl contains the full remote state configuration:

# terragrunt.hcl (root)
remote_state {
  backend = "s3"

  config = {
  bucket       = "your-terraform-state-bucket"
  key          = "${path_relative_to_include()}/terraform.tfstate"
  region       = "us-west-2"
  encrypt      = true
  use_lockfile = true   # Native S3 locking — replaces DynamoDB (Terraform v1.11+)
}

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

Update: As of Terraform v1.11, DynamoDB-based state
locking is deprecated. This example uses native S3 locking
via use_lockfile = true. Thanks to Paul Marcelin for
pointing this out!

Each environment file simply inherits from the root. Here is the dev example:

# dev/terragrunt.hcl
include "root" {
  path = find_in_parent_folders()
}

inputs = {
  environment   = "dev"
  instance_type = "t2.micro"
}

The staging and prod files follow the exact same structure, only the environment and instance_type values change. That's it. Three environments, three small files, each containing only what is unique to that environment. The backend configuration lives in one place and is never repeated.
The full project structure with all environments is available in the GitHub repository.

Key Terragrunt Functions Explained

Two functions make all of this possible. Understanding them is the key to mastering Terragrunt.

find_in_parent_folders() This funtcion automatically searches parent directories for the root terragrunt.hcl file. It allows each environment file to inherit the root configuration without hardcoding the path.

include "root" {
  path = find_in_parent_folders()  # finds ../../terragrunt.hcl automatically
}

No matter how deeply nested your environment folder is, Terragrunt will always find the root configuration.

path_relative_to_include() This is the function that makes the state key dynamic. It returns the relative path of the current environment folder from the root.

key = "${path_relative_to_include()}/terraform.tfstate"

Concretely, this means:

| Environment folder | Generated state key |
| :--- | :--- |
| `dev/` | `dev/terraform.tfstate` |
| `staging/` | `staging/terraform.tfstate` |
| `prod/` | `prod/terraform.tfstate` |

Each environment automatically gets its own isolated state file in S3, with zero manual configuration.

The generate Block

This block is often overlooked but extremely powerful. It tells Terragrunt to automatically generate a backend.tf file in each environment folder before running Terraform.

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

This means you never have to manually write a backend.tf file again. Terragrunt generates it for you, every time, with the correct values.

Deploying All Environments

once your configuration is in place, deploying all environments is as simple as running a single command from the root folder:

# Deploy all environments at once
terragrunt run-all apply

Terragrunt will automatically:

Detect all terragrunt.hcl files in subdirectories
Run terraform init for each environment
Deploy each environment in the correct order
Create the S3 bucket and DynamoDB table if they don't exist yet you can also target a specific environment:

# Deploy only dev
cd dev/
terragrunt apply

# Check outputs across all environments
terragrunt run-all output

# Destroy all environments
terragrunt run-all destroy

Compare this to the old approach where you had to navigate into each folder manually, run terraform init, then terraform apply, and repeat for every environment. With Terragrunt, that entire workflow collapses into one command.

Conclusion

Managing Terraform remote state across multiple environments doesn't have to be painful. With Terragrunt's remotestate block, find_in_parent_folders(), and path_relative_to_include(), you can define your backend configuration once and let Terragrunt handle the rest.
Let's recap what we covered:

The problem: repeated backend configuration across environments violate DRY principle
The solution: a single root terragrunt.hcl that centralizes the remote state configuration
The magic functions: find_in_parent_folders() and path_relative_to_include()that make everything dynamic
The power of Terragrunt run-all apply: deploy all environments in one command. This is just the beginning of what Terragrunt can do. In the next article, Part 2, we will go deeper and explore how to split your Terraform dependency blocks. You will learn why putting your VPC, your security groups, and your EC2 instances in the same state file is a risk and how to fix it.

If you found this article helpful, feel free to share it and follow me for Part 2. The code for this article is available on my GitHub.