From 86fcc88a1e303b69cc69e57f3b3a10aba8ac6d74 Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Sun, 16 Aug 2026 23:00:45 -0500 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_011FqYP3Wf1W63Qmh7qgXAAT --- docs/known-issues.md | 47 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 41 insertions(+), 6 deletions(-) diff --git a/docs/known-issues.md b/docs/known-issues.md index 23d8aed..651c4f0 100644 --- a/docs/known-issues.md +++ b/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 -consistente en la red Docker del cluster y en flannel, para eliminar el -blackhole de raíz y poder quitar el `podAffinity` (o dejarlo como -optimización, no como requisito de disponibilidad). +Confirmado empíricamente con un pod de debug (`nicolaka/netshoot`, tiene +`ping` con soporte real de bit DF — el `ping` de BusyBox en la imagen de +nodo de k3s no lo soporta) haciendo un sweep de payloads con +`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 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