• 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 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

bash scripts/validate_terragrunt.sh [TARGET_DIR]

• 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

• SKIP_PLAN=true

  - Skip terragrunt plan step

• SKIP_SECURITY=true

  - Skip security scanning (Trivy/tfsec)

• SKIP_LINT=true

  - Skip tflint linting

• TG_STRICT_MODE=true

  - Enable strict mode (errors on deprecated features)

undefined

python3 scripts/detect_custom_resources.py [DIRECTORY] [--format text|json]

• Custom Terraform providers (non-HashiCorp)
• Remote modules (Git, Terraform Registry, HTTP)
• Provider versions
• Module versions and sources

• text

  - Human-readable report with search recommendations

• json

  - Machine-readable format for automation

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 documentation:

       mcp__context7__get-library-docs

       with the resolved library ID
     • Use

       topic: "authentication"

       or

       topic: "configuration"

       for targeted docs
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__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
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__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

undefined

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

undefined

• 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

You MUST read the best practices reference file BEFORE starting validation. This is not optional.

undefined

1. Understand the structure:
   bash

   tree -L 3 <infrastructure-directory>

2. Identify Terragrunt files:
   bash

   find . -name "*.hcl" -o -name "terragrunt.hcl"

3. Detect custom resources:
   bash

   python3 scripts/detect_custom_resources.py .

CRITICAL: If ANY custom providers or modules are detected, you MUST look up documentation for EACH ONE. Do not skip any.

1. For EACH detected custom provider - look up documentation:
   • Use Context7 MCP (preferred):

     1. mcp__context7__resolve-library-id

        with provider name

     2. mcp__context7__get-library-docs

        with topic: "authentication"

     3. mcp__context7__get-library-docs

        with topic: "configuration"
   • OR use WebSearch:

     "{provider} terraform provider {version} documentation"

2. For EACH detected custom module - look up documentation:
   • Use Context7 MCP for Terraform Registry modules:

     1. mcp__context7__resolve-library-id

        with module name (e.g., "terraform-aws-modules vpc")

     2. mcp__context7__get-library-docs

        with relevant topic
   • For Git modules: Use WebSearch with repository URL
   • For HTTP modules: Investigate source URL for documentation
3. Document findings for each resource:
   • Required configuration blocks
   • Authentication requirements
   • Known issues or breaking changes in the version

1. Run comprehensive validation:
   bash

   bash scripts/validate_terragrunt.sh <target-directory>

2. Review output for errors:
   • Format errors → Fix with

     terragrunt hcl fmt

   • 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

You MUST verify each checklist item below and document the result (✅ pass or ❌ fail). Incomplete verification is not acceptable.

1. 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:
   bash

   # 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

1. Common issues and resolutions:

rm -rf .terragrunt-cache
terragrunt init

• Check provider configuration in generated files
• Verify environment variables or credentials
• Review provider documentation from WebSearch

• Check dependency paths are correct
• Ensure mock_outputs are provided for validation
• Review dependency graph with

  terragrunt dag graph

terragrunt force-unlock <LOCK_ID>

• Re-run custom resource detection
• Use WebSearch to look up current documentation
• Check version compatibility

ERROR: The file path ./versions.tf already exists and was not generated by terragrunt.
Can not generate terraform file: ./versions.tf already exists

.tf

generate

• Remove the conflicting static files (

  versions.tf

  ,

  provider.tf

  ,

  backend.tf

  )
• Or use

  if_exists = "skip"

  in the generate block to not overwrite existing files

# Remove conflicting files
rm -f versions.tf provider.tf backend.tf
rm -rf .terragrunt-cache

WARN: Using `terragrunt.hcl` as the root of Terragrunt configurations is an anti-pattern

root.hcl

terragrunt.hcl

mv terragrunt.hcl root.hcl
# Update include blocks in child modules to reference root.hcl

• terragrunt (>= 0.93.0 recommended for new CLI)
• terraform or opentofu (>= 1.6.0 recommended)

• tflint - HCL linting
• trivy - Security scanning (replaces tfsec)
• checkov - Alternative security scanner (750+ built-in policies)
• graphviz (dot) - Dependency visualization
• jq - JSON parsing
• python3 - For custom resource detection script

• tfsec - Merged into Trivy, no longer actively maintained

undefined

1. Resolve library ID:

   mcp__context7__resolve-library-id with libraryName: "mongodb/mongodbatlas"

2. Get documentation:

   mcp__context7__get-library-docs with context7CompatibleLibraryID: "/mongodb/mongodbatlas"

• Clear cache:

  rm -rf .terragrunt-cache

• Re-initialize:

  terragrunt init

• Check provider configuration
• Run custom resource detection
• Use WebSearch to find correct provider source and version
• Verify required_providers block

• Check Terragrunt version compatibility
• Review function syntax in documentation

• Review dependency chains
• Consider refactoring into single module
• Use data sources instead of dependencies

• Check if another process is running
• Verify DynamoDB table (for S3 backend)
• Force unlock if safe:

  terragrunt force-unlock <LOCK_ID>

• Terragrunt 0.93+ has a new CLI with breaking changes
• Commands like

  render-json

  ,

  validate-inputs

  are deprecated
• Use

  terragrunt run -- <command>

  for custom/unsupported commands
• Replace

  graph-dependencies

  with

  dag graph

• See: https://terragrunt.gruntwork.io/docs/migrate/cli-redesign/

• All HCL files properly formatted
• Inputs are valid
• Terraform configuration is valid
• No linting issues
• No critical security issues
• Valid dependency graph
• Plan generated successfully

• Security warnings from tfsec (non-critical)
• Linting suggestions (best practices)
• Deprecated provider features
• Missing recommended configurations

• Format errors
• Invalid inputs
• Terraform validation failures
• Circular dependencies
• Provider authentication failures
• State locking errors

• scripts/validate_terragrunt.sh

  - Comprehensive validation suite

• scripts/detect_custom_resources.py

  - Custom provider/module detector

• references/best_practices.md

  - Comprehensive best practices guide covering:
  • Directory structure patterns
  • DRY principles and configuration sharing
  • Dependency management
  • Security best practices
  • Testing and validation workflows
  • Common anti-patterns to avoid
  • Troubleshooting guides

• Terragrunt Documentation
• Terraform Best Practices
• Terraform Registry