Runbook: Tutti i Gateway Pod Down

Severita: Critical Alert Prometheus: AllGatewayPodsDown

Descrizione

Questo alert si attiva quando tutti i pod del deployment api-gateway nel namespace pos-enterprise sono non disponibili. Rappresenta un'interruzione totale del traffico API poiche l'API Gateway Moleculer (moleculer-web) e il singolo punto di ingresso per tutte le richieste client (Flutter, Vue admin console, webhook).

Regola Prometheus:

kube_deployment_status_replicas_available{namespace="pos-enterprise", deployment="api-gateway"} == 0

Impatto

• Outage totale: nessuna richiesta HTTP raggiunge i microservizi. Tutte le app client (cassa_ui, waiter_ui, kiosk_ui, admin console) ricevono errori di connessione.
• Health check falliti: i load balancer upstream rimuovono il backend dalla rotazione, restituendo HTTP 502/503.
• Ordini persi: gli ordini in fase di invio non vengono processati (mitigato dalla modalita offline-first di Flutter).
• Autenticazione bloccata: il flusso JWT/Keycloak transita per il gateway.
• Webhook non ricevuti: callback da payment gateway e servizi terzi falliscono.

Diagnosi

1. Verificare lo stato dei pod gateway

kubectl get pods -n pos-enterprise -l app=api-gateway
kubectl get deployment api-gateway -n pos-enterprise

2. Verificare lo stato dell'Ingress

# Controllare l'Ingress e i suoi endpoint
kubectl get ingress -n pos-enterprise
kubectl describe ingress pos-enterprise-ingress -n pos-enterprise

# Verificare che gli endpoint del service siano vuoti (confermano tutti i pod down)
kubectl get endpoints api-gateway-svc -n pos-enterprise

3. Test diretto dall'esterno

# Health check del gateway
curl -v https://platform.sellogic.cloud/api/health
# Risposta attesa: 200 OK con { "status": "ok", ... }
# Se 502/503: gateway down confermato

# Test con timeout ridotto
curl -m 5 -s -o /dev/null -w "%{http_code}" https://platform.sellogic.cloud/api/health

4. Controllare gli eventi del deployment

kubectl describe deployment api-gateway -n pos-enterprise
kubectl get events -n pos-enterprise --sort-by='.lastTimestamp' | grep -i gateway

5. Controllare lo stato dei nodi K8s

# Verificare che i nodi siano sani
kubectl get nodes
kubectl top nodes

# Verificare se c'e un problema di scheduling
kubectl get pods -n pos-enterprise -l app=api-gateway -o wide

6. Verificare le dipendenze del gateway

Il gateway Moleculer richiede:

# NATS (transporter)
kubectl run debug-net --rm -it --image=nicolaka/netshoot -n pos-enterprise -- \
  nc -zv nats.sellogic.cloud 4222

# Redis (cacher)
kubectl run debug-redis --rm -it --image=redis:7-alpine -n pos-enterprise -- \
  redis-cli -u "redis://:<password>@redis-xxxxx.cloud.redislabs.com:16379" ping

7. Controllare i log

# Log degli ultimi tentativi di avvio
kubectl logs deployment/api-gateway -n pos-enterprise --previous --tail=100

# Se i pod non esistono, controllare i ReplicaSet
kubectl get rs -n pos-enterprise -l app=api-gateway
kubectl describe rs <RS_NAME> -n pos-enterprise

Risoluzione

Scenario A: Pod in CrashLoopBackOff

Vedere il runbook Pod CrashLooping. Procedura rapida:

# Eliminare i pod per forzare la ri-creazione
kubectl delete pods -n pos-enterprise -l app=api-gateway

# Monitorare il riavvio
kubectl get pods -n pos-enterprise -l app=api-gateway -w

Scenario B: Nodi senza risorse

# Verificare risorse disponibili
kubectl describe nodes | grep -A 8 "Allocated resources"

# Scale down temporaneo di servizi meno critici per liberare risorse
kubectl scale deployment knowledge-node -n pos-enterprise --replicas=0
kubectl scale deployment scheduler-node -n pos-enterprise --replicas=0

# Riavviare il gateway
kubectl rollout restart deployment api-gateway -n pos-enterprise

Scenario C: Problema di immagine Docker

# Verificare l'immagine attuale
kubectl get deployment api-gateway -n pos-enterprise -o jsonpath='{.spec.template.spec.containers[0].image}'

# Se l'immagine non e raggiungibile, usare l'ultima nota funzionante
kubectl set image deployment/api-gateway -n pos-enterprise \
  moleculer=registry.sellogic.cloud/pos-backend:last-known-good

Scenario D: Errore di configurazione post-deploy

# Rollback al deploy precedente
kubectl rollout undo deployment/api-gateway -n pos-enterprise

# Verificare
kubectl rollout status deployment/api-gateway -n pos-enterprise

Scaling d'emergenza

# Aumentare le repliche per ripristino rapido
kubectl scale deployment api-gateway -n pos-enterprise --replicas=3

# Verificare che i pod siano pronti
kubectl wait --for=condition=ready pod -l app=api-gateway -n pos-enterprise --timeout=120s

# Verifica post-ripristino
curl -s https://platform.sellogic.cloud/api/health | jq .

Failover manuale: pod temporaneo

Se il deployment non riesce a creare pod funzionanti, lanciare un pod standalone d'emergenza:

kubectl run api-gateway-emergency -n pos-enterprise \
  --image=registry.sellogic.cloud/pos-backend:stable \
  --env="SERVICEDIR=services/api.service.js" \
  --env="TRANSPORTER=nats://nats.sellogic.cloud:4222" \
  --port=3000 \
  --labels="app=api-gateway" \
  --restart=Never

# Verificare che il service selector lo includa
kubectl get endpoints api-gateway-svc -n pos-enterprise

Prevenzione

• Minimo 2 repliche per il deployment api-gateway, con podAntiAffinity per distribuire su nodi diversi.
• PodDisruptionBudget: garantire almeno 1 pod attivo durante manutenzione.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api-gateway-pdb
  namespace: pos-enterprise
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: api-gateway

• Preemption priority: assegnare PriorityClass elevata al gateway per evitare eviction.
• Health check rigorosi: liveness e readiness probe su porta 3001 con soglie appropriate.
• Canary deployment: non aggiornare tutti i pod gateway contemporaneamente.

Escalation

Livello	Condizione	Contatto
L1 - Ops	Alert ricevuto, diagnosi in corso	Team Ops (Slack #pos-ops-critical)
L2 - Infra	Problema di nodi o risorse	DevOps Lead (telefono)
L3 - Management	Outage > 15 minuti	CTO + Communication Team

Tempo massimo di risposta: 5 minuti. Questo e l'alert con la massima priorita: outage totale della piattaforma.

Comunicazione: se l'outage supera i 10 minuti, aggiornare la status page su status.sellogic.cloud e notificare i clienti via email automatica.