homelab/docs/TERRAFORM-STATE.md

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

cd terraform
terraform state pull > terraform.tfstate.backup

View resources

terraform state list
terraform state show <resource-name>

Import new resources

terraform import <resource-type>.<name> <resource-id>

Backup Strategy

Automatic backups

Run the backup script periodically (e.g., cron):

scripts/terraform-state-backup.sh

Backups are saved to: ~/.terraform-backups/homelab/

Manual backup

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:

   git revert <commit>  # Rollback infrastructure changes
   

2. Restore from local backup:

   BACKUP_FILE=~/.terraform-backups/homelab/<timestamp>-terraform.tfstate
   cd terraform
   terraform state push $BACKUP_FILE
   

3. Verify state:

   terraform state list
   terraform plan
   

S3 Bucket Setup

If S3 bucket doesn't exist, create it:

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:

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