/terragrunt-validator

name: terragrunt-validator
description: Validate, lint, audit, or check Terragrunt .hcl/terragrunt.hcl files, stacks, modules, compliance.

Terragrunt Validator

Overview

This skill provides comprehensive validation, linting, and testing capabilities for Terragrunt configurations. Terragrunt is a thin wrapper for Terraform/OpenTofu that provides extra tools for keeping configurations DRY (Don't Repeat Yourself), working with multiple modules, and managing remote state.

**Use this skill when:**

• Validating Terragrunt HCL files (*.hcl, terragrunt.hcl, terragrunt.stack.hcl)
• Working with Terragrunt Stacks (unit/stack blocks, `terragrunt stack generate/run`)
• Performing dry-run testing with `terragrunt plan`
• Linting Terragrunt/Terraform code for best practices
• Detecting and researching custom providers or modules
• Debugging Terragrunt configuration issues
• Checking dependency graphs
• Formatting HCL files
• Running security scans on infrastructure code (Trivy, Checkov)
• Generating run reports and summaries

Terragrunt Version Compatibility

This skill is designed for **Terragrunt 0.93+** which includes the new CLI redesign.

CLI Command Migration Reference

| Deprecated Command | New Command | |-------------------|-------------| | `run-all` | `run --all` | | `hclfmt` | `hcl fmt` | | `hclvalidate` | `hcl validate` | | `validate-inputs` | `hcl validate --inputs` | | `graph-dependencies` | `dag graph` | | `render-json` | `render --json -w` | | `terragrunt-info` | `info print` | | `plan-all`, `apply-all` | `run --all plan`, `run --all apply` |

Key Changes in 0.93+:

• `terragrunt run --all` replaces `terragrunt run-all` for multi-module operations
• `terragrunt dag graph` replaces `terragrunt graph-dependencies` for dependency visualization
• `terragrunt hcl validate --inputs` replaces `validate-inputs` for input validation
• HCL syntax validation via `terragrunt hcl fmt --check` or `terragrunt hcl validate`
• Full validation requires `terragrunt init && terragrunt validate`

If using an older Terragrunt version, some commands may need adjustment.

Core Capabilities

1. Comprehensive Validation Suite

Run the comprehensive validation script to perform all checks at once:

bash scripts/validate_terragrunt.sh [TARGET_DIR]

**What it validates:**

• HCL formatting (`terragrunt hcl fmt --check`)
• HCL input validation (`terragrunt hcl validate --inputs`)
• Terragrunt configuration syntax
• Terraform configuration validation
• Linting with tflint
• Security scanning with Trivy (or legacy tfsec)
• Dependency graph validation
• Dry-run planning

**Environment variables:**

• `SKIP_PLAN=true` - Skip terragrunt plan step
• `SKIP_SECURITY=true` - Skip security scanning (Trivy/tfsec)
• `SKIP_LINT=true` - Skip tflint linting
• `SKIP_INIT=true` - Skip `terragrunt init` before validation
• `SKIP_BACKEND_INIT=true` - Run init with `-backend=false` (useful in CI/offline)
• `SOFT_FAIL_SECURITY=true` - Report security findings without failing
• `TG_STRICT_MODE=true` - Enable strict mode (errors on deprecated features)

**Example usage:**

# Full validation
bash scripts/validate_terragrunt.sh ./infrastructure/prod

# Skip plan generation (faster)
SKIP_PLAN=true bash scripts/validate_terragrunt.sh ./infrastructure

# Only validate, skip linting and security
SKIP_LINT=true SKIP_SECURITY=true bash scripts/validate_terragrunt.sh

2. Custom Provider and Module Detection

Use the detection script to identify custom providers and modules that may require documentation lookup:

python3 scripts/detect_custom_resources.py [DIRECTORY] [--format text|json]

**What it detects:**

• Custom Terraform providers (non-HashiCorp)
• Remote modules (Git, Terraform Registry, HTTP)
• Provider versions
• Module versions and sources

**Output formats:**

• `text` - Human-readable report with search recommendations
• `json` - Machine-readable format for automation

**When custom resources are detected:**

> **CRITICAL: You MUST look up documentation for EVERY detected custom resource (both providers AND modules). Do NOT skip any. This is mandatory, not optional.**

1. **For custom providers:**

• **Option A - WebSearch:** Search for provider documentation
• Query format: `"{provider_source} terraform provider documentation version {version}"`
• Example: `"mongodb/mongodbatlas terraform provider documentation version 1.14.0"`
• **Option B - Context7 MCP (Preferred):** Use Context7 for structured documentation lookup
• Step 1: Resolve library ID: `mcp__context7__resolve-library-id` with provider name (e.g., "datadog terraform provider")
• Step 2: **REQUIRED** - Fetch docs via `mcp__context7__query-docs` with the resolved library ID
• Use queries like `"authentication requirements"` and `"configuration examples"`

2. **For custom modules (EQUALLY IMPORTANT - DO NOT SKIP):**

• **Terraform Registry modules:**
• Use Context7: `mcp__context7__resolve-library-id` with module name (e.g., "terraform-aws-modules vpc")
• Then fetch docs with `mcp__context7__query-docs`
• Or visit `https://registry.terraform.io/modules/{source}/{version}`
• **Git modules:** Use WebSearch with the repository URL to find README or documentation
• **HTTP modules:** Investigate the source URL for documentation
• Pay attention to version compatibility with your Terraform/Terragrunt version

3. **Documentation lookup workflow (MANDATORY for ALL detected resources):**

   a) Run detect_custom_resources.py
   b) For EACH custom provider/module:
      - Note the exact version
      - Use Context7 MCP:
        1. mcp__context7__resolve-library-id with libraryName: "{provider/module name}"
        2. mcp__context7__query-docs with:
           - libraryId: "{resolved ID}"
           - query: "authentication requirements" (for auth requirements)
        3. mcp__context7__query-docs with:
           - libraryId: "{resolved ID}"
           - que