Beginner's Guide to Terragrunt

Stop the copy-paste madness

Ceyda Duzgec

SREday London Q3 2025

About Me - Ceyda Duzgec

Cloud & Platform Engineer at Sufle, Istanbul
Sufle: AWS Partner in Türkiye - Leading cloud transformation
Education:
- • BSc in Computer Science & Engineering
- • MS in Software Engineering
Certifications:
- • AWS Solutions Architect Associate
- • HashiCorp Terraform Associate
- • Certified Kubernetes Administrator (CKA) - In progress
Open Source: Maintainer of github.com/Hipo/university-domains-list
This is my first talk at SREday!

Connect with me or Stalk me

Picture This Monday Morning

The Infrastructure Copy-Paste Nightmare

Your dev environment works perfectly. Now you need staging and production.

Dev Environment

Works perfectly

➡️

Copy & Paste

To staging & prod

➡️

3x the Maintenance

3x the errors

Copy your entire Terraform directory 2 more times
Manually change variables in each copy
Set up S3 backends for each environment by hand
Pray that you didn't miss anything when copying
Repeat this process for every new project

Sound familiar? There's a better way.

What We'll Cover

What is Terragrunt?

The solution to your infrastructure management problems

Core Concepts & Examples

Real configurations and practical usage

Getting Started

Path forward

Q&A Session

Questions and discussion

Scan for slides

The Problems with Pure Terraform

Multiple Environments

Copy-paste everything

State Management

Manual backend setup

Dependencies

Complex inter-module deps

Code Duplication: Same configurations copied across environments
Remote State Management: Manual backend configuration for each module
Environment Management: No native way to promote configs between environments
Dependency Management: Complex inter-module dependencies
Configuration Drift: Hard to maintain consistency across projects

What is Terragrunt?

Terragrunt is a thin wrapper around Terraform that eliminates repetition by Gruntwork.io

Think of it as Terraform's Smart Assistant

Generates backend configurations automatically
Organizes your state files
Shares common settings across environments
Manages dependencies between modules
Keeps your code DRY (Don't Repeat Yourself)

Let's Dive Into Terragrunt

terragrunt.hcl

Configuration file

+

Terraform Module

Reusable infrastructure

=

DRY Infrastructure

Consistent & maintainable

Terragrunt acts as an orchestrator, managing your Terraform modules across environments

One module definition → Multiple environment deployments

Terraform vs Terragrunt

Aspect	Terraform	Terragrunt
Configuration	Verbose, repetitive	DRY, reusable
Remote State	Manual setup	Automatic generation
Multi-Environment	Complex	Built-in support
Dependencies	Limited	Advanced dependency management
Code Maintenance	High effort	Minimal effort

Before vs After: File Structure

Before (Pure Terraform)

dev/ ├── main.tf (300 lines) ├── variables.tf ├── backend.tf └── terraform.tfvars staging/ ├── main.tf (same 300 lines!) ├── variables.tf ├── backend.tf └── terraform.tfvars prod/ ├── main.tf (same 300 lines!) ├── variables.tf ├── backend.tf └── terraform.tfvars

900 lines of duplicate code!

After (With Terragrunt)

modules/ └── vpc/ ├── main.tf (300 lines) └── variables.tf environments/ ├── dev/terragrunt.hcl (10 lines) ├── staging/terragrunt.hcl (10 lines) └── prod/terragrunt.hcl (10 lines)

330 lines total. 70% reduction!

Core Terragrunt Concepts

terragrunt.hcl: Configuration file that defines Terragrunt behavior
Remote State: Automatically configured backend storage
Inputs: Variables passed to Terraform modules
Dependencies: Define module execution order
Include: Inherit configuration from parent files
Generate: Create files dynamically (provider configs, etc.)

Typical Terragrunt Project Structure

Let's see a typical project structure:

infrastructure/ │ ├── modules/ │ ├── vpc/ │ │ ├── main.tf │ │ └── variables.tf │ └── rds/ │ ├── main.tf │ └── variables.tf └──environments/ ├── dev/ │ ├── common_vars.yaml # Dev common variables │ ├── root.hcl # Dev environment config │ ├── vpc/ │ │ └── terragrunt.hcl # VPC module config │ └── rds/ │ └── terragrunt.hcl # RDS module config ├── staging/ │ ├── common_vars.yaml # Staging common variables │ ├── root.hcl # Staging environment config │ ├── vpc/ │ │ └── terragrunt.hcl # ... (similar structure) │ └── rds/ │ └── terragrunt.hcl └── prod/ ├── common_vars.yaml # Production common variables ├── root.hcl # Production environment config ├── vpc/ │ └── terragrunt.hcl # ... (similar structure) └── rds/ └── terragrunt.hcl

Simple Terragrunt Configuration

Let's break down the configuration files:

root.hcl

remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  config = {
    bucket = "dev-terragrunt-state-bucket"
    key    = "${path_relative_to_include()}/terraform.tfstate"
    region = "us-west-2"
  }
}

common_vars.yaml

# Common variables for dev environment

environment: "dev"
region: "us-west-2"
availability_zones:
  - "us-west-2a"
  - "us-west-2b"
project_name: "my-project"
tags:
  Environment: "Dev"
  Team: "Infrastructure"
  Project: "MyApp"

Your First Terragrunt Configuration

Here's what a terragrunt.hcl file looks like:

# vpc/terragrunt.hcl
terraform {
  source = "git::https://github.com/your-org/modules//vpc"
}

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

locals {
  common_vars            = yamldecode(file(find_in_parent_folders("common_vars.yaml")))
}

inputs = {
  environment        = local.common_vars.environment
  vpc_cidr           = "10.0.0.0/16"
  availability_zones = ["us-west-2a", "us-west-2b"]
}

# Backend is auto-generated!

That's it! No backend configuration needed.

Smart Dependency Management

Terragrunt knows what order to deploy things:

# rds/terragrunt.hcl
dependency "vpc" {
  config_path = "../vpc"
}

inputs = {
  vpc_id        = dependency.vpc.outputs.vpc_id
  subnet_ids    = dependency.vpc.outputs.private_subnet_ids
}

Terragrunt automatically runs VPC first, then database!

Essential Terragrunt Commands

terragrunt plan → Same as terraform plan, but with Terragrunt features
terragrunt apply → Apply changes with dependency resolution
terragrunt run-all plan → Run plan across all modules in directory
terragrunt run-all apply → Apply all modules in correct order
terragrunt destroy → Destroy infrastructure
terragrunt validate → Validate configuration
terragrunt graph-dependencies → Visualize dependencies

Automatic S3 State Management

Terragrunt automatically organizes your state files:

S3 Bucket Structure

dev-terragrunt-state-bucket/ ├── vpc/terraform.tfstate ├── rds/terraform.tfstate └── app/terraform.tfstate staging-terragrunt-state-bucket/ ├── vpc/terraform.tfstate ├── rds/terraform.tfstate └── app/terraform.tfstate prod-terragrunt-state-bucket/ ├── vpc/terraform.tfstate ├── rds/terraform.tfstate └── app/terraform.tfstate

Isolated State

Each module gets its own state file

Environment Separation

Clear boundaries between dev/staging/prod

Automatic Paths

No manual backend configuration

When You Might Skip Terragrunt

Single Environment: If you only have one environment and no plans to expand
Simple Setups: Very basic infrastructure with no module dependencies
Team Learning: If your team is still learning basic Terraform
CI/CD Constraints: Some CI/CD systems work better with plain Terraform
Quick Prototypes: When you need to spin up something quickly for testing

Remember: You can always add Terragrunt later when your infrastructure grows!

Getting Started Today

Step 1

Install Terragrunt

→

Step 2

Create terragrunt.hcl

→

Step 3

Run terragrunt plan

Quick Start Steps:

Setup: Add your Cloud Provider account credentials
Install: brew install terragrunt
Create your first terragrunt.hcl
Module: Point to an existing Terraform module
Run: terragrunt plan
Deploy: terragrunt apply

You can add Terragrunt to existing Terraform projects incrementally!

Key Takeaways

Stop copy-pasting Terraform configurations between environments
Terragrunt generates backends automatically - no more manual S3 setup
Dependencies are handled automatically with correct deployment order
Start small - add it to one environment first
70% code reduction in typical multi-environment setups
Works seamlessly with existing Terraform modules

💡 Bottom Line: If you're managing multiple environments with Terraform, Terragrunt will save you time, reduce errors, and make your infrastructure code more maintainable.

Thank You!

Slides & Examples

Connect with me

Feedback Form

Questions?

Let's chat about Terragrunt, AWS, or infrastructure automation!

github.com/ceydaduzgec | linkedin.com/in/ceydaduzgec