bakery-ia/docs/MIGRATION-SUMMARY.md

# Migration Summary: Local to Production

## Quick Overview

You're migrating from **Kind/Colima (macOS)** to **MicroK8s (Ubuntu VPS)**.

Good news: **Most of your Kubernetes configuration is already production-ready!** Your infrastructure is well-structured with proper overlays for dev and prod environments.

## What You Already Have ✅

Your configuration already includes:
- ✅ Separate dev and prod overlays
- ✅ Production ingress configuration
- ✅ Production ConfigMap with proper settings
- ✅ Resource scaling (2-3 replicas per service in prod)
- ✅ HorizontalPodAutoscalers for key services
- ✅ Security configurations (TLS, secrets, etc.)
- ✅ Database configurations
- ✅ Monitoring components (Prometheus, Grafana)

## What Needs to Change 🔧

### Critical Changes (Must Do)

1. **Domain Names** - Update in `infrastructure/kubernetes/overlays/prod/prod-ingress.yaml`:
   - Replace `bakery.yourdomain.com` → your actual domain
   - Replace `api.yourdomain.com` → your actual API domain
   - Replace `monitoring.yourdomain.com` → your actual monitoring domain
   - Update CORS origins
   - Update cert-manager email

2. **Storage Class** - Already patched in `storage-patch.yaml`:
   - `standard` → `microk8s-hostpath`

3. **Production Secrets** - Update in `infrastructure/kubernetes/base/secrets.yaml`:
   - Generate strong passwords
   - Update all sensitive values
   - **Never commit real secrets to git!**

4. **Container Registry** - Choose and configure:
   - Docker Hub (easiest)
   - GitHub Container Registry
   - MicroK8s built-in registry
   - Update image references in prod kustomization

### Setup on VPS

1. **Install MicroK8s**:
   ```bash
   sudo snap install microk8s --classic
   microk8s enable dns hostpath-storage ingress cert-manager metrics-server
   ```

2. **Configure Firewall**:
   ```bash
   sudo ufw allow 22/tcp 80/tcp 443/tcp
   sudo ufw enable
   ```

3. **DNS Configuration**:
   Point your domains to VPS IP address

## File Changes Summary

### New Files Created
```
docs/K8S-MIGRATION-GUIDE.md                          # Comprehensive guide
docs/MIGRATION-CHECKLIST.md                          # Quick checklist
docs/MIGRATION-SUMMARY.md                            # This file
infrastructure/kubernetes/overlays/prod/storage-patch.yaml   # Storage fix
scripts/deploy-production.sh                         # Deployment helper
scripts/tag-and-push-images.sh                       # Image management
scripts/backup-databases.sh                          # Backup script
```

### Files to Modify

1. **infrastructure/kubernetes/overlays/prod/prod-ingress.yaml**
   - Update domain names (3 places)
   - Update CORS origins
   - Update cert-manager email

2. **infrastructure/kubernetes/base/secrets.yaml**
   - Update all secrets with production values
   - Generate strong passwords

3. **infrastructure/kubernetes/overlays/prod/kustomization.yaml**
   - Update image registry prefixes if using external registry
   - Already includes storage patch

## Key Differences Table

| Feature | Local (Kind) | Production (MicroK8s) | Action Required |
|---------|--------------|----------------------|-----------------|
| **Cluster** | Kind in Docker | Native MicroK8s | Install MicroK8s |
| **Ingress** | Custom NGINX | MicroK8s addon | Enable addon |
| **Storage** | `standard` | `microk8s-hostpath` | Use storage patch ✅ |
| **Images** | Local build | Registry push | Setup registry |
| **Domains** | localhost | Real domains | Update ingress |
| **SSL** | Self-signed | Let's Encrypt | Configure email |
| **Replicas** | 1 per service | 2-3 per service | Already configured ✅ |
| **Resources** | Minimal | Production limits | Already configured ✅ |
| **Secrets** | Dev secrets | Production secrets | Update values |
| **Monitoring** | Optional | Recommended | Already configured ✅ |

## Deployment Steps (Quick Version)

### Phase 1: Prepare (On Local Machine)
```bash
# 1. Update domain names
vim infrastructure/kubernetes/overlays/prod/prod-ingress.yaml

# 2. Update secrets (use strong passwords!)
vim infrastructure/kubernetes/base/secrets.yaml

# 3. Build and push images
docker login  # or setup your registry
./scripts/tag-and-push-images.sh YOUR_USERNAME/bakery latest

# 4. Update image references if using external registry
vim infrastructure/kubernetes/overlays/prod/kustomization.yaml
```

### Phase 2: Setup VPS
```bash
# SSH to VPS
ssh user@YOUR_VPS_IP

# Install MicroK8s
sudo snap install microk8s --classic --channel=1.28/stable
sudo usermod -a -G microk8s $USER
newgrp microk8s

# Enable addons
microk8s enable dns hostpath-storage ingress cert-manager metrics-server rbac

# Setup kubectl
echo "alias kubectl='microk8s kubectl'" >> ~/.bashrc
source ~/.bashrc

# Configure firewall
sudo ufw allow 22/tcp 80/tcp 443/tcp
sudo ufw enable
```

### Phase 3: Deploy
```bash
# On VPS - clone your repo or copy manifests
git clone YOUR_REPO_URL
cd bakery_ia

# Deploy
kubectl apply -k infrastructure/kubernetes/overlays/prod

# Monitor
kubectl get pods -n bakery-ia -w

# Check everything
kubectl get all,ingress,pvc,certificate -n bakery-ia
```

### Phase 4: Verify
```bash
# Test access
curl -k https://bakery.yourdomain.com
curl -k https://api.yourdomain.com/health

# Check SSL
kubectl get certificate -n bakery-ia

# Check logs
kubectl logs -n bakery-ia deployment/gateway
```

## Common Pitfalls to Avoid

1. **Forgot to update domain names** → Ingress won't work
2. **Using dev secrets in production** → Security risk
3. **DNS not propagated** → SSL certificate won't issue
4. **Firewall blocking ports 80/443** → Can't access application
5. **Images not in registry** → Pods fail with ImagePullBackOff
6. **Wrong storage class** → PVCs stay pending
7. **Insufficient VPS resources** → Pods get evicted

## Resource Requirements

### Minimum VPS Specs
- **CPU**: 4 cores (6+ recommended)
- **RAM**: 8GB (16GB+ recommended)
- **Disk**: 100GB (SSD preferred)
- **Network**: Public IP with ports 80/443 open

### Resource Usage Estimates
With current prod configuration:
- ~20-30 pods running
- ~4-6GB memory used
- ~2-3 CPU cores used
- ~10-20GB disk for databases

## Testing Strategy

1. **Local Testing** (Before deploying):
   - Build all images successfully
   - Test with `skaffold build -f skaffold-prod.yaml`
   - Validate kustomization: `kubectl kustomize infrastructure/kubernetes/overlays/prod`

2. **Staging Deploy** (First deploy):
   - Deploy to staging/test environment first
   - Test all functionality
   - Verify SSL certificates
   - Load test

3. **Production Deploy**:
   - Deploy during low-traffic window
   - Have rollback plan ready
   - Monitor closely for first 24 hours

## Rollback Plan

If deployment fails:
```bash
# Quick rollback
kubectl rollout undo deployment/DEPLOYMENT_NAME -n bakery-ia

# Or delete and redeploy previous version
kubectl delete -k infrastructure/kubernetes/overlays/prod
# Deploy previous version
```

Always have:
- Previous version images tagged
- Database backups
- Configuration backups

## Post-Deployment Checklist

- [ ] Application accessible via HTTPS
- [ ] SSL certificates valid
- [ ] All services healthy
- [ ] Database migrations completed
- [ ] Monitoring configured
- [ ] Backups scheduled
- [ ] Alerts configured
- [ ] Team has access
- [ ] Documentation updated
- [ ] Runbooks created

## Getting Help

- **Full Guide**: See `docs/K8S-MIGRATION-GUIDE.md`
- **Checklist**: See `docs/MIGRATION-CHECKLIST.md`
- **MicroK8s**: https://microk8s.io/docs
- **Kubernetes**: https://kubernetes.io/docs

## Estimated Timeline

- **VPS Setup**: 30-60 minutes
- **Configuration Updates**: 30-60 minutes
- **Image Build & Push**: 20-40 minutes
- **Deployment**: 15-30 minutes
- **Verification & Testing**: 30-60 minutes
- **Total**: 2-4 hours (first time)

With experience: ~1 hour for updates/redeployments

## Next Steps

1. Read through the full migration guide
2. Provision your VPS
3. Update configuration files
4. Test locally first
5. Deploy to production
6. Monitor and optimize

Good luck! 🚀