How to Use Terragrunt: Simplify Terraform Configurations

Use terragrunt as a wrapper for terraform to manage infrastructure with reusable configurations, remote state management, and dependency handling. Create a terragrunt.hcl file to define your infrastructure modules and run terragrunt apply to deploy.

Syntax

The basic syntax of Terragrunt involves creating a terragrunt.hcl file that points to your Terraform module and configures remote state and dependencies.

Key parts include:

• terraform { source = "..." }: Specifies the Terraform module source.
• remote_state { ... }: Configures where Terraform stores its state remotely.
• dependencies { ... }: Defines dependencies on other modules.

hcl

terraform {
  source = "git::https://github.com/example/terraform-modules.git//module-path"
}

remote_state {
  backend = "s3"
  config = {
    bucket = "my-terraform-state"
    key    = "path/to/my/terraform.tfstate"
    region = "us-east-1"
  }
}

dependencies {
  paths = ["../vpc"]
}

Example

This example shows a terragrunt.hcl file that uses a Terraform module from a Git repo, configures remote state in an S3 bucket, and depends on a VPC module.

Running terragrunt apply will deploy the infrastructure defined in the module with state stored remotely.

hcl

terraform {
  source = "git::https://github.com/gruntwork-io/terraform-aws-eks.git//modules/eks-cluster"
}

remote_state {
  backend = "s3"
  config = {
    bucket = "my-terraform-state-bucket"
    key    = "eks/cluster/terraform.tfstate"
    region = "us-west-2"
  }
}

dependencies {
  paths = ["../vpc"]
}

Output

Initializing modules...

Applying changes to infrastructure...

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Common Pitfalls

Common mistakes when using Terragrunt include:

• Not specifying the source in terraform {}, so Terragrunt doesn't know which module to use.
• Misconfiguring remote state backend, causing state conflicts or loss.
• Forgetting to run Terragrunt commands from the directory with terragrunt.hcl.
• Incorrect dependency paths causing modules to apply in the wrong order.

Always double-check paths and backend configs before applying.

hcl

## Wrong: Missing source
terraform {
  # source missing here
}

## Right: Specify source
terraform {
  source = "git::https://github.com/example/module.git"
}

Quick Reference

Remember these tips when using Terragrunt:

• Always define terraform { source = "..." } to point to your module.
• Configure remote_state to keep your Terraform state safe and shared.
• Use dependencies to manage module order and inputs.
• Run Terragrunt commands like terragrunt plan and terragrunt apply from the folder with terragrunt.hcl.

Key Takeaways

Terragrunt wraps Terraform to simplify managing reusable infrastructure code.

Define your module source and remote state in a terragrunt.hcl file.

Use dependencies to control the order of module deployment.

Always run Terragrunt commands in the directory containing terragrunt.hcl.

Check remote state and source paths carefully to avoid errors.