feat(docs-portal): pipeline GitOps y manifiestos K8s para el portal MkDocs

Agrega lo que faltaba para desplegar workloads/docs-portal/ (ya existente sin commitear): deployment/service/ingress + kustomization siguiendo el patrón de workloads/nginx, Applications de workload y gobernanza separadas, y el workflow de Gitea Actions (build+push a Gitea Registry, bump de versión en el manifiesto) siguiendo el mismo patrón que build.yaml/build-medusa.yaml.
2026-08-13 21:08:04 -05:00
parent 11737ba109
commit fb5cf8bc98
27 changed files with 1328 additions and 0 deletions
@@ -0,0 +1,44 @@
+# ADR 0003 — Por qué HTTP/2 sobre QUIC para el transporte del túnel de Cloudflare
+
+**Estado:** aceptada
+**Fecha:** 2026-08 (ventana del incidente documentado abajo)
+
+> **TODO (fase 2+):** expandir la narrativa; el contexto/decisión ya
+> están fundamentados en un incidente real, solo falta pulir la
+> redacción y agregar los datos de validación completos.
+
+## Contexto
+
+`cloudflared` (el proceso que abre el túnel hacia Cloudflare) usaba
+QUIC (UDP) como protocolo de transporte por defecto para sus 4
+conexiones hacia el edge de Cloudflare. Una de esas conexiones sufría
+fallos recurrentes de "control stream" cada 2-6 minutos, causando
+`504 Gateway Timeout` intermitentes en **todos** los subdominios detrás
+del túnel (Gitea, Argo CD, la tienda, etc.), no solo uno.
+
+Diagnóstico completo en el
+[playbook del incidente](../playbooks/incidente-504-gitea-tunnel.md).
+
+## Opciones consideradas
+
+| Opción | A favor | En contra |
+|---|---|---|
+| QUIC (default) | Menor latencia teórica, multiplexing sin head-of-line blocking | Sensible a NAT/firewall doméstico; causaba el 504 intermitente real |
+| HTTP/2 sobre TCP | Estable en redes domésticas con NAT agresivo | Ligeramente más latencia teórica que QUIC |
+
+## Decisión
+
+Forzar `TUNNEL_TRANSPORT_PROTOCOL=http2` en la configuración del
+contenedor `cloudflared`, en vez de dejar el default (QUIC/UDP).
+
+## Consecuencias
+
+- Se eliminaron los `504` intermitentes — validado con curl en loop
+  contra `gitea.cruzcloud.net`: ~0.37–0.4s de latencia estable por
+  24+ minutos sin un solo error.
+- Se renuncia a la ventaja teórica de latencia de QUIC, aceptable en un
+  lab doméstico donde la estabilidad importa más que microsegundos.
+- Si en el futuro cambia el hardware de red (router, NAT) podría valer
+  la pena revisar si QUIC vuelve a ser viable — no hay una razón de
+  fondo para excluirlo para siempre, solo evidencia de que falló en
+  esta red concreta.