akin-ozer/cc-devops-skills/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. 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)

1. 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)
export TG_STRICT_MODE=true
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