terragrunt-validator

What this skill does

# 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 --recurs