- New Build and startup procedures for all services, compliant for both docker, podman and k8s

documentation/k8s_migratie_startup_containers_overzicht.md

@@ -0,0 +1,106 @@
+# 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:  
+  ```bash
+  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.  
+
+---