Runbook: NATS Transporter Down

Severita: Critical Alert Prometheus: NATSTransporterDown

Descrizione

Questo alert si attiva quando il transporter NATS, che gestisce tutta la comunicazione inter-servizio nella piattaforma Moleculer, non e raggiungibile. NATS e il bus di messaggistica centrale: senza di esso, nessun microservizio puo chiamare action di altri servizi, emettere eventi o partecipare alla service discovery.

L'endpoint NATS della piattaforma e nats://nats.sellogic.cloud:4222.

Regola Prometheus:

moleculer_transporter_connected{namespace="pos-enterprise"} == 0

oppure:

up{job="nats-exporter"} == 0

Impatto

• Comunicazione inter-servizio bloccata: tutte le ctx.call() tra servizi falliscono con TransporterDisconnectedError.
• Service discovery interrotta: nuovi pod non vengono scoperti, pod rimossi non vengono deregistrati.
• Circuit breaker attivati: tutti i circuit breaker si aprono per timeout, anche quando i servizi individuali sono sani.
• Gateway funziona parzialmente: le richieste HTTP arrivano al gateway ma non possono essere inoltrate ai microservizi.
• Eventi persi: ctx.emit() e ctx.broadcast() non vengono consegnati.
• Sync interrotto: i client Flutter non ricevono aggiornamenti real-time.

Diagnosi

1. Verificare la connettivita NATS dal cluster

# Test di connessione base
kubectl run nats-test --rm -it --image=natsio/nats-tools -n pos-enterprise -- \
  nats server check connection --server=nats://nats.sellogic.cloud:4222

# Test di pubblicazione/sottoscrizione
kubectl run nats-test --rm -it --image=natsio/nats-tools -n pos-enterprise -- \
  nats pub test.health "ping" --server=nats://nats.sellogic.cloud:4222

2. Verificare lo stato del transporter nei servizi

# Controllare i log del gateway per errori di connessione NATS
kubectl logs deployment/api-gateway -n pos-enterprise --tail=50 | grep -i "nats\|transporter\|disconnect"

# Controllare tutti i nodi
for deploy in $(kubectl get deployments -n pos-enterprise -o name); do
  echo "=== $deploy ==="
  kubectl logs $deploy -n pos-enterprise --tail=10 | grep -i "nats\|disconnect\|reconnect" 2>/dev/null
done

3. Verificare il DNS

kubectl run dns-test --rm -it --image=busybox -n pos-enterprise -- \
  nslookup nats.sellogic.cloud

4. Controllare le metriche NATS

Se NATS ha un exporter Prometheus:

# Connessioni attive
nats_server_connections{server="nats.sellogic.cloud"}

# Messaggi in/out
rate(nats_server_messages_total[5m])

# Slow consumers
nats_server_slow_consumers

5. Verificare la configurazione del transporter

# Estrarre la configurazione dal ConfigMap o env
kubectl get deployment api-gateway -n pos-enterprise \
  -o jsonpath='{.spec.template.spec.containers[0].env}' | \
  jq '.[] | select(.name | test("NATS|TRANSPORTER"))'

6. Verificare se il problema e di rete o di server

# Traceroute verso NATS
kubectl run trace-test --rm -it --image=nicolaka/netshoot -n pos-enterprise -- \
  traceroute nats.sellogic.cloud

# Test di latenza
kubectl run ping-test --rm -it --image=nicolaka/netshoot -n pos-enterprise -- \
  ping -c 5 nats.sellogic.cloud

Risoluzione

Scenario A: NATS Cloud temporaneamente irraggiungibile

Se NATS Cloud (Synadia) ha un'interruzione temporanea:

# Moleculer ha riconnessione automatica built-in.
# Verificare che la riconnessione avvenga controllando i log:
kubectl logs deployment/api-gateway -n pos-enterprise -f | grep -i "reconnect"

# Se necessario, forzare la riconnessione riavviando i pod
kubectl rollout restart deployment api-gateway -n pos-enterprise

Scenario B: Credenziali NATS scadute o errate

# Verificare le credenziali nel secret
kubectl get secret pos-enterprise-secrets -n pos-enterprise \
  -o jsonpath='{.data.NATS_URL}' | base64 -d

# Aggiornare se necessario
kubectl patch secret pos-enterprise-secrets -n pos-enterprise \
  -p='{"data":{"NATS_URL":"'"$(echo -n 'nats://user:newpass@nats.sellogic.cloud:4222' | base64)"'"}}'

# Riavviare tutti i deployment per applicare
kubectl rollout restart deployment -n pos-enterprise

Scenario C: Problema di rete (firewall, DNS)

# Verificare le Network Policy
kubectl get networkpolicies -n pos-enterprise

# Verificare che le egress rules permettano la porta 4222
kubectl describe networkpolicy -n pos-enterprise

Scenario D: Failover a NATS locale d'emergenza

Se NATS Cloud e irrecuperabile e serve un ripristino immediato:

# Deploy NATS temporaneo nel cluster
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nats-emergency
  namespace: pos-enterprise
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nats-emergency
  template:
    metadata:
      labels:
        app: nats-emergency
    spec:
      containers:
      - name: nats
        image: nats:2.10-alpine
        ports:
        - containerPort: 4222
---
apiVersion: v1
kind: Service
metadata:
  name: nats-emergency-svc
  namespace: pos-enterprise
spec:
  selector:
    app: nats-emergency
  ports:
  - port: 4222
EOF

# Aggiornare i servizi per usare il NATS locale
kubectl set env deployment --all -n pos-enterprise \
  TRANSPORTER="nats://nats-emergency-svc.pos-enterprise.svc.cluster.local:4222"

ATTENZIONE: il NATS d'emergenza non ha persistence. Tornare a NATS Cloud appena possibile.

Verifica post-ripristino

# Verificare che tutti i nodi Moleculer siano connessi
curl -s https://platform.sellogic.cloud/api/\$node/list | jq '.[].hostname'

# Verificare la service discovery
curl -s https://platform.sellogic.cloud/api/\$node/services | jq '.[].name' | sort

# Test end-to-end: creare un ordine di test
curl -s -X POST https://platform.sellogic.cloud/api/orders \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"type":"test","items":[]}' | jq .status

Prevenzione

• Monitoraggio proattivo: alert quando le riconnessioni NATS superano 3 in 5 minuti.
• Connection pooling: configurare maxReconnectAttempts: -1 (infinito) nel moleculer.config.js.
• NATS cluster multi-zona: utilizzare NATS con almeno 3 nodi in zone diverse.
• Retry policy Moleculer: configurare retryPolicy nel broker per gestire disconnessioni temporanee.

// moleculer.config.js
transporter: {
  type: "NATS",
  options: {
    url: process.env.NATS_URL,
    maxReconnectAttempts: -1,
    reconnectTimeWait: 2000,
    pingInterval: 10000,
  }
},
retryPolicy: {
  enabled: true,
  retries: 5,
  delay: 100,
  maxDelay: 2000,
  factor: 2,
  check: err => err && err.retryable
}

• Health check NATS: includere lo stato del transporter nella readiness probe.

Escalation

Livello	Condizione	Contatto
L1 - Ops	Disconnessione < 2 min, riconnessione automatica	Monitorare, nessuna azione
L2 - Ops	Disconnessione > 2 min	Team Ops - diagnosi rete
L3 - Infra	NATS Cloud outage	DevOps Lead + ticket Synadia
L4 - Management	Outage > 15 min	CTO - attivare failover locale

Tempo massimo di risposta: 5 minuti. NATS down equivale a piattaforma down.