Terragrunt

# Quick install (Linux/macOS)
curl -sL https://terragrunt.gruntwork.io/install | bash

# Homebrew
brew install terragrunt

# Binary download
# Download from GitHub releases
# https://github.com/gruntwork-io/terragrunt/releases

• OpenTofu >= 1.6.0 or Terraform >= 0.12.0
• Latest version: v0.99.1

# Initialize
terragrunt init

# Plan changes
terragrunt plan

# Apply changes
terragrunt apply

# Destroy infrastructure
terragrunt destroy

# Show outputs
terragrunt output

# Run across all units
terragrunt run --all plan
terragrunt run --all apply
terragrunt run --all destroy

# Run on dependency graph
terragrunt run --graph apply

# Limit parallelism
terragrunt run --all apply --parallelism 5

# terragrunt.hcl
terraform {
  source = "git::git@github.com:org/modules.git//vpc?ref=v1.0.0"
}

inputs = {
  vpc_name = "main"
  cidr     = "10.0.0.0/16"
  region   = "us-east-1"
}

# Validation and formatting
terragrunt validate
terragrunt fmt

# State refresh
terragrunt refresh

# Import resources
terragrunt import <addr> <id>

# Show dependency graph
terragrunt graph

# List providers
terragrunt providers

# Release state lock
terragrunt force-unlock <lock-id>

# List resources
terragrunt state list

# Show resource details
terragrunt state show <resource>

# Move resources
terragrunt state mv <source> <dest>

# Remove resources
terragrunt state rm <resource>

# Pull state
terragrunt state pull

# Push state
terragrunt state push

# Replace provider
terragrunt state replace-provider <old> <new>

# Mark resource for recreation
terragrunt taint <resource>

# Unmark tainted resource
terragrunt untaint <resource>

# Create backend resources (S3 bucket, DynamoDB table)
terragrunt backend bootstrap

# Migrate state between backends
terragrunt backend migrate

# Delete backend resources
terragrunt backend delete

# Creates S3 bucket with versioning, encryption
# Creates DynamoDB table for locking
terragrunt backend bootstrap

# Generate from stack file
terragrunt stack generate

# Run on stack
terragrunt stack run [cmd]

# Show stack outputs
terragrunt stack output

# Clean generated files
terragrunt stack clean

# Format HCL files
terragrunt hcl fmt

# Validate HCL syntax
terragrunt hcl validate

# Find configurations
terragrunt find

# List configurations
terragrunt list

# Browse modules (TUI)
terragrunt catalog

# Generate from catalog
terragrunt scaffold

# Show merged config
terragrunt render

# Print debug info
terragrunt info print

# Show DOT format graph
terragrunt dag graph

# Generate visual graph
terragrunt dag graph | dot -Tpng > graph.png

# Find units including a file
terragrunt --units-that-include path/to/file

# Debug logging
terragrunt plan --log-level debug

# JSON logging for automation
terragrunt apply --log-format json --non-interactive

# Custom working directory
terragrunt plan --working-dir /path/to/module

# Include/exclude specific directories
--queue-include-dir path/to/dir
--queue-exclude-dir path/to/exclude

# Include external dependencies
--queue-include-external

# Exclude external dependencies
--queue-exclude-external

# Include units reading specific file
--queue-include-units-reading path/to/file

# Load exclusion patterns from file
--queue-excludes-file .terragruntignore

# Ignore dependency order
--queue-ignore-dag-order

# Continue on errors
--queue-ignore-errors

# Only run explicitly included units
--queue-strict-include

# Max parallel executions
--parallelism 5

# Filter by path pattern
terragrunt run --all plan \
  --filter "path:prod/**"

# Filter affected by git changes
terragrunt run --all plan \
  --filter-affected

# Multiple filters
terragrunt run --all apply \
  --filter "path:prod/us-east-1/**" \
  --filter "!path:**/test/**"

# Override source for local development
terragrunt plan --source ../local-modules/vpc

# Update cached modules
terragrunt init --source-update

# Custom cache directory
terragrunt apply --download-dir /tmp/tg-cache

# Assume IAM role
terragrunt apply \
  --iam-assume-role arn:aws:iam::123456789012:role/Admin

# With custom session name
terragrunt apply \
  --iam-assume-role arn:aws:iam::123456789012:role/Admin \
  --iam-assume-role-session-name my-session

# Dynamic auth provider
terragrunt apply \
  --auth-provider-cmd "aws-vault exec prod --"

# Disable auto-init
--no-auto-init

# Disable auto-retry
--no-auto-retry

# Don't add -auto-approve
--no-auto-approve

# Disable auto provider cache
--no-auto-provider-cache-dir

# Save plans for review
terragrunt run --all plan \
  --out-dir /tmp/plans

# Save JSON plans for analysis
terragrunt run --all plan \
  --json-out-dir /tmp/json-plans

# Debug inputs
terragrunt apply --inputs-debug

# Enable provider cache
terragrunt run --all init \
  --provider-cache \
  --provider-cache-dir ~/.terragrunt/provider-cache \
  --provider-cache-port 5758

Benefits: Speeds up terraform init across multiple modules by sharing provider downloads.

# Custom config file
--config custom-terragrunt.hcl

# Path to tofu/terraform binary
--tf-path /usr/local/bin/tofu

# Forward TF stdout directly
--tf-forward-stdout

# Set feature flags
--feature flag_name=true

# Fetch dependency outputs from state
--dependency-fetch-output-from-state

# Use partial parse config cache
--use-partial-parse-config-cache

# Disable backend resource updates
--disable-bucket-update

# Check dependencies on destroy
--destroy-dependencies-check

# Faster dependency resolution
terragrunt apply \
  --dependency-fetch-output-from-state

# Use OpenTofu instead of Terraform
terragrunt apply --tf-path /usr/local/bin/tofu

terraform {
  # Module source
  source = "./modules/vpc"

  # Copy control
  include_in_copy = ["*.tf", "*.tfvars"]
  exclude_from_copy = ["test/**"]
  copy_terraform_lock_file = true
}

terraform {
  extra_arguments "custom_vars" {
    commands = ["plan", "apply"]

    # Additional arguments
    arguments = ["-var-file=custom.tfvars"]

    # Environment variables
    env_vars = {
      TF_VAR_foo = "bar"
    }

    # Variable files
    required_var_files = ["common.tfvars"]
    optional_var_files = ["optional.tfvars"]
  }
}

terraform {
  before_hook "before_init" {
    commands     = ["init"]
    execute      = ["echo", "Before init"]
    working_dir  = "."
    run_on_error = false
  }
}

terraform {
  after_hook "after_apply" {
    commands = ["apply"]
    execute  = ["echo", "After apply"]
  }
}

terraform {
  error_hook "on_error" {
    commands   = ["apply", "plan"]
    execute    = ["echo", "Error occurred"]
    on_errors  = [".*timeout.*"]
  }
}

# Validate before plan
before_hook "validate" {
  commands = ["plan"]
  execute  = ["terraform", "validate"]
}

# Notify after apply
after_hook "notify" {
  commands = ["apply"]
  execute  = ["slack-notify", "Applied changes"]
}

# Cleanup on error
error_hook "cleanup" {
  commands     = ["apply"]
  execute      = ["./cleanup.sh"]
  run_on_error = true
}

remote_state {
  backend = "s3"

  config = {
    bucket         = "my-terraform-state"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }

  generate = {
    path      = "backend.tf"
    if_exists = "overwrite"
  }
}

remote_state {
  backend = "s3"

  config = {
    # ... basic config ...

    # Skip specific configurations
    skip_bucket_versioning             = false
    skip_bucket_ssencryption           = false
    skip_bucket_root_access            = false
    skip_bucket_enforced_tls           = false
    skip_bucket_public_access_blocking = false
    disable_bucket_update              = false

    # Enable DynamoDB encryption
    enable_lock_table_ssencryption = true

    # Tags
    s3_bucket_tags      = { Team = "ops" }
    dynamodb_table_tags = { Team = "ops" }

    # Access logging
    accesslogging_bucket_name   = "my-logs"
    accesslogging_target_prefix = "tf-state/"

    # KMS encryption
    bucket_sse_algorithm  = "aws:kms"
    bucket_sse_kms_key_id = "alias/my-key"
  }
}

remote_state {
  backend = "s3"
  config  = { ... }

  # Disable init during plan/apply
  disable_init = false

  # Disable dependency optimization
  disable_dependency_optimization = false
}

include "root" {
  path = find_in_parent_folders()
}

include "root" {
  path = find_in_parent_folders()

  # Expose parent config to child
  expose = true

  # Merge strategy
  merge_strategy = "deep"  # shallow, deep, no_merge
}

include "root" {
  path   = find_in_parent_folders()
  expose = true
}

# Access parent locals
inputs = {
  region = include.root.locals.region
  tags   = include.root.locals.common_tags
}

include "root" {
  path   = find_in_parent_folders("root.hcl")
  expose = true
}

include "region" {
  path   = find_in_parent_folders("region.hcl")
  expose = true
}

inputs = merge(
  include.root.locals,
  include.region.locals,
)

dependency "vpc" {
  config_path = "../vpc"
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
}

dependency "vpc" {
  config_path = "../vpc"

  # Mock outputs for plan without deployment
  mock_outputs = {
    vpc_id     = "vpc-fake"
    subnet_ids = ["subnet-fake-1", "subnet-fake-2"]
  }

  # Allow mocks for these commands
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]

  # Merge strategy with state
  mock_outputs_merge_strategy_with_state = "shallow"
}

dependency "networking" {
  config_path = "../networking"

  # Skip fetching outputs (for non-output deps)
  skip_outputs = false

  mock_outputs = {
    vpc_id = "vpc-fake"
  }

  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

dependency "networking" {
  config_path = "../networking"
  mock_outputs = { vpc_id = "vpc-fake" }
  mock_outputs_allowed_terraform_commands = ["plan"]
}

dependency "security" {
  config_path = "../security"
  mock_outputs = { sg_id = "sg-fake" }
  mock_outputs_allowed_terraform_commands = ["plan"]
}

inputs = {
  vpc_id = dependency.networking.outputs.vpc_id
  sg_id  = dependency.security.outputs.sg_id
}

locals {
  environment = "prod"
  region      = "us-east-1"

  common_tags = {
    Environment = local.environment
    ManagedBy   = "Terragrunt"
  }
}

# Pass to Terraform as variables
inputs = {
  environment = local.environment
  region      = local.region
  tags        = local.common_tags
}

# Non-output dependencies
# (run before this module, but don't fetch outputs)
dependencies {
  paths = [
    "../networking",
    "../security"
  ]
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite"  # overwrite, overwrite_terragrunt, skip
  contents  = <<EOF
provider "aws" {
  region = "${local.region}"
}
EOF
}

engine {
  source  = "github.com/gruntwork-io/terragrunt-engine-opentofu"
  version = "v0.1.0"
  type    = "rpc"
}

feature {
  name    = "my_feature"
  default = true
}

# Exclude from run-all commands
exclude {
  actions = ["apply", "destroy"]
  if      = get_env("ENV") == "prod"
}

errors {
  retry_max_attempts       = 3
  retry_sleep_interval_sec = 5

  retryable_errors = [
    ".*timeout.*",
    ".*connection reset.*"
  ]
}

# Find parent terragrunt.hcl
find_in_parent_folders()

# Find specific file
find_in_parent_folders("root.hcl")

# Relative path to include
path_relative_to_include()

# Relative path from include
path_relative_from_include()

# Current directory
get_terragrunt_dir()

# Working directory for terraform
get_working_dir()

# Parent config directory
get_parent_terragrunt_dir()

# Original config directory
get_original_terragrunt_dir()

# Git repo root
get_repo_root()

# Path from repo root
get_path_from_repo_root()

# Relative path to repo root
get_path_to_repo_root()

locals {
  # Include parent config
  root_config = find_in_parent_folders()

  # Relative path for state key
  state_key = path_relative_to_include()

  # Repo-relative path
  module_path = get_path_from_repo_root()
}

# Get environment variable
get_env("VAR_NAME")

# With default value
get_env("VAR_NAME", "default")

# OS platform (linux, darwin, windows)
get_platform()

locals {
  environment = get_env("ENV", "dev")
  region      = get_env("AWS_REGION", "us-east-1")

  # Platform-specific config
  binary_path = get_platform() == "darwin" ? "/usr/local/bin" : "/usr/bin"
}

# AWS account ID
get_aws_account_id()

# AWS account alias
get_aws_account_alias()

# Caller identity ARN
get_aws_caller_identity_arn()

# Caller user ID
get_aws_caller_identity_user_id()

locals {
  account_id    = get_aws_account_id()
  account_alias = get_aws_account_alias()

  # Account-specific bucket name
  state_bucket = "terraform-state-${local.account_id}"
}

remote_state {
  backend = "s3"
  config = {
    bucket = "terraform-state-${get_aws_account_id()}"
    key    = "${path_relative_to_include()}/terraform.tfstate"
    region = "us-east-1"
  }
}

# Current command (plan, apply, etc)
get_terraform_command()

# Current command arguments
get_terraform_cli_args()

# Commands that need -var-file
get_terraform_commands_that_need_vars()

# Commands that need -input
get_terraform_commands_that_need_input()

# Commands that need -lock
get_terraform_commands_that_need_locking()

# Commands that need -parallelism
get_terraform_commands_that_need_parallelism()

# Default retryable error patterns
get_default_retryable_errors()

terraform {
  extra_arguments "vars" {
    commands = get_terraform_commands_that_need_vars()
    arguments = ["-var-file=common.tfvars"]
  }

  extra_arguments "parallelism" {
    commands = get_terraform_commands_that_need_parallelism()
    arguments = ["-parallelism=10"]
  }
}

# Parse terragrunt config
read_terragrunt_config("path/terragrunt.hcl")

# Read tfvars file
read_tfvars_file("vars.tfvars")

# Decrypt SOPS file
sops_decrypt_file("secrets.yaml")

# Mark file as read (for filtering)
mark_as_read("path/file")

locals {
  # Read hierarchical configs
  account_vars = read_terragrunt_config(
    find_in_parent_folders("account.hcl")
  )

  region_vars = read_terragrunt_config(
    find_in_parent_folders("region.hcl")
  )

  # Read secrets
  secrets = sops_decrypt_file("secrets.enc.yaml")

  # Merge configs
  account_id = local.account_vars.locals.account_id
  region     = local.region_vars.locals.region
}

# Execute command
run_cmd("echo", "hello")

# Multiple arguments
run_cmd("aws", "sts", "get-caller-identity")

# Quiet mode (suppress output)
run_cmd("--terragrunt-quiet", "aws", "sts", "get-caller-identity")

# Global cache (cache result)
run_cmd("--terragrunt-global-cache", "git", "rev-parse", "HEAD")

# No cache
run_cmd("--terragrunt-no-cache", "date")

locals {
  # Get git commit hash
  git_hash = run_cmd("--terragrunt-quiet", "git", "rev-parse", "HEAD")

  # Get AWS account ID dynamically
  account_id = run_cmd(
    "--terragrunt-quiet",
    "aws", "sts", "get-caller-identity",
    "--query", "Account",
    "--output", "text"
  )

  # Get current timestamp
  timestamp = run_cmd("--terragrunt-no-cache", "date", "+%Y%m%d%H%M%S")
}

⚠️ Warning: run_cmd executes during parsing, not during Terraform execution. Use sparingly as it can slow down parsing.

# Get --source flag value
get_terragrunt_source_cli_flag()

# Check version constraint
constraint_check("1.5.0", ">= 1.0")

locals {
  # Check if source override is set
  source_override = get_terragrunt_source_cli_flag()

  # Conditional logic based on version
  use_new_feature = constraint_check(
    get_env("TF_VERSION", "1.0.0"),
    ">= 1.5.0"
  )
}

.
├── terragrunt.hcl          # Root config
├── account.hcl             # Account-specific vars
├── region.hcl              # Region-specific vars
├── prod/
│   ├── us-east-1/
│   │   ├── vpc/
│   │   │   └── terragrunt.hcl
│   │   ├── eks/
│   │   │   └── terragrunt.hcl
│   │   └── rds/
│   │       └── terragrunt.hcl
└── dev/
    └── us-east-1/
        └── ...

locals {
  # Read hierarchical configs
  account_vars = read_terragrunt_config(
    find_in_parent_folders("account.hcl")
  )
  region_vars = read_terragrunt_config(
    find_in_parent_folders("region.hcl")
  )

  # Extract values
  account_id = local.account_vars.locals.account_id
  region     = local.region_vars.locals.region
}

# Configure remote state for all children
remote_state {
  backend = "s3"
  config = {
    bucket         = "terraform-state-${local.account_id}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = local.region
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# Pass common inputs to all children
inputs = merge(
  local.account_vars.locals,
  local.region_vars.locals,
)

locals {
  account_id   = "123456789012"
  account_name = "production"
}

locals {
  region = "us-east-1"
  azs    = ["us-east-1a", "us-east-1b", "us-east-1c"]
}

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git::git@github.com:org/modules.git//vpc?ref=v1.0.0"
}

inputs = {
  vpc_name = "main"
  cidr     = "10.0.0.0/16"

  # Inherits account_id, region, etc. from root
}

dependency "networking" {
  config_path = "../networking"
}

dependency "security" {
  config_path = "../security"
}

inputs = {
  vpc_id = dependency.networking.outputs.vpc_id
  sg_id  = dependency.security.outputs.sg_id
}

dependency "networking" {
  config_path = "../networking"

  # Mock for plan without dependencies deployed
  mock_outputs = {
    vpc_id     = "vpc-fake"
    subnet_ids = ["subnet-fake-1", "subnet-fake-2"]
  }

  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

dependency "security" {
  config_path = "../security"

  mock_outputs = {
    sg_id = "sg-fake"
  }

  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

inputs = {
  vpc_id     = dependency.networking.outputs.vpc_id
  subnet_ids = dependency.networking.outputs.subnet_ids
  sg_id      = dependency.security.outputs.sg_id
}

# Use dependencies block for non-output deps
dependencies {
  paths = ["../networking", "../security"]
}

# Or use skip_outputs
dependency "networking" {
  config_path  = "../networking"
  skip_outputs = true  # Don't fetch outputs
}

# Faster dependency resolution
terragrunt apply --dependency-fetch-output-from-state

# Assume role for single command
terragrunt apply \
  --iam-assume-role arn:aws:iam::123456789012:role/Admin

# With session name and duration
terragrunt apply \
  --iam-assume-role arn:aws:iam::123456789012:role/Admin \
  --iam-assume-role-session-name my-session \
  --iam-assume-role-duration 3600

locals {
  role_arn = "arn:aws:iam::123456789012:role/Admin"
}

terraform {
  extra_arguments "role" {
    commands = get_terraform_commands_that_need_vars()

    # Clear AWS_PROFILE
    env_vars = {
      AWS_PROFILE = ""
    }
  }

  before_hook "assume_role" {
    commands = ["init", "plan", "apply", "destroy"]
    execute  = [
      "aws", "sts", "assume-role",
      "--role-arn", local.role_arn
    ]
  }
}

locals {
  role_arn = "arn:aws:iam::123456789012:role/Admin"
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "${local.region}"

  assume_role {
    role_arn = "${local.role_arn}"
  }
}
EOF
}

errors {
  retry_max_attempts       = 3
  retry_sleep_interval_sec = 5

  retryable_errors = [
    "(?s).*timeout.*",
    "(?s).*connection reset.*",
  ]
}

errors {
  retry_max_attempts       = 5
  retry_sleep_interval_sec = 10

  retryable_errors = [
    # Throttling
    "(?s).*TooManyRequestsException.*",
    "(?s).*RequestLimitExceeded.*",
    "(?s).*Throttling.*",

    # Timeouts
    "(?s).*timeout.*",
    "(?s).*connection reset.*",
    "(?s).*EOF.*",

    # Transient errors
    "(?s).*InternalError.*",
    "(?s).*ServiceUnavailable.*",
  ]
}

Use get_default_retryable_errors() for standard patterns:

errors {
  retry_max_attempts       = 3
  retry_sleep_interval_sec = 5
  retryable_errors         = get_default_retryable_errors()
}

locals {
  region      = "us-east-1"
  environment = "prod"
  role_arn    = "arn:aws:iam::123456789012:role/Admin"
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "${local.region}"

  assume_role {
    role_arn = "${local.role_arn}"
  }

  default_tags {
    tags = {
      Environment = "${local.environment}"
      ManagedBy   = "Terragrunt"
    }
  }
}
EOF
}

generate "providers" {
  path      = "providers.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "${local.region}"
}

provider "aws" {
  alias  = "secondary"
  region = "us-west-2"
}

provider "kubernetes" {
  host = module.eks.cluster_endpoint
}
EOF
}

generate "versions" {
  path      = "versions.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}
EOF
}

Error: Cycle detected in dependencies

Solution: Use skip_outputs or dependencies block:

# Option 1: Skip outputs
dependency "networking" {
  config_path  = "../networking"
  skip_outputs = true
}

# Option 2: Use dependencies block
dependencies {
  paths = ["../networking"]
}

Error: Error acquiring the state lock

Solution:

# Check lock info
terragrunt state list

# Force unlock (use lock ID from error)
terragrunt force-unlock <lock-id>

Error: Module not found

Solution: Use absolute paths or git URLs with refs:

terraform {
  # Git with version tag
  source = "git::git@github.com:org/modules.git//vpc?ref=v1.0.0"

  # Local absolute path
  source = "/absolute/path/to/module"
}

Error: output "vpc_id" not found

Solution: Use mock_outputs:

dependency "vpc" {
  config_path = "../vpc"

  mock_outputs = {
    vpc_id = "vpc-fake"
  }

  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

Error: Failed to get existing workspaces

Solution: Bootstrap backend first:

terragrunt backend bootstrap

Error: AccessDenied

Solution: Assume correct IAM role:

terragrunt apply \
  --iam-assume-role arn:aws:iam::123456789012:role/Admin

.terragrunt-cache taking too much space.

Solution:

# Clean specific unit
rm -rf .terragrunt-cache

# Clean all (from root)
find . -type d -name ".terragrunt-cache" -exec rm -rf {} +

# Use custom location
terragrunt apply --download-dir /tmp/tg-cache

Error: No configuration files

Solution: Use --working-dir:

terragrunt apply --working-dir /path/to/module

Error: Module version constraint failed

Solution: Pin versions in source URL:

terraform {
  source = "git::git@github.com:org/modules.git//vpc?ref=v1.2.3"
}

Error: Too many concurrent operations

Solution: Limit parallelism:

terragrunt run --all apply --parallelism 5

.
├── terragrunt.hcl          # Root config
├── account.hcl             # Account vars
├── region.hcl              # Region vars
├── prod/
│   ├── us-east-1/
│   │   ├── vpc/
│   │   │   └── terragrunt.hcl
│   │   ├── eks/
│   │   │   └── terragrunt.hcl
│   │   └── rds/
│   │       └── terragrunt.hcl
└── dev/
    └── us-east-1/
        └── ...

• Use find_in_parent_folders() for root config
• Use locals {} for shared variables
• Use read_terragrunt_config() for hierarchical configs
• Use include {} for config inheritance
• Use generate {} for provider configs

• Enable versioning on S3 buckets
• Use encryption for state files
• Enable DynamoDB for state locking
• Use consistent key naming:

  key = "${path_relative_to_include()}/terraform.tfstate"
  

• Enable access logging:

  accesslogging_bucket_name = "my-logs"
  

• Use mock_outputs for faster planning
• Use skip_outputs = true to avoid circular deps
• Use dependencies {} for non-output dependencies
• Document dependency graph:

  terragrunt dag graph | dot -Tpng > graph.png
  

• Use before_hook for validations
• Use after_hook for notifications
• Use error_hook for cleanup
• Set run_on_error = true for critical hooks

• Use --parallelism for run-all commands
• Use --filter to target specific units
• Use --dependency-fetch-output-from-state
• Use provider cache for large stacks:

  terragrunt run --all init --provider-cache
  

• Use custom cache directory:

  --download-dir /tmp/tg-cache
  

• Never commit secrets to version control
• Use SOPS for encrypted secrets:

  sops_decrypt_file("secrets.enc.yaml")
  

• Use IAM roles, not access keys
• Enable encryption on state buckets
• Use KMS for state encryption:

  bucket_sse_algorithm  = "aws:kms"
  bucket_sse_kms_key_id = "alias/terraform"
  

• Pin module versions:

  source = "git::...?ref=v1.0.0"
  

• Pin provider versions:

  required_providers {
    aws = {
      version = "~> 5.0"
    }
  }
  

• Use semantic versioning
• Tag releases in git

• Use mock_outputs for unit testing
• Test with terragrunt plan first
• Use --filter to test specific units:

  terragrunt run --all plan --filter "path:prod/**"
  

• Validate before apply:

  terragrunt validate
  

locals {
  environment = get_env("ENV", "dev")

  # Use different branches per environment
  module_ref = local.environment == "prod" ? "v1.0.0" : "develop"
}

terraform {
  source = "git::git@github.com:org/modules.git//vpc?ref=${local.module_ref}"
}

locals {
  is_prod = get_env("ENV") == "prod"
}

# Skip apply in prod unless explicitly approved
exclude {
  actions = ["apply", "destroy"]
  if      = local.is_prod && get_env("APPROVED") != "true"
}

locals {
  environment = get_env("ENV", "dev")
}

terraform {
  # Only notify in production
  after_hook "notify_prod" {
    commands = ["apply"]
    execute  = local.environment == "prod" ? ["slack-notify"] : ["echo", "skipped"]
  }
}

remote_state {
  backend = "s3"

  config = {
    bucket = "terraform-state-${get_aws_account_id()}"
    key    = "${path_relative_to_include()}/terraform.tfstate"
    region = local.region

    # Custom tags for compliance
    s3_bucket_tags = {
      Team        = "ops"
      CostCenter  = "engineering"
      Compliance  = "required"
    }

    dynamodb_table_tags = {
      Team = "ops"
    }

    # Enable all security features
    skip_bucket_versioning             = false
    skip_bucket_ssencryption           = false
    skip_bucket_enforced_tls           = false
    skip_bucket_public_access_blocking = false
    enable_lock_table_ssencryption     = true

    # KMS encryption
    bucket_sse_algorithm  = "aws:kms"
    bucket_sse_kms_key_id = "alias/terraform"
  }
}

# Deploy to multiple regions
for region in us-east-1 us-west-2 eu-west-1; do
  TG_REGION=$region terragrunt run --all apply \
    --filter "path:**/${region}/**"
done

# Only apply changes affected by git diff
terragrunt run --all apply --filter-affected

# Trace-level logging
terragrunt plan --log-level trace

# JSON logging for parsing
terragrunt apply --log-format json --log-level debug

# Show final merged configuration
terragrunt render

# Show dependency graph
terragrunt dag graph

# Generate visual graph
terragrunt dag graph | dot -Tpng > graph.png

# Write inputs to debug.tfvars
terragrunt apply --inputs-debug
cat debug.tfvars

# Validate HCL syntax
terragrunt hcl validate

# Format HCL files
terragrunt hcl fmt

# Print debug info
terragrunt info print

# Override source for local testing
terragrunt plan --source ../local-modules/vpc

# Update cached modules
terragrunt init --source-update

# List resources in state
terragrunt state list

# Show specific resource
terragrunt state show aws_instance.example