As Terraform grows in popularity for managing infrastructure as code, tools that enhance its usability and manageability become increasingly valuable. Terragrunt is one such tool, designed to work as a wrapper, providing extra tools and features to help manage complex Terraform configurations more efficiently. In this post, we’ll explore the basics of Terragrunt, how it enhances Terraform’s capabilities, and guide you through its initial setup and basic usage.

What is Terragrunt?

Terragrunt is a thin wrapper that provides additional features for keeping Terraform configurations DRY (Don’t Repeat Yourself), working with multiple Terraform modules, and managing remote state configuration seamlessly. It’s built to provide an extra layer of configuration to avoid repetition and to manage dependencies more effectively.

Key Features of Terragrunt

  • Keep Your Terraform Code DRY: Terragrunt allows you to write your Terraform code once and reuse it across multiple environments, reducing duplication and simplifying maintenance.
  • Remote State Management: Automatically manage your state files in remote storage like AWS S3, which is essential for team collaboration and keeping state data secure.
  • Dependency Management: Terragrunt can handle dependencies between your Terraform projects, ensuring that your infrastructure is applied in the correct order.

Getting Started with Terragrunt

Prerequisites

Before you begin, you’ll need to have the following installed:

  • Terraform
  • Terragrunt

You can download and install Terraform from HashiCorp’s official site and Terragrunt from its GitHub repository.

Step 1: Setting Up Your Directory Structure

A typical Terragrunt setup involves a directory structure where each environment (like staging, production) is kept in separate directories, each containing a terragrunt.hcl file:

project/
│
├── staging/
│   └── terragrunt.hcl
│
└── production/
    └── terragrunt.hcl

Step 2: Configuring Terragrunt

Each terragrunt.hcl file contains configuration specific to that environment. Below is a basic example of what this file might look like:

# terragrunt.hcl
terraform {
  source = "git::git@github.com:user/repo.git//modules/aws-vpc?ref=v0.1.0"
}

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

# Include all settings from the root terragrunt.hcl file
include {
  path = find_in_parent_folders()
}

This configuration specifies:

  • The source of the Terraform module.
  • How to manage the remote_state.
  • An include to use common settings from a parent terragrunt.hcl file, aiding in keeping your configurations DRY.

Step 3: Running Terragrunt

Navigate to the directory of the specific environment and run Terragrunt commands that are similar to Terraform’s:

cd staging
terragrunt apply

Terragrunt will automatically handle the configuration of the remote state, and any dependencies defined, then run terraform apply with the appropriate settings and parameters.

Conclusion

Terragrunt is a powerful tool for anyone looking to streamline their Terraform workflow. By managing remote state, reducing duplication through DRY principles, and handling dependencies more effectively, Terragrunt can significantly simplify the management of complex or large-scale Terraform configurations. Whether you are working solo or as part of a larger team, incorporating Terragrunt into your Terraform projects can lead to more maintainable and easier-to-manage infrastructure as code.

Gotchas and Tips

  • Version Compatibility: Always ensure that your Terragrunt version is compatible with your Terraform version.
  • Debugging: Use terragrunt plan to preview changes without applying them, which can be invaluable for catching issues early.
  • Automation: Integrate Terragrunt with your CI/CD pipeline to automate your infrastructure deployments for different environments.