apps-registry/docs/known-issues.md

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).

Topología de red: Cloudflare Tunnel → Nginx Proxy Manager → k3d

Estado: referencia de arquitectura — no es un issue abierto, pero el patrón de falla que describe ya se repitió una vez (ver docs/playbooks/incidente-medusa-imagenes-proxy-npm-2026-08.md) y puede volver a aparecer con otro subdominio.

Ruta real de una petición pública a *.cruzcloud.net:

Internet → Cloudflare (DNS proxied, túnel) → contenedor `cloudflared`
  (app nativa de ZimaOS, red Host) → Nginx Proxy Manager
  (contenedor `nginxproxymanager`, config en
  /DATA/AppData/nginxproxymanager/data/) → 192.168.68.61:90
  → `k3d-lab-cluster-serverlb` (k3d-proxy, publica 90→80 y 9443→443)
  → Traefik (ingress del cluster) → Service correspondiente,
  enrutado por el header `Host`.

Los proxy hosts de NPM viven en /DATA/AppData/nginxproxymanager/data/database.sqlite (tabla proxy_host) y NPM regenera solo el .conf correspondiente en data/nginx/proxy_host/<id>.conf cuando cambia la fila en la base — no hace falta editar el .conf a mano, y si se edita a mano puede sobreescribirse en cualquier cambio posterior desde la UI/DB.

Patrón de diagnóstico: si un subdominio *.cruzcloud.net responde 500 Internal Server Error con header Server: openresty cuando se accede públicamente, pero el mismo path funciona bien contra el ingress interno del cluster (curl -H "Host: <subdominio>" http://<IP-del-nodo>/...), el problema no está en el cluster ni en la app — está en el proxy host de NPM para ese subdominio. Revisar forward_host/forward_port en la tabla proxy_host y compararlos contra un host que sí funcione (ej. shop.cruzcloud.net, commerce.cruzcloud.net, ambos con forward_host='192.168.68.61', forward_port=90).

Nota de arquitectura: Medusa v2 Store API requiere region_id explícito

Estado: no es un issue, es un requisito de la API que causó un incidente real por no ser conocido — ver docs/playbooks/incidente-medusa-precios-region-id-2026-08.md.

El endpoint /store/products de Medusa v2 (validado por StoreGetProductsParams, .strict()) no acepta currency_code ni country_code como parámetros para resolver el contexto de precio (calculated_price). El único parámetro válido para ese fin es region_id, apuntando a una región existente y configurada vía Admin API. Cualquier integración nueva contra el Store API de Medusa v2 que necesite precios calculados debe pasar region_id explícito — no asumir que currency_code o country_code son suficientes, aunque lo sean en Medusa v1 o en otras APIs de e-commerce.