# 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