docs(known-issues): documentar fix definitivo del blackhole MTU/PMTUD cross-node

Confirmado empiricamente el limite real (1420 OK / 1450 blackhole),
aplicado y validado el fix (flannel.1 mtu 1400 + rollout restart de
ecommerce). El podAffinity de medusa.yaml se deja como red de contencion,
ya no como requisito.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT

docs/known-issues.md

@@ -2,7 +2,8 @@
 
 ## Blackhole de red cross-node en el cluster k3d (MTU/PMTUD, flannel VXLAN)
 
-**Estado:** workaround aplicado, fix definitivo pendiente.
+**Estado:** RESUELTO (2026-08-16). Fix definitivo aplicado y validado; el
+`podAffinity` se deja como red de contención extra, no como requisito.
 
 **Síntoma:** cualquier pod que necesite hablar con `commerce-postgres-0`
 (StatefulSet, sin réplicas, fijo a un nodo) falla de forma consistente y
@@ -36,12 +37,46 @@ entre Medusa y Postgres, pero no resuelve el problema de fondo — cualquier
 otro workload que necesite cruzar nodos para hablar con Postgres (u otro
 servicio) puede pisar el mismo blackhole.
 
-**TODO — fix definitivo pendiente:**
+**Fix definitivo aplicado (2026-08-16):**
 
-Ajustar el MTU del cluster k3d a un valor seguro (`1400`) de forma
+Confirmado empíricamente con un pod de debug (`nicolaka/netshoot`, tiene
-consistente en la red Docker del cluster y en flannel, para eliminar el
+`ping` con soporte real de bit DF — el `ping` de BusyBox en la imagen de
-blackhole de raíz y poder quitar el `podAffinity` (o dejarlo como
+nodo de k3s no lo soporta) haciendo un sweep de payloads con
-optimización, no como requisito de disponibilidad).
+`ping -M do` cross-node hacia el pod de `commerce-postgres-0`: el límite
+real está entre payload interno **1420 (0% pérdida)** y **1450 (100%
+pérdida, sin ningún ICMP "frag needed" — blackhole real, no fragmentación
+normal)**. Coincide casi exactamente con el MTU que la propia interfaz
+`flannel.1` ya reportaba (1450, calculado como `eth0` 1500 − 50 de overhead
+VXLAN) — la aritmética de flannel es correcta, pero el último tramo no
+soporta en la práctica el paquete VXLAN a tamaño completo.
+
+`k3s` (que embebe flannel, no lo corre como binario/DaemonSet separado) no
+expone un flag `--flannel-mtu` en esta versión (confirmado con
+`k3s server --help`, ver `docs/gitops` o `scripts/deploy-lab.sh`). El único
+punto de ajuste real es la interfaz `flannel.1` en vivo dentro de cada
+contenedor de nodo: `docker exec <nodo> ip link set flannel.1 mtu 1400`. No
+persiste en ningún archivo — hay que reaplicarlo cada vez que el cluster
+arranca. Automatizado en `scripts/deploy-lab.sh` (función `fix_flannel_mtu`,
+llamada tanto en `create_cluster` como en `start_cluster`).
+
+Aplicar el nuevo MTU solo afecta pods **nuevos** — los que ya estaban
+corriendo mantienen el MTU viejo en su `veth` hasta que se recrean. Se hizo
+`kubectl rollout restart` de todo el namespace `ecommerce`
+(`commerce-postgres`, `commerce-redis`, `commerce-minio`, `medusa-deploy`,
+`catalog-api-deploy`, `frontend-deploy`) para que todos tomaran el MTU
+nuevo de inmediato.
+
+**Validación post-fix:** el mismo sweep de `ping -M do` ahora devuelve
+`Frag needed and DF set (mtu = 1400)` — PMTU Discovery funcionando
+correctamente, ya no hay blackhole silencioso. Confirmado además con
+tráfico TCP real cross-node hacia Postgres (conexión exitosa + transferencia
+de 50 KB sin colgarse, muy por encima del umbral que antes rompía).
+
+El `podAffinity` en `workloads/ecommerce/commerce/medusa.yaml` que fija
+`medusa-deploy` al mismo nodo que `commerce-postgres-0` **se deja tal
+cual** — ya no es necesario para evitar el blackhole, pero no tiene costo
+real y sirve como red de contención si el MTU real del entorno vuelve a
+cambiar (por ejemplo, tras una actualización de ZimaOS/Docker).
 
 ## Topología de red: Cloudflare Tunnel → Nginx Proxy Manager → k3d