eveAI/documentation/k8s_migratie_startup_containers_overzicht.md

Overzicht Kubernetes Migratie — eveai_app & eveai_workers

Dit document bundelt de belangrijkste inzichten en keuzes rond het migreren van je applicatiecomponenten naar Kubernetes.
(⚠️ Build-optimalisaties zijn hier niet meegenomen — die volgen eventueel later.)

---

1. Conceptuele inzichten

1.1 Webcomponenten (eveai_app)

• Gunicorn workers
  • -w = aantal processen (CPU-parallelisme).
  • --worker-connections = max. aantal gelijktijdige connecties per worker (bij async workers zoals gevent).
• Memory
  • Elke replica = eigen Pod = eigen memory footprint.
  • Binnen een Pod: elke workerproces neemt (bijna) z’n eigen geheugenruimte.
  • Image-grootte ≠ runtime memory (grote image → trager deployen, maar geen direct effect op RAM).
• Schaalstrategie
  • In Kubernetes hou je -w laag (1–2), en schaal je horizontaal met replicas.
  • Extern verkeer gaat via Ingress (poort 80/443, hostnames/paths).
  • Geen nood meer om per service aparte poorten te kiezen zoals in Docker.

1.2 Database migratie & startup-acties

• Huidige situatie: migrations + cache-acties gebonden aan container startup.
• Aanbevolen aanpak:
  • Gebruik Kubernetes Jobs voor eenmalige taken (bv. DB-migraties, cache-invalidate, re-index).
  • Gebruik CronJobs voor geplande taken (bv. nachtelijke purges, periodieke warm-ups).
• Jobs vs. Helm Hooks
  • Job: los uit te voeren, flexibel, manueel of via CI/CD te triggeren.
  • Helm Hook: gekoppeld aan een release, garandeert volgorde, maar minder flexibel.
  • Aanbevolen: Jobs voor flexibiliteit en onderhoud.

1.3 Backendcomponenten (eveai_workers met Celery)

• Worker Pods
  • Eén rol per Pod:
    • Workers (prefork pool, concurrency afgestemd op CPU).
    • Beat (scheduler) als apart Deployment indien nodig.
    • Flower (monitoring) als aparte Deployment (optioneel).
• Betrouwbaarheid
  • Gebruik acks_late, task_reject_on_worker_lost, en visibility_timeout.
  • Prefetch multiplier = 1, fairness inschakelen.
  • Time limits per taak instellen.
  • Taken idempotent maken.
• Queues & Routing
  • Verdeel workload over meerdere queues (bv. high, default, low).
  • Start gespecialiseerde workers die alleen luisteren naar de relevante queue.
• Autoscaling
  • Kubernetes HPA (CPU/memory) is beperkt.
  • Gebruik KEDA → schaalt workers op basis van queue-lengte.
• Graceful shutdown
  • terminationGracePeriodSeconds ≥ task timeout.
  • Celery stopt intake en werkt lopende taken af.

1.4 Flower

• Flower is een monitoring UI voor Celery (geen onderdeel van je app).
• Kan standalone worden gedeployed via een generieke container (mher/flower).
• Configuratie via Helm chart mogelijk (zelfgemaakt of community chart).
• Overhead van Airflow is niet nodig — enkel Flower volstaat in jouw setup.

1.5 RBAC (conceptueel)

• Role-Based Access Control = mechanisme om te bepalen wie wat mag doen in k8s.
• Componenten:
  • Role/ClusterRole = welke acties op welke resources.
  • RoleBinding/ClusterRoleBinding = koppelt Role aan gebruikers/ServiceAccounts.
  • ServiceAccount = identiteit die een Pod gebruikt.
• Belangrijk: principe van least privilege → Jobs/Workers krijgen enkel de rechten die ze nodig hebben.

---

2. Praktische aandachtspunten

Webcomponent (eveai_app)

• Bind port via env var (PORT=8080), niet hardcoded.
• Voeg health endpoints toe (/healthz) voor readiness/liveness probes.
• Logs naar stdout/stderr.
• Resources instellen voor pods (requests/limits).
• Migrations verplaatsen naar Job/Hook.

Backendcomponent (eveai_workers)

• Startscript aanpassen met veilige defaults:

  celery -A scripts.run_eveai_workers worker     --loglevel=INFO     --concurrency=2     --max-tasks-per-child=1000     --prefetch-multiplier=1 -O fair
  

• Beat enkel gebruiken als je periodieke Celery-taken nodig hebt.
• Flower los deployen (Deployment + Service + optioneel Ingress).
• Overweeg KEDA voor autoscaling op queue-lengte.
• Voeg een PodDisruptionBudget toe om altijd workers beschikbaar te houden.

Jobs & CronJobs

• Gebruik Jobs voor DB-migraties en startup-actions (cache invalidatie, warmup).
• Gebruik CronJobs voor geplande onderhoudstaken.
• Maak taken idempotent en stel deadlines/backoff limits in.
• Opruimen met ttlSecondsAfterFinished.

---

3. Samenvattende aanbevelingen

1. Haal startup-acties uit je app-containers → verplaats naar Jobs/CronJobs.
2. Hou app-containers slank en simpel → 1–2 workers per pod, schaal met replicas.
3. Beheer Celery-taken betrouwbaar → acks_late, visibility_timeout, idempotentie.
4. Scheiding van verantwoordelijkheden → workers, beat (indien nodig), flower los deployen.
5. Monitoring & autoscaling → gebruik health probes, resource limits, en KEDA voor workers.
6. Security → gebruik RBAC & Secrets om toegang netjes te beperken.
7. Flower → volstaat standalone, geen Airflow nodig.

---