Performance Optimization

# Default parallelism — 10 concurrent operations
terraform plan

# Increase parallelism for configurations with many independent resources
terraform plan  -parallelism=20
terraform apply -parallelism=20

# Reduce parallelism to avoid AWS rate limiting (ThrottlingException)
# Some AWS services have aggressive rate limits — IAM, Route53, CloudFront
terraform apply -parallelism=5

# Set parallelism via environment variable for consistency
export TF_CLI_ARGS_plan="-parallelism=20"
export TF_CLI_ARGS_apply="-parallelism=20"

# Finding the right parallelism value:
# Start at 20 — if you see ThrottlingException errors in TF_LOG=DEBUG, reduce to 10
# If the plan is clean and fast at 20, try 30
# There is no universal right answer — it depends on your AWS account limits

# Inspect the dependency graph — visualise what can run in parallel
terraform graph | dot -Tsvg > graph.svg  # Requires graphviz
# Resources at the same depth in the graph run concurrently
# Long chains of dependencies limit parallelism regardless of the -parallelism flag

# Method 1: TF_PLUGIN_CACHE_DIR — reuse downloaded providers across runs
export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
mkdir -p "$HOME/.terraform.d/plugin-cache"
terraform init  # Downloads provider and caches it in TF_PLUGIN_CACHE_DIR

# On subsequent init runs with the same provider version:
# Terraform finds the cached binary and creates a symlink instead of downloading
# AWS provider (400MB+) goes from 30-60 seconds to under 1 second

# ~/.terraformrc — set cache globally for all Terraform runs on this machine
cat ~/.terraformrc
# plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

# Method 2: Pre-bake providers into a Docker image
# Build a custom Docker image with providers pre-installed
# No download needed during CI/CD runs at all

# Dockerfile for a Terraform CI image
# FROM hashicorp/terraform:1.6.3
# RUN mkdir -p /root/.terraform.d/plugin-cache
# ENV TF_PLUGIN_CACHE_DIR="/root/.terraform.d/plugin-cache"
# COPY providers.tf /tmp/providers/
# WORKDIR /tmp/providers
# RUN terraform init -backend=false  # Downloads providers into the image layer
# WORKDIR /
# Provider binaries are now in the image — zero download time in CI

# Method 3: GitHub Actions cache
# Cache the .terraform directory across workflow runs

- name: Cache Terraform providers
  uses: actions/cache@v4
  with:
    path: ~/.terraform.d/plugin-cache
    key: ${{ runner.os }}-terraform-${{ hashFiles('**/.terraform.lock.hcl') }}
    restore-keys: |
      ${{ runner.os }}-terraform-
# When the lock file changes (provider upgrade), cache is invalidated and rebuilt
# When unchanged, providers load from cache — typically 60 seconds saved per run

# Measure your current plan time — establish a baseline
time terraform plan 2>&1 | tail -5
# real    4m12.345s  ← too slow if this is a frequent operation

# Profile which resources take longest — use TF_LOG to see timestamps
TF_LOG=DEBUG terraform plan 2>&1 | grep -E "^[0-9]{4}|Reading|Refreshing" \
  | awk '{print $1, $0}' | sort | head -30

# Count resources in the current state
terraform state list | wc -l
# If > 100, the configuration is a strong candidate for splitting

# Before splitting (monolith — one state file):
# networking.tf, databases.tf, compute.tf, iam.tf — all in one directory
# Plan: 8 minutes (500 resources × ~1 second each / 10 parallelism)

# After splitting (3 separate root modules):
# foundation/networking/  — 80 resources  → Plan: 45 seconds
# platform/databases/     — 60 resources  → Plan: 35 seconds
# services/compute/       — 360 resources → Plan: 4 minutes (still candidate for further split)

# The key insight:
# Engineers working on a feature branch only need to plan the services layer
# They never wait for the networking or databases plan
# Total plan time experienced: 4 minutes down from 8 minutes
# And the networking/database plans run much faster when they do change

# Splitting also improves the refresh phase:
# Fewer resources → fewer API calls per plan → faster refresh
# Independent state files → parallel plans across teams → no lock contention

# Anti-pattern: data source inside for_each — N data source reads for N resources
# This calls the AMI API once per EC2 instance — even if all instances use the same AMI

# BAD — one API call per resource
resource "aws_instance" "workers" {
  for_each = var.worker_configs  # 20 workers = 20 AMI API calls

  ami = data.aws_ami.latest[each.key].id  # Data source inside for_each = slow
}

data "aws_ami" "latest" {
  for_each    = var.worker_configs  # Creates 20 data source reads
  most_recent = true
  owners      = ["amazon"]
  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

# GOOD — one data source read, referenced by all resources
data "aws_ami" "latest" {
  most_recent = true  # One API call total, regardless of how many instances
  owners      = ["amazon"]
  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

resource "aws_instance" "workers" {
  for_each = var.worker_configs
  ami      = data.aws_ami.latest.id  # All workers share the same data source read
}

# Anti-pattern: data source on every plan for rarely-changing data
# If the VPC ID never changes, don't fetch it on every plan
# BAD:
data "aws_vpc" "main" {
  filter {
    name   = "tag:Name"
    values = ["prod-vpc"]
  }
}
# GOOD for stable cross-module data — use terraform_remote_state or variables instead
variable "vpc_id" {
  description = "VPC ID — pass from the networking module output"
  type        = string
  # No API call needed — value passed at apply time
}

# Legitimate uses of -refresh=false

# Use case 1: Testing a configuration change when you KNOW no external drift exists
# You just applied 5 minutes ago. Nothing has changed externally.
# You want to quickly preview a configuration edit.
terraform plan -refresh=false
# The plan skips all API calls — result in under 1 second for most configs
# Appropriate only when you are confident state is accurate

# Use case 2: Applying a saved plan file
# When you already ran terraform plan (which refreshed state) and saved the plan:
terraform plan -out=tfplan              # Refreshes, generates plan, saves file
# ... time passes, reviewer approves ...
terraform apply -refresh=false tfplan  # Apply the saved plan — no re-refresh needed
# The apply of a saved plan file always uses the state captured at plan time
# -refresh=false is implicit when applying a saved plan file anyway

# Use case 3: Debugging configuration logic, not infrastructure state
# You want to check how a local/variable expression evaluates without any API calls
terraform plan -refresh=false -target=local.computed_value

# Use case 4: Speeding up the apply of well-understood changes in CI/CD
# The plan already ran (with refresh) in the plan stage of the pipeline
# The apply stage can safely use -refresh=false if applying a saved plan file
# (The plan artifact already captured the refreshed state)

# NEVER use -refresh=false as a routine way to speed up plans
# The API calls in the refresh phase ARE the drift detection
# Skipping them makes every plan a diff against potentially stale state

# Save plan output for analysis
terraform plan -no-color 2>&1 | tee plan-output.txt

# Quick summary — just the final count line
grep "^Plan:" plan-output.txt
# Plan: 12 to add, 3 to change, 1 to destroy.

# Find all resources being destroyed — the dangerous ones
grep "^  # .* will be destroyed" plan-output.txt
grep "^  -" plan-output.txt | head -20

# Find all resources being replaced (destroy + create)
grep "# .* must be replaced" plan-output.txt
grep -A2 "must be replaced" plan-output.txt

# Find all in-place modifications
grep "# .* will be updated in-place" plan-output.txt

# Show only the lines with the change symbols
grep "^  [+~\-]" plan-output.txt | head -40

# JSON output — machine-readable for CI/CD tooling
terraform show -json tfplan > plan.json

# Extract just the resource changes from JSON
cat plan.json | jq '.resource_changes[] | {address, change: .change.actions}'

# Extract destroys from JSON
cat plan.json | jq '.resource_changes[] | select(.change.actions[] == "delete") | .address'

# Count changes by action type
cat plan.json | jq '.resource_changes[].change.actions[]' | sort | uniq -c