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:

   sudo snap install microk8s --classic
   microk8s enable dns hostpath-storage ingress cert-manager metrics-server
   

2. Configure Firewall:

   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)

# 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

# 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

# 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

# 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:

# 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! 🚀