docs/known-issues.md

@@ -0,0 +1,44 @@
+# Known issues
+
+## Blackhole de red cross-node en el cluster k3d (MTU/PMTUD, flannel VXLAN)
+
+**Estado:** workaround aplicado, fix definitivo pendiente.
+
+**Síntoma:** cualquier pod que necesite hablar con `commerce-postgres-0`
+(StatefulSet, sin réplicas, fijo a un nodo) falla de forma consistente y
+reproducible al 100% cuando queda agendado en un nodo **distinto** al de
+Postgres. El handshake TCP (SYN/ACK, `nc`, `ping`) funciona perfecto entre
+nodos, pero el primer paquete de datos real de la sesión (protocolo Postgres,
+`pg_isready` incluido) nunca llega — se cuelga hasta hacer timeout.
+
+**Diagnóstico:**
+
+- Confirmado aislando el nodo con `nodeName` en pods de prueba: 100% de
+  fallos (186/186 intentos) agendando cross-node (`agent-0` → Postgres en
+  `server-0`); 100% de éxito agendando en el mismo nodo.
+- MTU dentro de los pods (interfaz `flannel.1`/VXLAN) es 1450 en ambos nodos
+  — consistente, no es un mismatch obvio a nivel flannel.
+- `ping` sin `-M do` (permite fragmentación) no muestra pérdida de paquetes
+  hasta payloads de 2000 bytes entre los contenedores Docker de los nodos.
+- Encaja con un blackhole de PMTU Discovery: el bridge Docker externo que
+  conecta los contenedores de los nodos k3d probablemente tiene un MTU real
+  menor a 1500, y los paquetes TCP con el bit DF puesto (como los de la
+  sesión de Postgres) se pierden en vez de fragmentarse o generar el ICMP
+  "fragmentation needed" que permitiría el ajuste automático.
+
+**Workaround temporal (aplicado en `workloads/ecommerce/commerce/medusa.yaml`):**
+
+`podAffinity` con `requiredDuringSchedulingIgnoredDuringExecution` sobre
+`medusa-deploy`, forzando que sus pods se agenden siempre en el mismo nodo
+que `commerce-postgres-0` (`matchLabels: app: commerce-postgres`,
+`topologyKey: kubernetes.io/hostname`). Esto evita el tráfico cross-node
+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:**
+
+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).

workloads/ecommerce/commerce/medusa.yaml

@@ -20,6 +20,14 @@ spec:
       imagePullSecrets:
         - name: gitea-registry-secret
 
+      affinity:
+        podAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+            - labelSelector:
+                matchLabels:
+                  app: commerce-postgres
+              topologyKey: kubernetes.io/hostname
+
       initContainers:
         - name: wait-for-postgres
           image: postgres:17-alpine