Terragrunt Ally

Your specialized agent for managing complex Terraform deployments with Terragrunt, enabling DRY infrastructure code, multi-account orchestration, and dependency management across environments.

When to Use This Agent

Choose Terragrunt Ally when:

• Managing multi-account, multi-region Terraform deployments with Terragrunt
• Reducing Terraform code duplication using Terragrunt's DRY patterns
• Orchestrating dependencies between Terraform modules across environments
• Implementing Terragrunt configurations for enterprise landing zones
• Migrating from raw Terraform to Terragrunt for better organization

Consider alternatives when:

• You have a simple single-account Terraform setup — use a standard Terraform agent
• You prefer Terraform Cloud/Enterprise for orchestration — use a Terraform engineer agent
• You need infrastructure design without IaC tooling — use a cloud architect agent

Quick Start

Copy
# .claude/agents/terragrunt-ally.yml
name: Terragrunt Ally
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Terragrunt specialist for DRY infrastructure code, multi-account orchestration, and dependency management

Example invocation:

claude "Set up a Terragrunt project structure for a multi-account AWS deployment with shared networking, per-account EKS clusters, and centralized monitoring"

Core Concepts

Terragrunt Project Structure

infrastructure-live/
├── terragrunt.hcl           # Root config (remote state, provider generation)
├── _envcommon/               # Shared variable definitions
│   ├── networking.hcl
│   ├── compute.hcl
│   └── database.hcl
├── dev/
│   ├── account.hcl           # Account-specific vars
│   ├── us-east-1/
│   │   ├── region.hcl
│   │   ├── vpc/terragrunt.hcl
│   │   ├── eks/terragrunt.hcl
│   │   └── rds/terragrunt.hcl
│   └── us-west-2/
│       └── ...
├── staging/
│   └── ...
└── prod/
    └── ...

Key Terragrunt Features

Feature	Purpose	Example
include	Inherit parent configs	include "root" { path = find_in_parent_folders() }
dependency	Declare inter-module dependencies	dependency "vpc" { config_path = "../vpc" }
generate	Auto-generate provider/backend blocks	Generate provider.tf with account creds
inputs	Pass variables to Terraform modules	inputs = { vpc_id = dependency.vpc.outputs.vpc_id }
run_all	Orchestrate multiple modules together	terragrunt run-all apply

Configuration

Parameter	Description	Default
source_base	Base path for Terraform modules	git::[email protected]:org/modules.git
state_bucket_pattern	State bucket naming pattern	{account}-{region}-terraform-state
account_structure	Account layout (flat, ou-based)	ou-based
lock_table	DynamoDB table for state locking	terraform-locks
terragrunt_version	Terragrunt CLI version	>= 0.55.0

Best Practices

1. Use find_in_parent_folders() to keep configs DRY. Define remote state, provider generation, and common variables in the root terragrunt.hcl, then use include blocks in leaf configs. Each leaf config should only contain what's unique to that specific deployment.

2. Declare explicit dependencies between modules. Use dependency blocks to tell Terragrunt which modules must apply before others. This enables safe run-all apply commands that respect ordering — networking before compute, compute before monitoring.

3. Use _envcommon for shared module configurations. Extract shared variable definitions and module sources into _envcommon/*.hcl files. Each environment's terragrunt.hcl then merges these common configs with environment-specific overrides.

4. Pin module source versions per environment. Use different ref tags for dev, staging, and prod so module upgrades flow through environments sequentially. Dev gets the latest, prod gets the proven version.

5. Use mock_outputs for plan-time dependency resolution. When running terragrunt plan before dependencies are applied, mock_outputs provides placeholder values so the plan can complete. This is essential for CI pipelines that plan all modules in parallel.

Common Issues

run-all apply fails partway through the dependency chain. When one module fails, dependent modules can't proceed. Use --terragrunt-non-interactive with --terragrunt-ignore-dependency-errors carefully in CI, or better, fix the failing module first. Run run-all plan before apply to catch errors early.

Circular dependencies between modules cause deadlocks. Terragrunt can't resolve circular dependency blocks. Restructure your modules to break the cycle — often by extracting shared resources (like VPC) into a separate module that both sides depend on instead of depending on each other.

State bucket doesn't exist for a new account/region. Terragrunt can auto-create state buckets with remote_state { ... config = { ... } } and generate blocks, but this requires the initial credentials to have bucket-creation permissions. Use a bootstrap script that creates the state bucket and DynamoDB lock table before running Terragrunt for the first time.