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,33 @@
+# ADR 0001 — Por qué k3d (y no k3s directo, minikube, o un cluster cloud)
+
+> **TODO (fase 2+):** completar contexto/opciones/consecuencias con
+> criterio real (recursos del NAS ZimaOS, necesidad de multi-nodo para
+> reproducir el blackhole de MTU documentado en `known-issues.md`,
+> costo cero vs. cluster gestionado).
+
+**Estado:** aceptada (placeholder — pendiente de redactar)
+**Fecha:** TODO
+
+## Contexto
+
+TODO
+
+## Opciones consideradas
+
+| Opción | A favor | En contra |
+|---|---|---|
+| k3d | | |
+| k3s directo (sin Docker) | | |
+| minikube | | |
+| Cluster gestionado (cloud) | | |
+
+## Decisión
+
+TODO
+
+## Consecuencias
+
+TODO — mencionar explícitamente el blackhole de red cross-node
+(MTU/PMTUD) como consecuencia real y documentada de correr multi-nodo
+sobre Docker-in-Docker sin ajuste de MTU (ver
+[playbook del crashloop de Medusa](../playbooks/incidente-crashloop-medusa.md)).
@@ -0,0 +1,30 @@
+# ADR 0002 — Por qué Argo CD (y no `kubectl apply` manual o un script de CI)
+
+> **TODO (fase 2+):** completar con el criterio real detrás de elegir
+> reconciliación continua (`selfHeal`) sobre despliegue imperativo desde
+> CI.
+
+**Estado:** aceptada (placeholder — pendiente de redactar)
+**Fecha:** TODO
+
+## Contexto
+
+TODO
+
+## Opciones consideradas
+
+| Opción | A favor | En contra |
+|---|---|---|
+| Argo CD (GitOps, pull-based) | | |
+| `kubectl apply` manual | | |
+| `kubectl apply` desde el pipeline de CI (push-based) | | |
+
+## Decisión
+
+TODO
+
+## Consecuencias
+
+TODO — mencionar el patrón App of Apps (`application.yaml` +
+`apps/*.yaml`) y cómo `selfHeal:true` cambia el modelo mental de
+"quién puede tocar el cluster".
@@ -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.
@@ -0,0 +1,31 @@
+# ADR NNNN — Título corto de la decisión
+
+> Copiar este archivo como `NNNN-titulo-corto.md` (siguiente número
+> disponible) para cada decisión arquitectónica nueva.
+
+**Estado:** propuesta | aceptada | reemplazada por ADR-XXXX
+**Fecha:** AAAA-MM-DD
+
+## Contexto
+
+¿Qué problema forzó esta decisión? ¿Qué restricciones reales existían
+(hardware del NAS, presupuesto cero, tiempo disponible, conocimiento
+previo)? Sin justificar todavía la elección — solo la situación.
+
+## Opciones consideradas
+
+| Opción | A favor | En contra |
+|---|---|---|
+| Opción A | | |
+| Opción B | | |
+| Opción C | | |
+
+## Decisión
+
+Qué se eligió, en una o dos frases.
+
+## Consecuencias
+
+- Qué se gana
+- Qué se sacrifica o queda como deuda técnica
+- Qué tendría que pasar para revertir esta decisión