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 | 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 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:** ```bash # 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: ```bash 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:** ```bash # 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 ```bash cd <target-directory> terragrunt hcl fmt --check # To auto-fix formatting terragrunt hcl fmt ``` #### Configuration Validation ```bash # 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 ```bash # Initialize if needed terragrunt init # Validate terragrunt validate ``` #### Linting with tflint ```bash # 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. ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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`): ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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 ```bash # 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) ```bash # Get contextual information about current configuration terragrunt info print # Output includes: # - config_path # - download_dir # - terraform_binary # - working_dir ``` #### Find and List Units ```bash # 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 ```bash # 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 ```hcl # 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 ```bash # 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: ```hcl unit "experimental" {