Comprehensive toolkit for validating, linting, testing, and automating Terragrunt configurations, HCL files, and Stacks. Use this skill when working with Terragrunt files (.hcl, terragrunt.hcl, terragrunt.stack.hcl), validating infrastructure-as-code, debugging Terragrunt configurations, performing dry-run testing with terragrunt plan, working with Terragrunt Stacks, or working with custom providers and modules.
Comprehensive toolkit for validating, linting, testing, and automating Terragrunt configurations, HCL files, and Stacks. Use this skill when working with Terragrunt files (.hcl, terragrunt.hcl, terragrunt.stack.hcl), validating infrastructure-as-code, debugging Terragrunt configurations, performing dry-run testing with terragrunt plan, working with Terragrunt Stacks, or working with custom providers and modules.
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.
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.
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 documentation: mcp__context7__get-library-docs with the resolved library ID
Use topic: "authentication" or topic: "configuration" for targeted docs
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__get-library-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
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__get-library-docs with:
- context7CompatibleLibraryID: "{resolved ID}"
- topic: "authentication" (for auth requirements)
- topic: "configuration" (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
# 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
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.
# 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 s3://my-bucket
# Run custom scripts with Terragrunt context
terragrunt exec -- ./scripts/validate.sh
# Run across all units
terragrunt run --all exec -- tflint
Key Features:
Terragrunt loads the inputs for the unit and makes them available as TF_VAR_ prefixed environment variables
Works with any program that can use environment variables
Integrates with Terragrunt's authentication context (e.g., AWS profiles)
Can be combined with run --all for multi-unit operations
Use Cases:
Running security scanners (checkov, trivy) with unit context
Executing linters (tflint) per unit
Running operational commands (AWS CLI) with correct credentials
Custom validation scripts that need Terragrunt inputs
10. Feature Flags (Production Feature)
Terragrunt supports first-class Feature Flags for safe infrastructure changes. Feature flags allow you to integrate incomplete work without risk, decouple release from deployment, and codify IaC evolution.
# Enable a feature flag
terragrunt plan --feature enable_monitoring=true# Enable multiple feature flags
terragrunt plan --feature enable_monitoring=true --feature use_new_vpc=false# Via environment variable
TG_FEATURE='enable_monitoring=true' terragrunt plan
Feature Flags with run --all
# Apply feature flag across all units
terragrunt run --all plan --feature enable_monitoring=true
Benefits:
Safe rollouts: Test changes on subset of infrastructure
Gradual migrations: Enable new features incrementally
Emergency rollbacks: Quickly disable problematic features
11. Experiments (Opt-in Unstable Features)
Terragrunt provides an experiments system for trying unstable features before they're GA:
# Enable all experiments (not recommended for production)
terragrunt --experiment-mode run --all plan
# Enable specific experiment
terragrunt --experiment symlinks run --all plan
# Enable CAS (Content Addressable Storage) for faster cloning
terragrunt --experiment cas run --all plan
Available Experiments:
symlinks - Support symlink resolution for Terragrunt units
cas - Content Addressable Storage for faster Git/module cloning
filter-flag - Advanced filtering capabilities (coming in 1.0)
Validation Workflow
Follow this workflow when validating Terragrunt configurations:
Step 0: Read Best Practices Reference (MANDATORY FIRST STEP)
You MUST read the best practices reference file BEFORE starting validation. This is not optional.
# Read the best practices reference file firstcat references/best_practices.md
This ensures you understand the patterns, anti-patterns, and checklists you will verify.
Initial Assessment
Understand the structure:
tree -L 3 <infrastructure-directory>
Identify Terragrunt files:
find . -name "*.hcl" -o -name "terragrunt.hcl"
Detect custom resources:
python3 scripts/detect_custom_resources.py .
Documentation Lookup (MANDATORY for ALL detected custom resources)
CRITICAL: If ANY custom providers or modules are detected, you MUST look up documentation for EACH ONE. Do not skip any.
For EACH detected custom provider - look up documentation:
Use Context7 MCP (preferred):
mcp__context7__resolve-library-id with provider name
mcp__context7__get-library-docs with topic: "authentication"
mcp__context7__get-library-docs with topic: "configuration"
OR use WebSearch: "{provider} terraform provider {version} documentation"
For EACH detected custom module - look up documentation:
Use Context7 MCP for Terraform Registry modules:
mcp__context7__resolve-library-id with module name (e.g., "terraform-aws-modules vpc")
mcp__context7__get-library-docs with relevant topic
For Git modules: Use WebSearch with repository URL
For HTTP modules: Investigate source URL for documentation
Configuration errors → Check terragrunt.hcl syntax and inputs
Terraform validation errors → Check .tf files or generated configs
Linting issues → Review tflint output and fix
Security issues → Review tfsec output and address
Dependency errors → Check dependency blocks and paths
Plan errors → Review Terraform configuration and provider setup
Best Practices Check (REQUIRED - Must Complete All Checklists)
You MUST verify each checklist item below and document the result (✅ pass or ❌ fail). Incomplete verification is not acceptable.
Perform explicit best practices verification using references/best_practices.md:
Configuration Pattern Checklist - verify each item:
[ ] Include blocks: Child modules use `include "root" { path = find_in_parent_folders("root.hcl") }`
[ ] Named includes: All include blocks have names (not bare `include {}`)
[ ] Root file naming: Root config is named `root.hcl` (not `terragrunt.hcl`)
[ ] Environment configs: Environment-level configs named `env.hcl` (not `terragrunt.hcl`)
[ ] Common variables: Shared variables in `common.hcl` read via `read_terragrunt_config()`
Dependency Management Checklist:
[ ] Mock outputs: ALL dependency blocks have mock_outputs for validation
[ ] Mock allowed commands: mock_outputs_allowed_terraform_commands includes ["validate", "plan", "init"]
[ ] Explicit paths: Dependency config_path uses relative paths ("../vpc" not absolute)
[ ] No circular deps: Run `terragrunt dag graph` to verify no cycles
Security Checklist:
[ ] State encryption: remote_state config has `encrypt = true`
[ ] State locking: DynamoDB table configured for S3 backend
[ ] No hardcoded credentials: Search for patterns like "AKIA", "password =", account IDs
[ ] Sensitive variables: Passwords/keys use `sensitive = true` in variable blocks
[ ] IAM roles: Provider uses assume_role instead of static credentials
DRY Principle Checklist:
[ ] Generate blocks: Provider and backend configs use `generate` blocks
[ ] Version constraints: terragrunt_version_constraint and terraform_version_constraint set
[ ] Reusable locals: Common values in shared files, not duplicated
[ ] if_exists: Generate blocks use appropriate if_exists strategy
Quick grep checks to run:
# Check for hardcoded AWS account IDs
grep -r "[0-9]\{12\}" --include="*.hcl" . | grep -v mock
# Check for potential credentials
grep -ri "password\s*=" --include="*.hcl" .
grep -ri "api_key\s*=" --include="*.hcl" .
# Check for dependencies without mock_outputs
grep -l "dependency\s" --include="*.hcl" -r . | xargs grep -L "mock_outputs"# Check for terragrunt.hcl files in non-module directories (anti-pattern)
find . -name "terragrunt.hcl" -not -path "*/.terragrunt-cache/*" | head -20
