Why I Use Terragrunt Over Terraform/OpenTofu in 2025

Code Duplication

For managing multiple environments with Terraform, there are two possibilities:

1. Using folder duplication.
   
2. Using Terraform Workspaces.

Let’s start with the first option.

In this scenario, you would build your Terraform modules under the modules directory and create one directory per environment (dev, staging, and prod).

Resulting in the following tree:

project/
├── modules/
│   └── vpc/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
├── environments/
│   ├── dev/
│   │   ├── provider.tf      # Duplicated
│   │   ├── backend.tf       # Duplicated (different S3 key)
│   │   ├── variables.tf     # Duplicated
│   │   ├── outputs.tf       # Duplicated
│   │   └── main.tf          
│   ├── staging/
│   │   ├── provider.tf      # Duplicated
│   │   ├── backend.tf       # Duplicated (different S3 key)
│   │   ├── variables.tf     # Duplicated
│   │   ├── outputs.tf       # Duplicated
│   │   └── main.tf          
│   └── prod/
│       ├── provider.tf      # Duplicated
│       ├── backend.tf       # Duplicated (different S3 key)
│       ├── variables.tf     # Duplicated
│       ├── outputs.tf       # Duplicated
│       └── main.tf          # module "vpc" { source = "../../modules/vpc" }

Each main.tf instantiates the vpc module. You can directly see the problem here: we need to redefine provider.tf, backend.tf, variables.tf, and outputs.tf in each environment folder.

That’s a lot of duplication! Any change to shared configuration needs to be manually copied to every environment.

Manual Backend State Setup

Following the example from the previous section, you would also need to write the backend configuration for each environment:

# dev/backend.tf
terraform {
  backend "s3" {
    bucket         = "myproject-terraform-state"
    key            = "dev/terraform.tfstate"
    region         = "us-west-2"
    dynamodb_table = "terraform-locks-dev"
  }
}

# staging/backend.tf  
terraform {
  backend "s3" {
    bucket         = "myproject-terraform-state"
    key            = "staging/terraform.tfstate"
    region         = "us-west-2"
    dynamodb_table = "terraform-locks-staging"
  }
}

Each environment needs its own unique S3 key to avoid state conflicts.

Here’s the worst: you can’t use variables here! Terraform simply doesn’t allow them in backend blocks.

You will also need to create the S3 bucket manually before anyone can run terraform init.

Usually, this means running a separate Terraform configuration just for the backend infrastructure, or clicking through the AWS console.

The whole process becomes a headache that only gets worse as you add more environments and team members.

You got it right! Each time you need to create an additional environment, you’ll need to copy and paste an environment folder and manually change all the keys.

No Built-in Orchestration

Terraform CLI can only work on one directory at a time. It has no idea that your modules depend on each other.

Here’s a typical application stack:

dev/
├── vpc/           # Must deploy FIRST
├── database/      # Must deploy SECOND (needs VPC)  
├── app-servers/   # Must deploy THIRD (needs database)
└── load-balancer/ # Must deploy FOURTH (needs app servers)

To deploy this stack, you have to manually run commands in dependency order:

cd dev/vpc && terraform apply
cd ../database && terraform apply  
cd ../app-servers && terraform apply
cd ../load-balancer && terraform apply

Following such an error-prone process in a production environment is not realistic.

HashiCorp introduced Terraform Stacks to address dependency management and orchestration problems. But it’s locked behind their paid Terraform Cloud platform.

Avoids Code Duplication

Terragrunt follows the Don’t Repeat Yourself (DRY) principle.

Instead of duplicating files across environments, you define shared configurations once and inherit them in child configurations.

Here’s what the same structure looks like with Terragrunt:

project/
├── root.hcl                 # Shared configuration
├── modules/
│   └── vpc/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── live/
    ├── dev/
    │   └── terragrunt.hcl   # Only environment-specific values
    └── prod/
        └── terragrunt.hcl    # Only environment-specific values

The root.hcl defines the provider configuration once:

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
terraform {
  required_version = ">= 1.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = var.aws_region
}
EOF
}

# We'll cover remote_state configuration later

Each environment configuration instantiates the Terraform vpc module while changing environment variables:

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

locals {
  env = "prod"
}

terraform {
  source = "../../modules/vpc"
}

inputs = {
  environment       = local.env
  vpc_name          = "myproject-${local.env}"
  azs               = ["us-west-2a", "us-west-2b"]  # Availability zones list
}

The dev environment would be identical except env = "dev" and only one availability zone, for example azs = ["us-west-2a"].

include blocks let child configurations inherit everything from the parent. Terragrunt automatically generates the provider.tf file in each environment:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-west-2"
}

It prevents the duplication of the Terraform version, the AWS provider version, and the provider block.

Supports Automated Backend State Isolation

Remember the manual backend configuration nightmare from earlier? Terragrunt eliminates all of that.

You define the backend configuration once in your root.hcl file, and Terragrunt automatically handles unique state isolation for each environment:

# root.hcl

# Configuration from earlier plus:
remote_state {
  backend = "s3"

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

  config = {
    bucket         = "myproject-terraform-state"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "us-west-2"
    encrypt        = true
    dynamodb_table = "my-lock-table"
  }
}

It literally does the coffee for you: Terragrunt automatically creates the S3 bucket and DynamoDB table if they don’t exist.

No more bootstrap scripts or clicking manually on the AWS console!

The path_relative_to_include() function automatically generates unique S3 keys based on the directory structure.

Your prod environment produces prod/terraform.tfstate, while dev generates dev/terraform.tfstate. No manual key configuration, no copy-paste backend files!

Unlike Terraform’s backend blocks, Terragrunt can use dynamic values and local variables in backend configuration.

You write the backend setup once, and it works correctly across all environments without any manual intervention.

Has Built-in Orchestration

Remember the custom CI/CD scripts and manual orchestration from earlier? Terragrunt eliminates that entirely with native dependency management.

Here’s how you can structure related modules:

project/
├── root.hcl
├── live/
│   ├── prod/
│   │   ├── env.hcl              # Environment-specific values
│   │   ├── database/
│   │   │   └── terragrunt.hcl
│   │   └── app/
│   │       └── terragrunt.hcl
│   └── dev/
│       ├── env.hcl              # Environment-specific values
│       ├── database/
│       │   └── terragrunt.hcl
│       └── app/
│           └── terragrunt.hcl
└── modules/
   ├── app/
   │   ├── main.tf
   │   └── …
   └── database/
       └── main.tf

Environment-specific values are declared in one place:

# live/prod/env.hcl
locals {
  environment = "prod"
}

Here’s the database module with no dependency:

# live/prod/database/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}
 
# Read the locals from env.hcl
locals {
  env = read_terragrunt_config(find_in_parent_folders("env.hcl")).locals.environment
}
terraform {
  source = "../../../modules/database"
}

inputs = {
  environment = local.env
  db_name     = "db-${local.env}"
}

The app module declares its dependency and uses the db_endpoint output from the database module:

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

# Read the locals from env.hcl
locals {
  env = read_terragrunt_config(find_in_parent_folders("env.hcl")).locals.environment
}


dependency "database" {
  config_path = "../database"
}

terraform {
  source = "../../modules/app"
}

inputs = {
  environment = local.env
  db_host     = dependency.database.outputs.db_endpoint
}

Terragrunt automatically understands that the database must deploy before the app.

One command deploys everything in the correct order:

terragrunt run-all apply

Much more elegant, isn’t it?

Definitions

Let me start with the basics first:

• Unit: A Terragrunt wrapper around a Terraform module. Defines a single, deployable piece of infrastructure.
  
• Stack: Defines a collection of related units that can be reused.

Making The Example Even DRYer

In the previous example, we still had to copy Terragrunt configurations in each environment directory. prod/app/terragrunt.hcl and dev/app/terragrunt.hcl were still duplicated.

With Terragrunt Stacks, we can factorize that too!

First, we will move prod/app/terragrunt.hcl and prod/database/terragrunt.hcl to the units directory without changing their content.

Next, we define the pattern (app + database) once in a stack file:

# stacks/web-app/terragrunt.stack.hcl
unit "database" {
  source = "git::git@github.com/yourorg/infrastructure-modules.git//units/database?ref=v1.0.0"
  path   = "database"
}

unit "app" {
  source = "git::git@github.com/yourorg/infrastructure-modules.git//units/app?ref=v1.0.0"
  path   = "app"
}

Then each environment just calls the stack with environment-specific values:

# live/dev/terragrunt.stack.hcl
stack "dev" {
  source = "git::git@github.com/yourorg/infrastructure-modules.git//stacks/web-app?ref=v1.0.1"
  path   = "services"
}

# live/prod/terragrunt.stack.hcl
stack "prod" {
  source = "git::git@github.com/yourorg/infrastructure-modules.git//stacks/web-app?ref=v1.0.0"
  path   = "services"
}

prod and dev are exactly identical. That’s right! Because our units search for the env.hcl file in parent directories, we don’t even have to specify the environment.

You can even point your dev stack to a more recent version v1.0.1 and keep prod on a stable one.

This is already a significant improvement. We’ve eliminated the last bits of duplication.

But honestly, I thought this was just a nice incremental upgrade.

I was wrong.

Nested Stacks

Here’s what I didn’t expect: Terragrunt Stacks can be nested.

For example, you could re-use your web-app stack and add a monitoring stack to it.

# live/prod/web-app-monitoring/terragrunt.stack.hcl
stack "web-app" {
  source = "git::git@github.com/yourorg/infrastructure-modules.git//stacks/web-app?ref=v1.0.0"
  path   = "services-web-app"
}

stack "monitoring" {
  source = "git::git@github.com/yourorg/infrastructure-modules.git//stacks/monitoring?ref=v1.0.0"
  path   = "services-monitoring"
}

Gruntwork is planning to incorporate the ability to use stack outputs as dependencies in the future. This will allow for even greater modularity.

Then it clicked: this isn’t just about eliminating copy-paste anymore.

Pattern Level Re-Use

This is the fundamental shift I completely missed at first.

With this new feature, platform teams aren’t just sharing Terraform modules anymore. They’re packaging and distributing complete infrastructure patterns.

Want to deploy a new microservice? Don’t think about databases, load balancers, monitoring, and networking separately. Just reference the microservice pattern and input your application-specific values.

Need a data pipeline? Reference the data pipeline pattern. It comes with ingestion, processing, storage, and observability already wired together.

Imagine the possibilities: creating a reusable stack that you could easily incorporate into your client’s infrastructures.

Want to learn more? Read Gruntwork’s Terragrunt Stacks article.

Objection 1: Learning Curve

Terragrunt is known in the community to have a steep learning curve.

Yes, I must confess that the onboarding is harder initially.

The inheritance model and generative nature feel painful compared to copy-paste when you’re starting out.

However, I’ve been building and maintaining complex multi-environment infrastructures for RecSys. I’ve found it’s been totally fine!

I’ve even taught junior engineers to work and collaborate in such an environment.

The beauty is, once it clicks, the payoff is huge.

Objection 2: Poor Performance

I’ve found a recurring complaint that Terragrunt is slow and has performance issues.

Terragrunt v0.80 delivered 42% performance improvements, 43% memory reduction, and solved the O(n²) scaling issues that plagued earlier versions.

I’ve never had performance issues deploying and maintaining multiple environments with thousands of resources.

Objection 3: Difficult Debugging

Coming from Terraform, people may find the debugging process more difficult because Terragrunt has longer traces. It applies the infrastructure following a Directed Acyclic Graph (DAG).

I think it is certainly easier to debug than the custom CI/CD workflows needed to work around Terraform’s caveats.

Why I Think These Trade-offs Are Worth It

Look, I’m not going to pretend Terragrunt has zero learning curve or that every team should adopt it.

But when I see a 2025 article from Scalr ranking #1 on Google for Terragrunt drawbacks, I’m baffled to find that all the highlighted problems have been resolved since 2021-2022.

Unfortunately, this leads people to make decisions based on outdated information.

At the time of the writing, Terragrunt has 215 open issues versus 2,350 closed issues. That’s pretty solid for an open-source project.

Bottom line: for teams managing multiple environments with orchestrated deployments, I think Terragrunt is absolutely worth it.