Initial commit

skills/terraform/references/state-management.md

@@ -0,0 +1,112 @@
+# State Management
+
+## Remote Backend (Recommended)
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket         = "terraform-state"
+    key            = "project/terraform.tfstate"
+    region         = "us-east-1"
+    encrypt        = true
+    dynamodb_table = "terraform-locks"  # State locking
+  }
+}
+```
+
+### S3-Compatible (MinIO, Ceph)
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket = "terraform-state"
+    key    = "project/terraform.tfstate"
+    region = "us-east-1"  # Required but ignored
+
+    endpoint                    = "https://minio.example.com"
+    skip_credentials_validation = true
+    skip_metadata_api_check     = true
+    skip_region_validation      = true
+    force_path_style            = true
+  }
+}
+```
+
+## State Operations
+
+```bash
+# List resources
+terraform state list
+terraform state list proxmox_vm_qemu.*
+
+# Show resource details
+terraform state show proxmox_vm_qemu.web
+
+# Rename resource
+terraform state mv proxmox_vm_qemu.old proxmox_vm_qemu.new
+
+# Move to module
+terraform state mv proxmox_vm_qemu.web modules.web.proxmox_vm_qemu.main
+
+# Remove from state (doesn't destroy)
+terraform state rm proxmox_vm_qemu.orphaned
+
+# Import existing resource
+terraform import proxmox_vm_qemu.web pve1/qemu/100
+
+# Update state from infrastructure
+terraform refresh
+```
+
+## State Migration
+
+```bash
+# Change backend - updates terraform block, then:
+terraform init -migrate-state
+
+# Reinitialize without migration
+terraform init -reconfigure
+```
+
+## State Locking
+
+Prevents concurrent modifications. Enable via backend config:
+- S3: `dynamodb_table`
+- Consul: Built-in
+- HTTP: `lock_address`
+
+### Force Unlock (Emergency)
+
+```bash
+# Only when certain no operation running
+terraform force-unlock LOCK_ID
+```
+
+## Troubleshooting
+
+### State Lock Timeout
+
+```
+Error: Error acquiring state lock
+```
+
+1. Wait for other operation
+2. Verify no process running
+3. `terraform force-unlock LOCK_ID` if safe
+
+### State Drift
+
+```
+Plan shows unexpected changes
+```
+
+```bash
+terraform refresh  # Update state from real infra
+terraform plan     # Review changes
+```
+
+### Corrupted State
+
+1. Restore from backup
+2. `terraform state pull > backup.tfstate`
+3. Last resort: `terraform state rm` and re-import