Managing Terragrunt

Terragrunt Management Skill

Manage and inspect Terragrunt configurations, dependencies, and multi-module operations.

MANDATORY: Discovery-First Pattern

Always inspect the dependency graph and configuration before running operations.

Phase 1: Discovery

#!/bin/bash

echo "=== Terragrunt Version ==="
terragrunt --version 2>/dev/null

echo ""
echo "=== Configuration Structure ==="
find . -name "terragrunt.hcl" -not -path "./.terragrunt-cache/*" 2>/dev/null | sort | head -30

echo ""
echo "=== Root Configuration ==="
cat terragrunt.hcl 2>/dev/null | head -20

echo ""
echo "=== Dependency Graph ==="
terragrunt graph-dependencies 2>/dev/null | head -30

Core Helper Functions

#!/bin/bash

# Terragrunt wrapper
tg_cmd() {
    terragrunt "$@" --terragrunt-non-interactive 2>&1
}

# Run in specific module directory
tg_module() {
    local module_dir="$1"
    shift
    terragrunt "$@" --terragrunt-working-dir "$module_dir" --terragrunt-non-interactive 2>&1
}

# Run-all with safety
tg_run_all() {
    terragrunt run-all "$@" --terragrunt-non-interactive 2>&1
}

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Use --terragrunt-non-interactive to prevent prompts
• Filter .terragrunt-cache from file searches
• Use graph-dependencies for visual dependency overview

Common Operations

Dependency Graph Analysis

#!/bin/bash
echo "=== Full Dependency Graph ==="
terragrunt graph-dependencies 2>/dev/null

echo ""
echo "=== Module Dependencies ==="
find . -name "terragrunt.hcl" -not -path "./.terragrunt-cache/*" -exec grep -l 'dependency' {} \; 2>/dev/null | while read f; do
    DIR=$(dirname "$f")
    echo "--- $DIR ---"
    grep -A 3 'dependency "' "$f" 2>/dev/null | grep -E '(dependency|config_path)' | head -5
done | head -40

Run-All Plan

#!/bin/bash
echo "=== Run-All Plan ==="
terragrunt run-all plan --terragrunt-non-interactive 2>&1 | \
    grep -E '(Plan:|No changes|Error|module)' | head -40

echo ""
echo "=== Change Summary by Module ==="
terragrunt run-all plan --terragrunt-non-interactive 2>&1 | \
    grep -E 'Plan:' | head -20

Single Module Operations

#!/bin/bash
MODULE_DIR="${1:?Module directory required}"
ACTION="${2:-plan}"

echo "=== Module: $MODULE_DIR ==="
echo "=== Action: $ACTION ==="

case "$ACTION" in
    plan)
        terragrunt plan --terragrunt-working-dir "$MODULE_DIR" --terragrunt-non-interactive 2>&1 | tail -20
        ;;
    output)
        terragrunt output --terragrunt-working-dir "$MODULE_DIR" --terragrunt-non-interactive -json 2>/dev/null | jq '.'
        ;;
    state)
        terragrunt state list --terragrunt-working-dir "$MODULE_DIR" --terragrunt-non-interactive 2>/dev/null | head -20
        ;;
    validate)
        terragrunt validate --terragrunt-working-dir "$MODULE_DIR" --terragrunt-non-interactive 2>&1
        ;;
esac

Configuration Generation and Inputs

#!/bin/bash
MODULE_DIR="${1:?Module directory required}"

echo "=== Generated Config ==="
terragrunt render-json --terragrunt-working-dir "$MODULE_DIR" 2>/dev/null | jq '{
    terraform_source: .terraform[0].source,
    inputs: (.inputs // {} | keys),
    dependencies: [.dependency // {} | to_entries[] | .key]
}' 2>/dev/null || echo "render-json not available in this version"

echo ""
echo "=== Terragrunt Config ==="
cat "${MODULE_DIR}/terragrunt.hcl" 2>/dev/null | head -40

Multi-Environment Comparison

#!/bin/bash
echo "=== Environment Modules ==="
for env_dir in */; do
    if [ -f "${env_dir}terragrunt.hcl" ] || find "$env_dir" -name "terragrunt.hcl" -maxdepth 2 2>/dev/null | grep -q .; then
        MODULE_COUNT=$(find "$env_dir" -name "terragrunt.hcl" -not -path "*/.terragrunt-cache/*" 2>/dev/null | wc -l | tr -d ' ')
        echo "$env_dir: $MODULE_COUNT modules"
    fi
done

echo ""
echo "=== Cross-Environment Diff ==="
ENV1="${1:-dev}"
ENV2="${2:-prod}"
diff <(find "$ENV1" -name "terragrunt.hcl" -not -path "*/.terragrunt-cache/*" 2>/dev/null | sed "s|$ENV1/||" | sort) \
     <(find "$ENV2" -name "terragrunt.hcl" -not -path "*/.terragrunt-cache/*" 2>/dev/null | sed "s|$ENV2/||" | sort) 2>/dev/null || \
echo "Could not compare environments"

Safety Rules

• NEVER run run-all apply without run-all plan first -- review all module changes
• NEVER use run-all destroy without explicit confirmation and --terragrunt-parallelism 1
• Use --terragrunt-non-interactive to prevent prompts in automation
• Dependency order matters -- run-all respects dependency graph but failures can cascade
• Lock files should be committed to prevent provider version drift across modules

Output Format

Present results as a structured report:

Managing Terragrunt Report
══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Cache corruption: .terragrunt-cache can become stale -- delete it and re-init if seeing odd errors
• Circular dependencies: Terragrunt detects cycles but error messages can be cryptic -- check graph-dependencies
• Source caching: Terraform source is cached -- use --terragrunt-source-update to force refresh
• Input variable type mismatch: Terragrunt inputs must match Terraform variable types exactly
• Remote state config: Backend config is generated -- manual .terraform/ changes will be overwritten
• run-all parallelism: Default parallelism can overwhelm APIs -- use --terragrunt-parallelism to limit
• Relative paths: find_in_parent_folders() walks up -- can match wrong config if directory structure changes
• Include conflicts: Multiple include blocks with overlapping settings cause merge conflicts