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"

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}"
           - 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
tflint --recursive

Security Scanning with Trivy (Recommended)

Note: tfsec has been merged into Trivy and is no longer actively maintained. Use Trivy for all new projects.

# Using Trivy (recommended)
trivy config . --severity HIGH,CRITICAL

# With tfvars file
trivy config --tf-vars terraform.tfvars .

# Exclude downloaded modules
trivy config --tf-exclude-downloaded-modules .

# Legacy: Using tfsec (deprecated)
tfsec . --soft-fail

Alternative: Security Scanning with Checkov

# Scan directory
checkov -d . --framework terraform

# Scan with specific checks
checkov -d . --check CKV_AWS_21

# Output as JSON
checkov -d . --output json

Dependency Graph Validation

# Note: graph-dependencies command replaced with 'dag graph' in Terragrunt 0.93+
# Validate and display dependency graph
terragrunt dag graph

# Visualize dependencies (requires graphviz)
terragrunt dag graph | dot -Tpng > dependencies.png

Dry-Run Planning

# Single module
terragrunt plan

# All modules (new syntax - Terragrunt 0.93+)
terragrunt run --all plan

# Legacy syntax (deprecated)
# terragrunt run-all plan

4. Multi-Module Operations

For projects with multiple Terragrunt modules, use run --all (replaces deprecated run-all):

# Validate all modules
terragrunt run --all validate

# Plan all modules
terragrunt run --all plan

# Apply all modules
terragrunt run --all apply

# Destroy all modules
terragrunt run --all destroy

# Format all HCL files
terragrunt hcl fmt

# With parallelism
terragrunt run --all plan --parallelism 4

# With strict mode (errors on deprecated features)
terragrunt --strict-mode run --all plan

# Or via environment variable
TG_STRICT_MODE=true terragrunt run --all plan

5. HCL Input Validation (New in 0.93+)

Validate that all required inputs are set and no unused inputs exist:

# Validate inputs
terragrunt hcl validate --inputs

# Show paths of invalid files
terragrunt hcl validate --show-config-path

# Combine with run --all to exclude invalid files
terragrunt run --all plan --queue-excludes-file <(terragrunt hcl validate --show-config-path || true)

6. Strict Mode

Enable strict mode to catch deprecated features early:

# Via CLI flag
terragrunt --strict-mode run --all plan

# Via environment variable (recommended for CI/CD)

terragrunt run --all plan

# Check available strict controls
terragrunt info strict

Specific Strict Controls:

For finer-grained control, use --strict-control to enable specific controls:

# Enable specific strict controls
terragrunt run --all plan --strict-control cli-redesign --strict-control deprecated-commands

# Via environment variable (comma-separated)
TG_STRICT_CONTROL='cli-redesign,deprecated-commands' terragrunt run --all plan

# Available strict controls:
# - cli-redesign: Errors on deprecated CLI syntax
# - deprecated-commands: Errors on deprecated commands (run-all, hclfmt, etc.)
# - root-terragrunt-hcl: Errors when using root terragrunt.hcl (use root.hcl instead)
# - skip-dependencies-inputs: Improves performance by not reading dependency inputs
# - bare-include: Errors on bare include blocks (use named includes)

7. New CLI Commands (0.93+)

Render Configuration

# Render configuration to JSON
terragrunt render --json

# Render and write to file
terragrunt render --json --write

# Output goes to terragrunt.rendered.json

Info Print (replaces terragrunt-info)

# Get contextual information about current configuration
terragrunt info print

# Output includes:
# - config_path
# - download_dir
# - terraform_binary
# - working_dir

Find and List Units

# Find all units/stacks in directory
terragrunt find

# Output as JSON
terragrunt find --json

# Include dependency information
terragrunt find --json --dag

# List units (simpler output)
terragrunt list

Run Summary and Reports

# Run with summary output (default in newer versions)
terragrunt run --all plan

# Disable summary output
terragrunt run --all plan --summary-disable

# Generate detailed report file
terragrunt run --all plan --report-file=report.json

# CSV format report
terragrunt run --all plan --report-file=report.csv

8. Terragrunt Stacks (GA in v0.78.0+)

Terragrunt Stacks provide declarative infrastructure generation using terragrunt.stack.hcl files.

Stack File Structure

# terragrunt.stack.hcl
locals {
  environment = "dev"
  aws_region  = "us-east-1"
}

# Define a unit (generates a single terragrunt.hcl)
unit "vpc" {
  source = "git::git@github.com:acme/infra-catalog.git//units/vpc?ref=v0.0.1"
  path   = "vpc"

  values = {
    environment = local.environment
    cidr        = "10.0.0.0/16"
  }
}

unit "database" {
  source = "git::git@github.com:acme/infra-catalog.git//units/database?ref=v0.0.1"
  path   = "database"

  values = {
    environment = local.environment
    vpc_path    = "../vpc"
  }
}

# Include reusable stacks
stack "monitoring" {
  source = "git::git@github.com:acme/infra-catalog.git//stacks/monitoring?ref=v0.0.1"
  path   = "monitoring"

  values = {
    environment = local.environment
  }
}

Stack Commands

# Generate stack (creates .terragrunt-stack directory)
terragrunt stack generate

# Generate stack without validation
terragrunt stack generate --no-stack-validate

# Run command on all stack units
terragrunt stack run plan
terragrunt stack run apply

# Clean generated stack directories
terragrunt stack clean

# Get stack outputs
terragrunt stack output

Stack Validation Control

Use no_validation attribute to skip validation for specific units:

unit "experimental" {
  source = "git::git@github.com:acme/infra-catalog.git//units/experimental?ref=v0.0.1"
  path   = "experimental"

  # Skip validation for this unit (useful for incomplete/experimental units)
  no_validation = true

  values = {
    environment = local.environment
  }
}

Benefits of Stacks

• Clean working directory: Generated code in hidden .terragrunt-stack directory
• Reusable patterns: Define infrastructure patterns once, deploy many times
• Version pinning: Different environments can pin different versions
• Atomic updates: Easy rollbacks of both modules and configurations

9. Exec Command (Run Arbitrary Programs)

The exec command allows you to run arbitrary programs against units with Terragrunt context. This is useful for integrating other tools like tflint, checkov, or AWS CLI with Terragrunt's configuration.

# Run tflint with unit context (TF_VAR_ env vars available)
terragrunt exec -- tflint

# Run checkov against specific unit
terragrunt exec -- checkov -d .

# Run AWS CLI with unit's configuration
terragrunt exec -- aws s3 ls