Understanding Terragrunt Units and Their Importance

What is Terragrunt?

Terragrunt is a tool that helps manage Terraform configurations efficiently. It simplifies infrastructure deployment by reducing code duplication and enforcing best practices.

What are Terragrunt Units?

A Terragrunt Unit is the smallest deployable part of an infrastructure. It is simply a folder that contains a terragrunt.hcl file. This file tells Terragrunt how to run Terraform for that specific part of the infrastructure.

Each Terragrunt unit represents a service or component, such as a database, a virtual network, or an application server. These units help keep infrastructure code organized, reusable, and easy to maintain.

Why are Terragrunt Units Important?

1. Avoids Code Duplication: Instead of writing Terraform code multiple times for different environments (like production, staging, and development), Terragrunt lets you reuse the same module.

2. Better Organization: Each unit is self-contained, making it easy to manage different parts of the infrastructure.

3. Easy to Scale: You can deploy only the units that need changes instead of re-deploying everything.

4. Version Control: Different environments can use different versions of Terraform modules, ensuring stability in production.

5. Automation-Friendly: Terragrunt integrates well with CI/CD pipelines, making automation smoother.

How to Use Terragrunt Units

Folder Structure Example

A common way to organize Terraform projects with Terragrunt looks like this:

project-root/
  ├── modules/
  │   ├── app/
  │   │   └── main.tf
  │   ├── database/
  │   │   └── main.tf
  │   ├── network/
  │       └── main.tf
  ├── environments/
  │   ├── production/
  │   │   ├── app/
  │   │   │   └── terragrunt.hcl
  │   │   ├── database/
  │   │   │   └── terragrunt.hcl
  │   │   └── network/
  │   │       └── terragrunt.hcl
  │   ├── staging/
  │   │   ├── app/
  │   │   │   └── terragrunt.hcl
  │   │   ├── database/
  │   │   │   └── terragrunt.hcl
  │   │   └── network/
  │   │       └── terragrunt.hcl

Writing a terragrunt.hcl File

Each unit contains a terragrunt.hcl file that tells Terragrunt how to fetch and apply Terraform configurations.

Example terragrunt.hcl file for the app unit in the staging environment:

terraform {
  source = "git::git@github.com:my-org/modules.git//app?ref=v1.0.0"
}

inputs = {
  instance_count = 3
  instance_type  = "t3.micro"
}

Deploying a Terragrunt Unit

To apply a Terragrunt unit, navigate to the directory and run:

cd environments/staging/app
terragrunt apply

This will:

1. Download the Terraform module from the specified source.

2. Pass the input variables (like instance_count and instance_type).

3. Deploy the infrastructure component.

Updating a Terragrunt Unit

To update a unit, change the terragrunt.hcl file (e.g., updating the ref to a new version) and then run:

terragrunt apply

Destroying a Terragrunt Unit

To delete a unit, run:

terragrunt destroy

Conclusion

Terragrunt units make Terraform deployments simpler, reusable, and easier to manage. By organizing infrastructure into small, independent units, you can deploy changes faster and with fewer errors. If you are working with Terraform, Terragrunt is a powerful tool that can save time and effort while keeping infrastructure well-structured.