veylant/docs/runbooks/traffic-spike.md

# Runbook — Pic de Trafic / Surcharge

**Alerte :** `VeylantHighLatencyP99` ou `VeylantHighErrorRate` + taux de requêtes anormalement élevé
**SLA impact :** Dégradation des performances, potentiellement interruptions
**Temps de résolution cible :** < 10 minutes (HPA automatique), < 5 min si intervention manuelle

---

## Symptômes

- Alerte `VeylantHighLatencyP99` : p99 > 500ms pendant > 5 min
- Alerte `VeylantHighErrorRate` : error rate > 5%
- Dashboard Grafana : RPS brutal augmentation, p99 qui monte
- Logs : `"rate limit exceeded"` massif pour une tenant, ou requests en queue

---

## Diagnostic

### 1. Évaluer l'ampleur du pic

```bash
# RPS actuel vs baseline
curl -s "http://prometheus:9090/api/v1/query" \
  --data-urlencode 'query=sum(rate(veylant_requests_total[1m]))' | \
  jq '.data.result[0].value[1]'

# Identifier le tenant / provider qui drive le trafic
curl -s "http://prometheus:9090/api/v1/query" \
  --data-urlencode 'query=topk(5, sum by (tenant_id) (rate(veylant_requests_total[1m])))' | \
  jq '.data.result[] | {tenant: .metric.tenant_id, rps: .value[1]}'

# État HPA
kubectl get hpa -n veylant
kubectl describe hpa veylant-proxy -n veylant
```

### 2. Vérifier si le HPA scale

```bash
# Vérifier le scaling automatique en cours
kubectl get hpa veylant-proxy -n veylant -w

# Pods actuels
kubectl get pods -n veylant -l app.kubernetes.io/name=veylant-proxy

# Events HPA
kubectl describe hpa veylant-proxy -n veylant | grep -A10 "Events:"
```

### 3. Vérifier l'état des providers upstream

```bash
# Latence upstream par provider
kubectl logs -n veylant deploy/veylant-proxy-blue --since=5m | \
  grep "upstream_duration" | \
  awk '{sum+=$NF; count++} END {print "avg:", sum/count, "ms"}'
```

---

## Remédiation

### A — HPA automatique (cas normal)

Si le HPA est configuré et que les pods scalent :

```bash
# Observer le scaling (attendre 30-60 secondes)
kubectl get hpa veylant-proxy -n veylant -w

# Surveiller les nouveaux pods qui deviennent Ready
kubectl get pods -n veylant -l app.kubernetes.io/name=veylant-proxy -w
```

Si le scaling prend > 5 minutes → **forcer le scale manuel (Option B)**.

### B — Scale manuel d'urgence

```bash
# Scale immédiat sans attendre l'HPA
kubectl scale deployment veylant-proxy-blue -n veylant --replicas=10

# Vérifier que les pods démarrent
kubectl rollout status deployment/veylant-proxy-blue -n veylant

echo "Scaled to 10 replicas — monitor for 2 minutes"
```

### C — Activer le rate limiting agressif temporaire

Si un seul tenant consomme la majorité du trafic :

```bash
# Identifier le tenant abusif
ABUSIVE_TENANT=$(kubectl logs -n veylant deploy/veylant-proxy-blue --since=5m | \
  grep "rate_limit" | grep -oP 'tenant_id=[^ ]+' | sort | uniq -c | sort -rn | head -1)
echo "Abusive tenant: $ABUSIVE_TENANT"

# Réduire temporairement la limite du tenant via l'API admin
curl -sf -X PATCH \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requests_per_minute": 10}' \
  "https://api.veylant.ai/v1/admin/tenants/$TENANT_ID/rate-limit"

echo "Rate limit réduit à 10 req/min pour $TENANT_ID"
```

### D — Circuit breaker manuel (trafic trop élevé pour les providers)

```bash
# Activer temporairement la réponse cached / dégradée
# (feature flag maintenance-mode)
curl -sf -X PATCH \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "message": "Service en charge élevée. Réessayez dans quelques minutes."}' \
  https://api.veylant.ai/v1/admin/flags/maintenance-mode

# Désactiver une fois le trafic revenu à la normale
curl -sf -X PATCH \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' \
  https://api.veylant.ai/v1/admin/flags/maintenance-mode
```

### E — Retour à l'état normal

```bash
# Une fois le trafic normalisé, remettre le HPA en contrôle
kubectl patch hpa veylant-proxy -n veylant \
  --type=merge \
  -p '{"spec":{"minReplicas":3,"maxReplicas":15}}'

# Le HPA réduira le nombre de pods progressivement
echo "HPA reprend le contrôle — stabilisation en 5-10 min"
```

---

## Prévention

- HPA configuré avec `maxReplicas: 15` et scale-up rapide (100% en 60s)
- Rate limiting per-tenant activé (DB overrides disponibles)
- Circuit breaker activé avec threshold=5 failures / 60s window
- k6 smoke test en CI pour détecter les régressions de performance

---

## Post-mortem Template

```markdown
## Post-mortem — Traffic Spike [DATE]

**Pic observé :** [X RPS vs baseline Y RPS]
**Durée d'impact :** [X minutes p99 > 500ms]
**Cause :** [Charge légitime / Tenant abusif / DDoS / Bug client]

### Timeline
- HH:MM — Alerte HighLatencyP99 reçue
- HH:MM — Diagnostic : [cause identifiée]
- HH:MM — Action : [Scale manuel / Rate limit / Maintenance mode]
- HH:MM — Retour à la normale

### Root Cause
[Description]

### Actions correctives
- [ ] Revoir les limites HPA maxReplicas si insuffisant
- [ ] Ajouter rate limit global cross-tenant si nécessaire
- [ ] Communication avec le tenant si abus constaté
```