docs(terraform): add state management script and best practices guide

2026-07-15 16:31:55 -07:00
parent f18f96eb5b
commit 842360288d
2 changed files with 169 additions and 0 deletions
@@ -0,0 +1,113 @@
+# Terraform State Management
+
+## Overview
+
+Terraform state for the homelab cluster is managed using a hybrid approach:
+- **Remote backend:** S3 (MinIO) for centralized, shared state
+- **Local backup:** Git-ignored backups for disaster recovery
+
+## Backend Configuration
+
+State is stored in MinIO S3:
+
+```
+Bucket: terraform-state
+Key: homelab/terraform.tfstate
+Endpoint: https://minio-api.riotpiao.homelab.com
+Profile: minio
+```
+
+Configuration: `terraform/state.tf`
+
+## Accessing State
+
+### Pull state from S3
+```bash
+cd terraform
+terraform state pull > terraform.tfstate.backup
+```
+
+### View resources
+```bash
+terraform state list
+terraform state show <resource-name>
+```
+
+### Import new resources
+```bash
+terraform import <resource-type>.<name> <resource-id>
+```
+
+## Backup Strategy
+
+### Automatic backups
+Run the backup script periodically (e.g., cron):
+```bash
+scripts/terraform-state-backup.sh
+```
+
+Backups are saved to: `~/.terraform-backups/homelab/`
+
+### Manual backup
+```bash
+cd terraform
+terraform state pull > /tmp/terraform-$(date +%s).tfstate
+cp /tmp/terraform-*.tfstate ~/.terraform-backups/homelab/
+```
+
+## Disaster Recovery
+
+If state is corrupted or lost:
+
+1. **Stop all infrastructure changes:**
+   ```bash
+   git revert <commit>  # Rollback infrastructure changes
+   ```
+
+2. **Restore from local backup:**
+   ```bash
+   BACKUP_FILE=~/.terraform-backups/homelab/<timestamp>-terraform.tfstate
+   cd terraform
+   terraform state push $BACKUP_FILE
+   ```
+
+3. **Verify state:**
+   ```bash
+   terraform state list
+   terraform plan
+   ```
+
+## S3 Bucket Setup
+
+If S3 bucket doesn't exist, create it:
+
+```bash
+kubectl exec -n storage <minio-pod> -- mc mb minio/terraform-state --region us-east-1
+```
+
+## State Lock (Optional)
+
+For multi-person teams, enable state locking via DynamoDB (not yet configured).
+
+## Best Practices
+
+- ✓ Never commit `*.tfstate` or `*.tfstate.*` to git
+- ✓ Back up state before major `terraform apply` operations
+- ✓ Always run `terraform plan` before `terraform apply`
+- ✓ Review diff carefully for destructive changes
+- ✓ Keep state backend secure (MinIO has authentication)
+
+## Monitoring
+
+Check S3 backend status:
+```bash
+kubectl get pods -n storage -l app=minio
+# Or
+scripts/terraform-state-backup.sh
+```
+
+## Related Files
+
+- `terraform/state.tf` — Backend configuration
+- `scripts/terraform-state-backup.sh` — Automated backup script
+- `.gitignore` — Excludes local state files from git