Add comprehensive Kubernetes migration guide from local to production

This commit adds complete documentation and tooling for migrating from local development (Kind/Colima on macOS) to production deployment (MicroK8s on Ubuntu VPS at Clouding.io). Documentation added: - K8S-MIGRATION-GUIDE.md: Comprehensive step-by-step migration guide covering all phases from VPS setup to post-deployment operations - MIGRATION-CHECKLIST.md: Quick reference checklist for migration tasks - MIGRATION-SUMMARY.md: High-level overview and key changes summary Configuration updates: - Added storage-patch.yaml for MicroK8s storage class compatibility (changes from 'standard' to 'microk8s-hostpath') - Updated prod/kustomization.yaml to include storage patch Helper scripts: - deploy-production.sh: Interactive deployment script with validation - tag-and-push-images.sh: Automated image tagging and registry push - backup-databases.sh: Database backup script for production Key differences addressed: - Ingress: MicroK8s addon vs custom NGINX - Storage: MicroK8s hostpath vs Kind standard storage - Registry: Container registry configuration for production - SSL: Let's Encrypt production certificates - Domains: Real domain configuration vs localhost - Resources: Production-grade resource limits and scaling The migration guide covers: - VPS setup and MicroK8s installation - Configuration adaptations required - Container registry setup options - SSL certificate configuration - Monitoring and backup setup - Troubleshooting common issues - Security hardening checklist - Rollback procedures All existing Kubernetes manifests remain unchanged and compatible.
2026-01-02 14:57:09 +00:00
parent ddf95958d2
commit 23b8523b36
8 changed files with 1921 additions and 0 deletions
--- a/docs/MIGRATION-SUMMARY.md
+++ b/docs/MIGRATION-SUMMARY.md
@@ -0,0 +1,275 @@
+# 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! 🚀