Terraform

terraform plan -out=tfplan
terraform show tfplan                   # human-readable review of the saved plan
terraform apply tfplan                  # applies exactly what was reviewed, or fails if state moved on

terraform {
  required_version = ">= 1.11"
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 6.0" }
  }
  backend "s3" {
    bucket       = "example-tfstate"
    key          = "prod/network/terraform.tfstate"
    region       = "ap-southeast-2"
    use_lockfile = true      # S3-native locking; DynamoDB locking is deprecated
    encrypt      = true
  }
}

provider "aws" {
  region = "ap-southeast-2"
}

provider "aws" {
  alias  = "us_east_1"        # for resources that must live in us-east-1, such as CloudFront certificates
  region = "us-east-1"
}

resource "aws_instance" "web" {
  for_each               = var.web_nodes          # map of name => { subnet_id = ... }
  ami                    = data.aws_ami.al2023.id
  instance_type          = var.instance_type
  subnet_id              = each.value.subnet_id
  vpc_security_group_ids = [aws_security_group.web.id]

  tags = merge(var.tags, { Name = "${var.name}-${each.key}" })

  lifecycle {
    create_before_destroy = true
    ignore_changes        = [ami]          # an image pipeline owns this attribute
    precondition {
      condition     = var.instance_type != "t2.micro"
      error_message = "t2.micro is not permitted in production."
    }
  }
}

variable "instance_type" {
  type        = string
  default     = "t3.small"
  description = "EC2 instance size for the web tier"
  validation {
    condition     = can(regex("^t3\\.", var.instance_type))
    error_message = "Only t3 sizes are approved here."
  }
}

output "url" {
  value       = "https://${aws_lb.this.dns_name}"
  description = "Public endpoint"
}

ephemeral "random_password" "db" {
  length = 32
}

resource "aws_db_instance" "main" {
  # ...
  password_wo         = ephemeral.random_password.db.result
  password_wo_version = 1          # bump to push a new password
}

module "network" {
  source = "git::https://github.com/example/tf-modules.git//network?ref=v1.4.0"

  name     = "prod"
  cidr     = "10.20.0.0/16"
  az_count = 3
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"     # registry module
  version = "~> 6.0"
  # ...
}

moved {
  from = aws_instance.web
  to   = module.compute.aws_instance.web
}

removed {
  from = aws_instance.legacy
  lifecycle {
    destroy = false
  }
}

import {
  to = aws_s3_bucket.logs
  id = "example-logs-bucket"
}

terraform plan -generate-config-out=generated.tf   # writes resource blocks for import targets that lack one

terraform state list
terraform state show 'aws_instance.web["a"]'
terraform state mv 'aws_instance.web' 'aws_instance.api'
terraform state rm 'aws_instance.legacy'            # forget it; the object keeps running
terraform import 'aws_instance.web["a"]' i-0abc123

moved {                                   # whole module rename; every resource inside moves with it
  from = module.net
  to   = module.network
}

moved {                                   # count to for_each: one block per index
  from = aws_subnet.private[0]
  to   = aws_subnet.private["a"]
}
moved {
  from = aws_subnet.private[1]
  to   = aws_subnet.private["b"]
}

import {                                  # bulk import driven by a map (1.7+)
  for_each = var.existing_buckets          # { logs = "example-logs", assets = "example-assets" }
  to       = aws_s3_bucket.managed[each.key]
  id       = each.value
}

import {
  to       = aws_route53_record.www
  id       = "Z0123456789ABC_www.example.com_A"     # ID formats are provider-specific; check the resource docs "Import" section
}                                                   # 1.12+: providers may accept an identity {...} object instead of an id string

removed {
  from = module.legacy                    # also works for whole modules
  lifecycle { destroy = false }
}

terraform state pull > state.json                          # always first; keep this copy until the next successful plan
terraform state list -id i-0abc123                         # which address holds an object with that ID
terraform state show -no-color 'module.db.aws_db_instance.main' | grep -E '^\s+(arn|id) '
terraform state mv 'module.old.aws_instance.web' 'module.new.aws_instance.web'
terraform state rm 'module.legacy'                         # forgets every resource under the module
terraform state replace-provider registry.terraform.io/-/aws registry.terraform.io/hashicorp/aws   # after the 0.13 provider namespace change or a fork
terraform apply -replace='aws_instance.web["a"]'           # supersedes terraform taint
terraform untaint 'aws_instance.web["a"]'                  # clear a taint left by a failed create
terraform apply -refresh-only                              # accept reality into state without touching configuration
terraform state push state.json                            # upload an edited copy; refuses older serial or different lineage
terraform state push -force state.json                     # overrides both checks; last resort

cd ../network && terraform state pull > /tmp/net.json && cd ../compute && terraform state pull > /tmp/comp.json
terraform state mv -state=/tmp/net.json -state-out=/tmp/comp.json 'aws_security_group.web' 'aws_security_group.web'
cd ../network && terraform state push /tmp/net.json && cd ../compute && terraform state push /tmp/comp.json
# then add the resource block to compute, delete it from network, and plan both: each should show no changes

envs/
  prod/    main.tf  backend.tf  prod.tfvars      # root module: a handful of module calls and provider config
  staging/ main.tf  backend.tf  staging.tfvars
modules/
  network/ compute/ database/                     # all environment differences arrive through variables

terraform -chdir=envs/prod init -backend-config=prod.s3.tfbackend   # partial backend config kept out of source when it holds account-specific values
terraform -chdir=envs/prod plan -var-file=prod.tfvars -out=tfplan
terraform workspace new pr-1234 && terraform apply -var-file=review.tfvars -auto-approve   # ephemeral copy
terraform workspace select default && terraform workspace delete pr-1234                  # refuses while its state is non-empty; destroy first

# tests/network.tftest.hcl
variables {
  name = "test"
  cidr = "10.99.0.0/16"
}

mock_provider "aws" {}                     # every resource and data source returns generated values

run "creates_one_subnet_per_az" {
  command = plan
  variables { az_count = 3 }
  assert {
    condition     = length(aws_subnet.private) == 3
    error_message = "expected 3 private subnets, got ${length(aws_subnet.private)}"
  }
}

run "rejects_small_cidr" {
  command = plan
  variables { cidr = "10.99.0.0/28" }
  expect_failures = [var.cidr]             # the variable's validation block must reject it
}

run "outputs_match" {
  command = plan
  assert {
    condition     = output.vpc_cidr == var.cidr
    error_message = "output must echo the input CIDR"
  }
}

terraform test                                   # every test file
terraform test -filter=tests/network.tftest.hcl  # one file
terraform test -verbose                          # print the plan or state for each run
terraform test -junit-xml=report.xml             # JUnit report for CI

terraform providers                                                # required providers and which module requires them
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 -platform=linux_arm64   # record hashes for every platform CI and laptops use
terraform init -upgrade                                            # newest versions within constraints; rewrites the lock file
terraform providers mirror ./mirror                                # download providers for an air-gapped or rate-limited environment
terraform providers schema -json | jq '.provider_schemas | keys'   # inspect installed provider schemas

# ~/.terraformrc: reuse downloaded providers across working directories and prefer a local mirror
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
provider_installation {
  filesystem_mirror { path = "/opt/terraform/mirror", include = ["registry.terraform.io/hashicorp/*"] }
  direct { exclude = ["registry.terraform.io/hashicorp/*"] }
}

locals {
  env_tags = merge(var.tags, { Environment = var.env, ManagedBy = "terraform" })
  subnets  = { for az in var.azs : az => cidrsubnet(var.cidr, 8, index(var.azs, az)) }   # for expression over a list into a map
  public   = [for s in aws_subnet.all : s.id if s.tags["tier"] == "public"]             # filter
  cfg      = yamldecode(file("${path.module}/config.yaml"))
  name     = coalesce(var.name_override, "${var.project}-${var.env}")
}

dynamic "ingress" {                       # repeat a nested block per element
  for_each = var.ingress_rules
  content {
    from_port   = ingress.value.port
    to_port     = ingress.value.port
    protocol    = "tcp"
    cidr_blocks = ingress.value.cidrs
  }
}

check "endpoint_answers" {                # post-apply assertion that does not block the apply (1.5+)
  data "http" "health" { url = "https://${aws_lb.this.dns_name}/health" }
  assert {
    condition     = data.http.health.status_code == 200
    error_message = "health endpoint returned ${data.http.health.status_code}"
  }
}

terraform console <<< 'cidrsubnet("10.0.0.0/16", 8, 3)'   # evaluate expressions against the current state
terraform console <<< 'keys(module.network.subnet_ids)'

terraform workspace list
terraform workspace new feature-x
terraform workspace select default

TF_LOG=DEBUG terraform plan 2>debug.log      # core and provider logs; may contain secrets
TF_LOG_PROVIDER=TRACE terraform apply        # provider API calls only
terraform providers                          # provider requirements per module
terraform graph | dot -Tsvg > graph.svg      # needs graphviz

# Every change in a saved plan, one line each
terraform show -json tfplan | jq -r '.resource_changes[] | select(.change.actions != ["no-op"]) | "\(.change.actions|join(","))\t\(.address)"'

# Only the deletes and replacements: the review that matters
terraform show -json tfplan | jq -r '.resource_changes[] | select(.change.actions | index("delete")) | .address'

# Resource counts by type
terraform state list | sed 's/\[.*//' | awk -F. '{print $(NF-1)}' | sort | uniq -c | sort -rn

# Outputs into environment variables
eval "$(terraform output -json | jq -r 'to_entries[] | "export TF_\(.key|ascii_upcase)=\(.value.value|@sh)"')"

# Format check in CI
terraform fmt -check -recursive -diff

# Locked provider versions
grep -A1 '^provider ' .terraform.lock.hcl

# Exit code 2 means changes are pending, 0 means none, 1 means error
terraform plan -detailed-exitcode -out=tfplan

# Plan summary counts: add, change, destroy
terraform show -json tfplan | jq '[.resource_changes[].change.actions] | flatten | group_by(.) | map({(.[0]): length}) | add'

# Attributes that force replacement, per resource
terraform show -json tfplan | jq -r '.resource_changes[] | select(.change.actions == ["delete","create"] or .change.actions == ["create","delete"]) | "\(.address): \(.change.replace_paths | map(join(".")) | join(", "))"'

# Fail CI if the plan destroys anything
terraform show -json tfplan | jq -e '[.resource_changes[] | select(.change.actions | index("delete"))] | length == 0' >/dev/null

# Drift only: which resources changed outside Terraform
terraform plan -refresh-only -detailed-exitcode -no-color | grep -E '^\s+# .* (has changed|has been deleted)'

# Every resource ID in state, with address
terraform show -json | jq -r '.values.root_module | .. | .resources? // empty | .[] | "\(.address)\t\(.values.id // "-")"'

# Providers and versions actually selected
terraform version -json | jq -r '.provider_selections | to_entries[] | "\(.key) \(.value)"'

# Modules and their sources, from the module manifest
jq -r '.Modules[] | select(.Key != "") | "\(.Key)\t\(.Source)\t\(.Version // "-")"' .terraform/modules/modules.json

# Variables without a description (awk keeps the block between variable and the closing brace)
awk '/^variable "/ {v = $2; d = 0} /^\s*description/ {d = 1} /^}/ && v != "" {if (!d) print FILENAME, v; v = ""}' *.tf

# Which state a resource with a known cloud ID lives in, across several roots
for d in envs/*; do (cd "$d" && terraform state list -id "$ID" 2>/dev/null | sed "s|^|$d: |"); done

# Move a resource into a module and verify the plan is empty
terraform state mv 'aws_instance.web' 'module.compute.aws_instance.web' && terraform plan -detailed-exitcode; echo "rc=$?"

# Untaint everything that a failed apply tainted
terraform state list | while read -r r; do terraform state show "$r" 2>/dev/null | grep -q '(tainted)' && terraform untaint "$r"; done

# Import many objects from a CSV of address,id (imperative alternative to import blocks)
while IFS=, read -r addr id; do terraform import "$addr" "$id"; done < imports.csv

# Outputs of another root as JSON, for wiring roots together in a script
terraform -chdir=envs/network output -json | jq -r '.vpc_id.value'

# Evaluate a function against the current state without a plan
terraform console <<< 'cidrsubnets("10.0.0.0/16", 4, 4, 8)'

# Validate every root module in the repository
for d in $(find . -name backend.tf -not -path '*/.terraform/*' -exec dirname {} \;); do (cd "$d" && terraform init -backend=false -input=false >/dev/null && terraform validate) || echo "FAIL $d"; done

# Run tests with a JUnit report and show only failures
terraform test -junit-xml=report.xml -json | jq -r 'select(.type == "test_run" and .test_run.status == "fail") | "\(.test_file) \(.test_run.run)"'

# Who holds the state lock (S3 lockfile backend)
aws s3 cp "s3://example-tfstate/prod/network/terraform.tfstate.tflock" - 2>/dev/null | jq .

# Age of the state snapshot and its serial
terraform state pull | jq '{serial, terraform_version, resources: (.resources | length)}'

# Sensitive outputs in plain text (prints secrets; for debugging only)
terraform output -json | jq -r 'to_entries[] | select(.value.sensitive) | .key'

# Diff two saved plans (for example before and after a provider upgrade)
diff <(terraform show -no-color before.tfplan) <(terraform show -no-color after.tfplan)

# Rebuild the lock file from scratch for all platforms
rm .terraform.lock.hcl && terraform providers lock -platform=linux_amd64 -platform=darwin_arm64

#!/usr/bin/env bash
# usage: plan-gate.sh [allowed-destroys.txt]   run in the root module directory with credentials in the environment
set -euo pipefail

allow=${1:-/dev/null}
export TF_IN_AUTOMATION=1
terraform init -input=false >/dev/null
terraform plan -input=false -lock-timeout=5m -detailed-exitcode -out=tfplan; rc=$?
(( rc == 1 )) && { echo 'plan failed' >&2; exit 1; }
(( rc == 0 )) && { echo 'no changes'; exit 0; }

json=$(terraform show -json tfplan)
jq -r '.resource_changes[] | select(.change.actions != ["no-op"]) | "\(.change.actions | join("+"))\t\(.address)"' <<< "$json" | column -t -s $'\t'

mapfile -t destroys < <(jq -r '.resource_changes[] | select(.change.actions | index("delete")) | .address' <<< "$json")
blocked=()
for a in "${destroys[@]}"; do grep -qxF -- "$a" "$allow" || blocked+=("$a"); done
if (( ${#blocked[@]} )); then
  printf 'BLOCKED: plan destroys or replaces resources not in %s:\n' "$allow" >&2
  printf '  %s\n' "${blocked[@]}" >&2
  exit 2
fi
printf '%d changes, %d destroys (all allowed)\n' "$(jq '[.resource_changes[] | select(.change.actions != ["no-op"])] | length' <<< "$json")" "${#destroys[@]}"

#!/usr/bin/env bash
# usage: drift-report.sh envs/   (each subdirectory with a backend.tf is a root module)
set -euo pipefail

base=${1:?directory of root modules}
tmp=$(mktemp -d); trap 'rm -rf -- "$tmp"' EXIT
rc=0
printf '%-20s %-8s %s\n' ROOT STATUS RESOURCES
for d in "$base"/*/; do
  [[ -f $d/backend.tf ]] || continue
  name=$(basename "$d")
  if ! terraform -chdir="$d" init -input=false >"$tmp/$name.init" 2>&1; then printf '%-20s %-8s init failed\n' "$name" ERROR; rc=1; continue; fi
  terraform -chdir="$d" plan -refresh-only -input=false -lock=false -detailed-exitcode -out="$tmp/$name.plan" >"$tmp/$name.log" 2>&1; prc=$?
  case $prc in
    0) printf '%-20s %-8s -\n' "$name" clean ;;
    2) changed=$(terraform -chdir="$d" show -json "$tmp/$name.plan" | jq -r '[.resource_drift[]? | .address] | join(", ")')
       printf '%-20s %-8s %s\n' "$name" DRIFT "$changed"; rc=1 ;;
    *) printf '%-20s %-8s see %s\n' "$name" ERROR "$tmp/$name.log"; rc=1 ;;
  esac
done
exit "$rc"

#!/usr/bin/env bash
# usage: state-backup.sh [backup-dir]
set -euo pipefail

dir=${1:-${TF_STATE_BACKUPS:-$HOME/.terraform-state-backups}}
mkdir -p "$dir"
root=$(basename "$PWD")
ws=$(terraform workspace show)
state=$(terraform state pull)
serial=$(jq -r '.serial' <<< "$state")
lineage=$(jq -r '.lineage' <<< "$state")
[[ $serial =~ ^[0-9]+$ ]] || { echo 'state pull did not return a state file' >&2; exit 1; }
out="$dir/$root-$ws-serial$serial-$(date +%Y%m%dT%H%M%S).tfstate"
printf '%s' "$state" > "$out"
jq -e '.resources | length' "$out" >/dev/null
chmod 600 "$out"
printf 'saved %s (lineage %s, %s resources)\n' "$out" "$lineage" "$(jq '.resources | length' "$out")"
printf 'restore with: terraform state push %q\n' "$out"