--- name: tfappfix description: Terraform debugging for small teams. Diagnoses plan/apply failures, state issues, and Azure provider errors. Use when asked to "fix terraform", "debug infra", "why did apply fail", or "/tfappfix". --- # Terraform Debugging (/tfappfix) Pragmatic terraform debugging for a 2-person team. No enterprise overhead. ## Philosophy: What This Skill Is NOT **Skip these enterprise patterns - you are 2 people:** - Complex policy checks (Sentinel/OPA) - just review the plan - Multi-workspace orchestration - you have dev/prod, that is enough - Drift detection dashboards - just run `terraform plan` - Checkpoint files - terraform state IS the checkpoint - 4-agent planning - talk to each other instead **Terraform already provides:** - State management (do not reinvent it) - Change detection (`plan -detailed-exitcode`) - Locking (do not build another layer) - Dependency resolution **This skill focuses on:** - Diagnosing why plan/apply failed - Common Azure provider issues - Safe state manipulation when needed - Getting CI green again ## Triggers - `/tfappfix`, "fix terraform", "debug infra", "why did apply fail" - "plan is failing", "state is locked", "terraform error" ## The 80/20 of Terraform Debugging | Frequency | Problem Type | Solution | |-----------|--------------|----------| | 80% | Code/config error | Read error, fix code, push, CI applies | | 15% | State issues | Unlock, rm, import (with user confirmation) | | 5% | Azure API / provider | Wait, retry, or workaround | **Most terraform issues are solved by reading the error message carefully.** ## Workflow ``` Phase 0: CONTEXT - Identify the failing stack - Get the error (from user, CI logs, or local run) Phase 1: DIAGNOSE - Run fmt, validate, plan locally - Check state lock status if relevant - Check Azure resource status if apply failed Phase 2: FIX - Apply code changes - State ops require user confirmation Phase 3: VERIFY - Plan shows expected changes - Push to trigger CI ``` ### Phase 0: Get Context **Find out:** 1. Which stack? (Look for directories with `main.tf` or `*.tf` files) 2. What is the error? (CI log, local error, or symptom) 3. Plan or apply failure? **If user provides a GitHub Actions run URL:** ```bash gh run view --log-failed ``` ### Phase 1: Diagnose **Always start here - run the basics:** ```bash cd # directory containing main.tf # 1. Format check terraform fmt -check -recursive # 2. Validate (fast, no backend) terraform init -backend=false terraform validate # 3. Full plan (if validate passes) terraform init terraform plan -out=debug.tfplan ``` **Check state lock (if plan hangs):** For Azure Blob backend, check lease status with `az storage blob show`. **Check Azure resource status (if apply failed mid-way):** ```bash az resource list -g --query "[].{name:name, state:properties.provisioningState}" -o table ``` ### Phase 2: Fix #### Error: State Lock For Azure Blob backend: ```bash # Check lease status az storage blob show --container-name --name --account-name --query "properties.lease" # Break lease (ASK USER FIRST) az storage blob lease break --container-name --name --account-name ``` **Safety gate:** Always ask user before breaking a lock. #### Error: Resource Already Exists Resource exists in Azure but not in state. **⚠️ CRITICAL: 99% of cases should DELETE, not import.** **DEFAULT ACTION (do not ask, just do this):** 1. Ask user to DELETE the resource in Azure Portal or CLI 2. Re-run terraform to create it fresh under Terraform management ```bash # Example: delete a role assignment az role assignment delete --ids "" # Example: delete a generic resource az resource delete --ids "" ``` **IMPORT IS ALMOST NEVER CORRECT.** Only consider import when ALL of these are true: 1. The resource has existed for a **long time** (months/years, not hours/days) 2. The resource contains **irreplaceable data** or **configuration that cannot be recreated** 3. The resource is managed in a **different terraform repo** OR was created manually before IaC **If you believe import is appropriate, you MUST:** 1. Stop and ask the user with ALL of these details: - Why you believe this qualifies as a rare import case - What the resource is and how long it has existed - The exact import command you would run - The risk: import can cause state corruption if the resource config doesn't match 2. Wait for explicit "yes, import it" confirmation 3. Note: `terraform import` is BLOCKED by the command guard - user must run manually **DO NOT ask about import** for resources created in the last few days. Just delete and recreate. #### Error: Resource Not Found (Drift) Resource in state but deleted from Azure: ```bash # Remove from state - ASK USER FIRST terraform state rm ``` #### Error: Provider / API Error | Error | Cause | Fix | |-------|-------|-----| | `StatusCode=409` | Resource busy | Wait 5 min, retry | | `StatusCode=429` | Rate limited | Retry with `-parallelism=1` | | `StatusCode=404` on apply | Eventual consistency | Wait 2 min, retry | | `OperationNotAllowed` | Resource in transitional state | Wait and retry | #### Error: Module/Provider Version ```bash terraform providers terraform init -upgrade ``` ### Phase 3: Verify ```bash # Local plan should show expected changes terraform plan # Push to trigger CI git add git commit -m "fix(terraform): " git push # Monitor CI gh run watch ``` ## Finding Stacks **Discover terraform stacks in your repo:** ```bash # Find all directories with terraform files find . -name "*.tf" -type f | xargs dirname | sort -u # Or look for backend configurations grep -r "backend" --include="*.tf" -l ``` **Understand dependencies:** - Check `terraform_remote_state` data sources for cross-stack references - Check module sources for shared modules - Apply order: shared/platform stacks first, then application stacks ## Safety Rules **BLOCKED (cannot run via Claude - user must run manually):** - `terraform import` — blocked by command guard - `terraform state rm` — blocked by command guard - `terraform apply` — blocked by command guard - `terraform destroy` — blocked by command guard **Ask user before:** - Breaking state locks - Suggesting user run `terraform import` (see "Resource Already Exists" - 99% should DELETE instead) - Operations on production stacks - Any `-force` flags **Proceed without asking:** - `terraform fmt` - `terraform validate` - `terraform plan` - `terraform init` - Code changes to .tf files - Committing and pushing ## Azure Authentication ```bash # Check auth az account show # Login if needed az login # Set subscription az account set -s ``` For terraform: ```bash export ARM_SUBSCRIPTION_ID=$(az account show --query id -o tsv) export ARM_TENANT_ID=$(az account show --query tenantId -o tsv) ``` ## Error Message Decoder | Error Message | Meaning | Fix | |---------------|---------|-----| | "Error acquiring the state lock" | CI crashed or local tf running | Break lease if stale | | "Resource already exists" | Exists in Azure, not in state | DELETE resource, recreate (import is rare) | | "Unsupported attribute" | Module output changed | `terraform init -upgrade` | | "dial tcp: lookup ... no such host" | DNS/network issue | Retry | | "AuthorizationFailed" | Missing RBAC | Check permissions | | "QuotaExceeded" | Azure limits | Request increase or change region | ## When to Escalate **Talk to your teammate (not Claude):** - Production outage - Security-related changes - Billing/cost decisions - Architectural changes - Anything you are not sure about **This skill is for:** - Getting a failing plan/apply to pass - Understanding error messages - Safe state manipulation with confirmation - Quick fixes, not redesigns

forge

Scan your own AI components