Terragrunt Validator

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

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"

1. 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

1. 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. mcpcontext7resolve-library-id with libraryName: "{provider/module name}"
2. mcpcontext7query-docs with:

• libraryId: "{resolved ID}"
• query: "authentication requirements" (for auth requirements)

1. mcpcontext7query-docs with:

• libraryId: "{resolved ID}"
• query: "configuration examples" (for setup requirements)
• OR use WebSearch with version-specific queries
• Review documentation for:
• Required configuration blocks
• Authentication requirements (API keys, credentials)
• Available resources/data sources
• Known issues or breaking changes in the version c) Apply learnings to validation/troubleshooting d) Document findings if issues are encountered ```

Example using Context7 MCP:

# 1. Detect custom resources
python3 scripts/detect_custom_resources.py ./infrastructure
# Output: Provider: datadog/datadog, Version: 3.30.0

# 2. Resolve library ID
mcp__context7__resolve-library-id with libraryName: "datadog terraform provider"
# Result: /datadog/terraform-provider-datadog

# 3. Fetch authentication docs (REQUIRED)
mcp__context7__query-docs with:
  libraryId: "/datadog/terraform-provider-datadog"
  query: "authentication requirements"

# 4. Fetch configuration docs
mcp__context7__query-docs with:
  libraryId: "/datadog/terraform-provider-datadog"
  query: "configuration examples"

Example using WebSearch:

# Detect custom resources
python3 scripts/detect_custom_resources.py ./infrastructure

# Then search for documentation:
# WebSearch: "datadog terraform provider 3.30.0 authentication configuration"
# WebSearch: "datadog terraform provider api_key app_key setup"

3. Step-by-Step Validation

For manual or granular validation, use these individual commands:

Format Validation

cd <target-directory>
terragrunt hcl fmt --check

# To auto-fix formatting
terragrunt hcl fmt

Configuration Validation

# Check HCL syntax and formatting
terragrunt hcl fmt --check

# Note: In Terragrunt 0.93+, for deeper configuration validation,
# initialize and validate (requires actual resources/credentials):
# terragrunt init && terragrunt validate

Terraform Validation

# Initialize if needed
terragrunt init

# Validate
terragrunt validate

Linting with tflint

# Initialize tflint (if .tflint.hcl exists)
tflint --init

# Run linting