Terragrunt vs Terraform: A Practical Guide

Infrastructure as Code (IaC) tools have revolutionized how teams manage and provision their cloud resources. Among these tools, Terraform and its wrapper, Terragrunt, are two popular choices. While Terraform is an excellent tool for defining and provisioning infrastructure, Terragrunt enhances it with features that simplify management, especially for large-scale, multi-environment setups. This article explores the key differences between Terraform and Terragrunt, their unique features, and practical examples to help you understand when and how to use each tool.

---

Prerequisites

Before diving into Terragrunt and Terraform, ensure the following prerequisites are met:

1. Install Terraform:

   • Download the latest Terraform binary from Terraform Downloads.

   • Add the binary to your system's PATH.

   • Verify the installation:

       terraform version
     

2. Install Terragrunt:

   • Download the latest Terragrunt binary from Terragrunt Releases.

   • Add the binary to your system's PATH.

   • Verify the installation:

       terragrunt version
     

3. Install Terraform and Terragrunt on Ubuntu:

   • Update your system and install dependencies:

       sudo apt update
       sudo apt install -y curl unzip
     

   • Install Terraform:

       curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
       echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
       sudo apt update
       sudo apt install terraform
     

   • Install Terragrunt:

       curl -L https://github.com/gruntwork-io/terragrunt/releases/latest/download/terragrunt_linux_amd64 -o terragrunt
       chmod +x terragrunt
       sudo mv terragrunt /usr/local/bin/
     

   • Verify installations:

       terraform version
       terragrunt version
     

4. Configure AWS CLI (if using AWS):

   • Install AWS CLI and configure it with your credentials:

       aws configure
     

5. Access to Terraform Code:

   • Ensure you have existing Terraform code or modules ready to be integrated with Terragrunt.

---

What is Terraform?

Terraform is an open-source IaC tool developed by HashiCorp. It allows users to define, provision, and manage infrastructure resources using a declarative configuration language called HCL (HashiCorp Configuration Language). Terraform enables consistent and repeatable provisioning of infrastructure across various cloud providers like AWS, Azure, GCP, and on-premise systems.

Key Features of Terraform:

• Modularity: Supports reusable modules for resource definitions.

• State Management: Tracks infrastructure changes using a state file.

• Multi-Provider Support: Works with multiple cloud providers and third-party services.

• Plan and Apply: Allows you to preview changes before applying them.

---

What is Terragrunt?

Terragrunt is a lightweight wrapper around Terraform that simplifies and enhances its functionality. It is designed to make working with Terraform in complex environments easier by focusing on code reuse, managing dependencies, and simplifying remote state configurations.

Key Features of Terragrunt:

• Code Reuse with DRY Principle: Share and reuse Terraform configurations using terragrunt.hcl files.

• Remote State Management: Automates backend configurations for Terraform’s state files.

• Dependency Management: Easily manage dependencies between Terraform modules.

• Dynamic Configuration: Inject variables dynamically for different environments (e.g., dev, staging, prod).

• Execution Wrapper: Adds features like locking, retries, and fail-safe execution for Terraform commands.

---

Key Differences Between Terraform and Terragrunt

---

Practical Examples

Example 1: Basic Terraform Setup

Here’s an example of setting up an S3 bucket using Terraform:

Folder Structure

project
├── main.tf
├── variables.tf
└── outputs.tf

main.tf

provider "aws" {
  region = var.region
}

resource "aws_s3_bucket" "example" {
  bucket = var.bucket_name
  acl    = "private"
}

variables.tf

variable "region" {
  default = "us-east-1"
}

variable "bucket_name" {}

outputs.tf

output "bucket_name" {
  value = aws_s3_bucket.example.bucket
}

To deploy:

terraform init
terraform plan
terraform apply

---

Example 2: Terragrunt Setup for Multi-Environment Management

Let’s enhance the above example for managing multiple environments using Terragrunt.

Folder Structure

project
├── modules
│   └── s3
│        ├── main.tf
│        ├── variables.tf
│        └── outputs.tf
├── environments
    ├── dev
    │   └── terragrunt.hcl
    ├── staging
    │   └── terragrunt.hcl
    └── prod
        └── terragrunt.hcl

modules/s3/main.tf

resource "aws_s3_bucket" "example" {
  bucket = var.bucket_name
  acl    = "private"
}

variable "bucket_name" {}

environments/dev/terragrunt.hcl

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

inputs = {
  bucket_name = "dev-bucket"
}

remote_state {
  backend = "s3"
  config = {
    bucket         = "terraform-state"
    key            = "dev/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

environments/prod/terragrunt.hcl

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

inputs = {
  bucket_name = "prod-bucket"
}

remote_state {
  backend = "s3"
  config = {
    bucket         = "terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

To deploy the dev environment:

cd environments/dev
terragrunt init
terragrunt plan
terragrunt apply

---

Benefits of Using Terragrunt

1. Centralized State Management: Automates remote state configurations, reducing manual effort and errors.

2. Reusability: DRY principle eliminates code duplication across environments.

3. Dependency Management: Automatically resolves dependencies, streamlining multi-module workflows.

4. Multi-Environment Support: Simplifies managing environments like dev, staging, and prod.

5. Ease of Scaling: Easily add new environments or resources with minimal changes.

---

When to Use Terraform vs Terragrunt

Use Terraform When:

• You are managing a single environment or a small project.

• You want direct control over backend configurations and state management.

• The complexity of dependencies and multi-environment setups is low.

Use Terragrunt When:

• You are managing multi-environment setups (e.g., dev, staging, prod).

• You want to enforce the DRY principle for reusable configurations.

• Your project involves complex state management and dependencies.

---

Conclusion

Terraform and Terragrunt are both powerful tools, each suited for different use cases. While Terraform is an excellent choice for defining and provisioning infrastructure, Terragrunt simplifies and enhances its functionality for large-scale, multi-environment projects. By understanding the key differences and applying the practical examples shared in this guide, you can choose the right tool for your infrastructure needs and improve the efficiency of your workflows.

Ready to simplify your Terraform workflows? Give Terragrunt a try in your next project!