From 0052dfa1da0524ec922c911149f031f2dac61e7c Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Tue, 25 Aug 2026 23:11:10 -0500 Subject: [PATCH 1/9] =?UTF-8?q?Documentar=20lab-agent:=20lista=20blanca,?= =?UTF-8?q?=20dise=C3=B1o=20de=20seguridad=20y=20prueba=20e2e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agrega docs/arquitectura/agente-monitoreo.md como referencia técnica y documento de gobernanza del wrapper headless de diagnóstico/corrección (scripts/lab-agent). Cubre la lista blanca de acciones automáticas aprobada, por qué Claude corre con --allowedTools "" en vez de un Bash tool con prefijo (coincidencia por prefijo permite inyección de comandos, confirmado en vivo), el rediseño de autenticación a login de suscripción en vez de API key, y la evidencia completa de la prueba end-to-end del 2026-08-26 (DRY_RUN, ejecución real, rate limit/bloqueo, 2 bugs encontrados y corregidos). --- .../docs/arquitectura/agente-monitoreo.md | 191 ++++++++++++++++++ workloads/docs-portal/mkdocs.yml | 1 + 2 files changed, 192 insertions(+) create mode 100644 workloads/docs-portal/docs/arquitectura/agente-monitoreo.md diff --git a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md new file mode 100644 index 0000000..dc23d10 --- /dev/null +++ b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md @@ -0,0 +1,191 @@ +# Agente de diagnóstico/corrección (lab-agent) + +Wrapper headless (`scripts/lab-agent/lab-agent.sh`) que corre `claude -p` +periódicamente para diagnosticar el estado del lab y, solo para un +conjunto explícito y aprobado de recursos, ejecutar una acción +correctiva de bajo riesgo. Este documento es tanto referencia técnica +como decisión de gobernanza — la lista blanca de abajo es lo que +autoriza al agente a actuar sin intervención humana, y debe poder +auditarse. + +Estado: **script y prueba end-to-end validados en vivo (2026-08-26)**. +El timer de systemd (automatización continua) **todavía no está +activo** — pendiente de decisión explícita para habilitarlo. + +## Lista blanca de acciones correctivas automáticas + +Aprobada 2026-08-25, antes de escribir una sola línea de código. + +### 1. `kubectl rollout restart deployment/` + +| Condición | Valor | +|---|---| +| Trigger | Deployment con `readyReplicas < replicas` o condición `Available=False` durante **≥10 minutos consecutivos** | +| Namespace elegible | `ecommerce` (todos los deployments detectados ahí en el momento de la corrida) | +| Excepción | `medusa-deploy` — el deployment real de "commerce-backend" en la terminología de `CLAUDE.md` (confirmado en vivo 2026-08-25: no existe un deployment llamado literalmente `commerce-backend`) — solo elegible si además la hora **local** del host está entre **00:00–06:00** | +| Namespaces excluidos siempre | `argocd`, `kube-system`, cualquier otro namespace de plataforma | + +### 2. `docker restart ` + +| Condición | Valor | +|---|---| +| Contenedores elegibles | **Únicamente `gitea-runner`** | +| Trigger | Contenedor no está en estado `running` durante ≥10 min, **o** la API de Gitea Actions reporta un run en estado `running` atascado por más de 10 min sin terminar (señal del incidente de runner zombie del 2026-08-16) | +| Degradación segura | Si no hay `GITEA_TOKEN_FILE` configurado o la API falla, esa señal se omite — nunca dispara una acción sobre una lectura no verificada, solo queda la señal de "contenedor caído" | +| Excluidos siempre | `gitea`, `nginxproxymanager`, `cloudflared` | + +### 3. Fuera de alcance automático — SIEMPRE (solo diagnóstico + notificación) + +- Borrar cualquier recurso, escalar réplicas, tocar `ConfigMap`/`Secret`/configuración. +- Reiniciar `gitea`, `nginxproxymanager`, `cloudflared`. +- Cualquier acción sobre `medusa-deploy` fuera de la ventana 00:00–06:00. +- Cualquier namespace/deployment no detectado explícitamente en `ecommerce`. + +### 4. Límites obligatorios + +- **Rate limit:** máx. 1 acción correctiva por recurso cada 30 min. +- **Sin reintento silencioso:** tras un primer intento cuyo problema no + se resuelve, el recurso queda `blocked` — solo notificación, hasta + que un humano limpie la entrada en `state.json` o el recurso se + recupere solo. +- **Logging completo:** cada decisión (actúe o no) se registra en + `actions.jsonl` con timestamp, recurso, decisión, resultado y motivo. +- **Notificación siempre:** toda acción correctiva o anomalía dispara + notificación — nunca es silenciosa. + +## Diseño de seguridad: por qué Claude nunca ejecuta comandos + +`claude -p` se invoca con `--allowedTools ""` (cero herramientas) y +`--json-schema`, así que el modelo **nunca** ejecuta un comando — +solo devuelve una decisión estructurada +(`{"actions":[{"resource","decision","reason"}], "summary"}`). El +script bash es el único que ejecuta `kubectl`/`docker`, y solo después +de revalidar la decisión contra su propio cálculo de elegibilidad — +nunca confía en el JSON de Claude por sí solo. + +Se descartó dar a Claude un `Bash` tool con un patrón tipo +`Bash(kubectl rollout restart deployment/medusa-deploy -n ecommerce)` +porque se comprobó en vivo (2026-08-25) que `--allowedTools` hace +**coincidencia por prefijo, no exacta**: un patrón `Bash(echo pintest)` +también permite ejecutar `echo pintest && echo INJECTED` o +`echo pintest; rm -rf /`. Para un comando root-capaz eso no es un +límite seguro. Con `--allowedTools ""`, el peor caso posible es que +Claude proponga una decisión incorrecta en el JSON — y el wrapper la +rechaza si el recurso no está en su propia lista de elegibles. + +El prompt también advierte contra prompt injection: los datos de +diagnóstico (estado de pods, logs) podrían contener texto arbitrario +si algo en el cluster está comprometido, e instruye a Claude a ignorar +cualquier instrucción incrustada ahí. + +## Autenticación: login de suscripción, no API key + +`ANTHROPIC_API_KEY_FILE` queda vacío por defecto — `claude -p` usa el +login de suscripción ya activo del usuario que corre el script +(`~/.claude/.credentials.json`), el mismo que usa una sesión +interactiva normal. Esta decisión se tomó en vivo (2026-08-26) al +confirmar que no había una API key real disponible; el diseño original +pedía un secreto root-only para la API key, pero se simplificó porque: + +1. No hacía falta una API key aparte — la suscripción ya cubre esto. +2. Elimina la necesidad de crear secretos root-only vía `sudo` (que + además está bloqueado para una sesión de Claude Code interactiva + por diseño — ver `feedback_scoped_root_access_pattern` en memoria + del proyecto). + +**Consecuencia directa:** el servicio systemd (cuando se active) debe +correr como usuario `devops`, no como `root` — root no tiene acceso a +ese login. `CLAUDE_BIN`/`KUBECTL_BIN` apuntan por ruta absoluta a +`/DATA/AppData/home-devops/.local/bin/` porque ese directorio no está +en el `PATH` de root ni de systemd (confirmado en vivo: `sudo which +claude` no lo encuentra). + +El único secreto que queda es `GITEA_TOKEN_FILE` (token de Gitea +Actions, opcional, scope lectura), dueño `devops`, `600` — sin sudo. + +## Prueba end-to-end (2026-08-26) + +Ejecutada contra el cluster real, rama `fix/lab-agent-diagnostico-headless`. +Umbral bajado a 2 minutos solo para esta prueba (`UNHEALTHY_THRESHOLD_MIN`, +valor real en producción: 10). Canario desechable: `deployment/test-agent-canary` +en `ecommerce`, imagen `busybox:stable` con `command: ["sh","-c","exit 1"]` +— garantiza `CrashLoopBackOff` predecible, sin relación con +`catalog-api-deploy`/`frontend-deploy`/`medusa-deploy`. + +### Bugs encontrados y corregidos durante la prueba + +1. **Subshell perdía el resultado de la acción.** `execute_corrective_action` + se invocaba como `result="$(execute_corrective_action "$resource")"` — + al correr en un subshell, las variables `LAST_ACTION_CMD`/`STDOUT`/`STDERR` + nunca volvían al script principal → crash con `unbound variable`. + Corregido: la función ahora devuelve éxito/fallo por exit status, invocada + directamente (sin `$(...)`) para que sus variables globales persistan. +2. **DRY_RUN contaminaba el estado real.** El wrapper marcaba `blocked=true` + en `state.json` incluso en modo simulación, lo que habría bloqueado + incorrectamente una corrida real posterior sobre el mismo recurso. + Corregido: la actualización de `state.json` (bloqueo/rate-limit) solo + ocurre fuera de `DRY_RUN`. +3. **`claude`/`kubectl` fuera del PATH de root/systemd** — ver sección de + autenticación arriba. Corregido con `CLAUDE_BIN`/`KUBECTL_BIN` por ruta + absoluta. + +### Evidencia por paso + +**DRY_RUN (elegibilidad + decisión, sin tocar el cluster):** + +- 1ª corrida (recién detectado): `elegibilidad=not_eligible:bajo_umbral(0m<2m)` + → Claude devolvió `notify_only` para los 5 recursos. +- 2ª corrida (>2 min después): `elegibilidad=eligible` para + `test-agent-canary` → Claude devolvió `decision:"restart"` solo para + ese recurso, `notify_only` para los otros 4 (sanos). +- Log: `ACCIÓN EJECUTADA: kubectl -n ecommerce rollout restart + deployment/test-agent-canary -> OK`, pero verificado en el cluster real + que **no hubo restart** (sin anotación `restartedAt`, mismo pod, misma + edad). `actions.jsonl` registra `"dry_run": true`. + +**Ejecución real (`--live`):** + +- Misma decisión de Claude (`restart` para el canario, `notify_only` para + el resto). +- Verificado en el cluster: nueva anotación + `kubectl.kubernetes.io/restartedAt` en el deployment, evento + `ScalingReplicaSet` de un ReplicaSet **nuevo**, pod nuevo en otro nodo. +- `actions.jsonl`: `"result": "success", "dry_run": false`. +- `state.json`: `last_action_at` seteado, `blocked: true`. + +**Rate limit / sin reintento silencioso:** + +- El canario (siempre crashea por diseño) volvió a estar unhealthy sin + intervención extra. +- Corrida siguiente: `elegibilidad=not_eligible:blocked_tras_intento_previo_sin_recuperacion`. +- Claude devolvió `notify_only` para **todos** los recursos, incluido el + canario — ningún segundo restart propuesto ni ejecutado. +- `state.json` sin cambios (mismo `last_action_at` que la corrida real + anterior) — confirma que no hubo reintento. +- Notificación real entregada vía ntfy.sh, confirmada leyendo el propio + historial del topic (no solo el log del script). + +**Limpieza:** `deployment/test-agent-canary` eliminado, entrada +correspondiente en `state.json` borrada. Los logs de la prueba +(`actions.jsonl`, `run-*.log`) se conservan como evidencia auditable — +no se purgaron. + +## Notificaciones + +Canal: [ntfy](https://ntfy.sh) — sin sistema de notificación previo en +el lab, se eligió la opción sin infraestructura nueva (tópico público +de ntfy.sh, nombre privado difícil de adivinar) para validar la prueba +end-to-end sin bloquear en instalar y exponer un contenedor propio. +Migrar a un ntfy self-hosted (mismo patrón que gitea/nginxproxymanager/ +cloudflared) es un cambio de una sola variable (`NTFY_URL`) cuando se +decida. + +## Pendiente antes de activar el timer en continuo + +- **Confirmación explícita del propietario del lab** para habilitar el + timer de systemd (Paso 4 original) — no se activa automáticamente + solo por haber pasado la prueba end-to-end. +- Unidad systemd corriendo como `devops` (no root), con límites de + CPU/memoria. +- Opcional: `GITEA_TOKEN_FILE` para activar la señal de "runner + atascado" vía API de Gitea Actions (hoy se omite, degradación segura). diff --git a/workloads/docs-portal/mkdocs.yml b/workloads/docs-portal/mkdocs.yml index 11fbcc0..0b3a1ce 100644 --- a/workloads/docs-portal/mkdocs.yml +++ b/workloads/docs-portal/mkdocs.yml @@ -84,6 +84,7 @@ nav: - Visión general: arquitectura/vision-general.md - Red y exposición: arquitectura/red-y-exposicion.md - Flujo GitOps: arquitectura/gitops-flujo.md + - Agente de monitoreo: arquitectura/agente-monitoreo.md - Glosario: arquitectura/glosario.md - Decisiones (ADRs): - "0001 · Por qué k3d": decisiones/0001-por-que-k3d.md From 680f3ba068e8e21b255616a2fc4c3c684b6b0384 Mon Sep 17 00:00:00 2001 From: gitea-actions Date: Wed, 26 Aug 2026 04:29:35 +0000 Subject: [PATCH 2/9] chore(gitops): deploy Docs Portal v1.0.161 [skip ci] --- workloads/docs-portal/patches/deployment.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workloads/docs-portal/patches/deployment.yaml b/workloads/docs-portal/patches/deployment.yaml index 024606c..1725876 100644 --- a/workloads/docs-portal/patches/deployment.yaml +++ b/workloads/docs-portal/patches/deployment.yaml @@ -25,7 +25,7 @@ spec: runAsNonRoot: false containers: - name: app - image: gitea.cruzcloud.net/devops/docs-portal:v1.0.159 + image: gitea.cruzcloud.net/devops/docs-portal:v1.0.161 # El base saca TODAS las capabilities. Probado en vivo y # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al From e493f7d39ea2609210f5029b64e346f3dfee0ca7 Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Wed, 26 Aug 2026 00:01:08 -0500 Subject: [PATCH 3/9] Documentar cambio a Telegram, pausa nocturna y costo estimado MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Actualiza docs/arquitectura/agente-monitoreo.md: canal de notificación cambiado de ntfy a Telegram Bot API (con la evidencia de la prueba de entrega), horario activo 06:00-23:00 con su justificación de costo, la tensión sin resolver con la ventana de medusa-deploy (00:00-06:00, no se solapa con el horario activo del agente), y la estimación de costo mensual (~US$60-65, basada en las corridas reales medidas). --- .../docs/arquitectura/agente-monitoreo.md | 81 ++++++++++++++++--- 1 file changed, 70 insertions(+), 11 deletions(-) diff --git a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md index dc23d10..45b5fe3 100644 --- a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md +++ b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md @@ -172,20 +172,79 @@ no se purgaron. ## Notificaciones -Canal: [ntfy](https://ntfy.sh) — sin sistema de notificación previo en -el lab, se eligió la opción sin infraestructura nueva (tópico público -de ntfy.sh, nombre privado difícil de adivinar) para validar la prueba -end-to-end sin bloquear en instalar y exponer un contenedor propio. -Migrar a un ntfy self-hosted (mismo patrón que gitea/nginxproxymanager/ -cloudflared) es un cambio de una sola variable (`NTFY_URL`) cuando se -decida. +**Canal: Telegram Bot API** (reemplaza a ntfy, cambiado 2026-08-26 por +preferencia — no por costo, ver sección de costo abajo). Bot creado +manualmente vía [@BotFather](https://t.me/BotFather); el token vive en +`TELEGRAM_BOT_TOKEN_FILE` (dueño `devops`, `600` — **no** root-only, +mismo criterio que `GITEA_TOKEN_FILE`: el servicio corre como `devops` +por el login de suscripción, un archivo `root:root` le sería ilegible). +`TELEGRAM_CHAT_ID` no es secreto, va directo en `lab-agent.env`. + +El mensaje se manda como texto plano, sin `parse_mode`: el motivo que +devuelve Claude es texto libre y puede traer `_`, `*`, `[`, `]` — con +Markdown/MarkdownV2 esos caracteres rompen el parser de Telegram (`400 +Bad Request`) si no se escapan con cuidado. Se prioriza entrega +confiable sobre formato. + +**Validado en vivo 2026-08-26** con el mismo código que usa +`notify_send()` (lectura del token, `sendMessage` vía `curl +--data-urlencode`, formato `[title]\nmessage`): entrega confirmada +(`"ok":true`) y contenido recibido tal cual en Telegram. Gotcha +encontrado durante la prueba: el primer intento falló con `400 chat not +found` porque el `chat_id` pegado correspondía a otro bot — el `chat_id` +de un usuario es el mismo across bots, pero Telegram igual devuelve +`chat not found` si *ese bot puntual* nunca recibió un mensaje de esa +persona. Se resolvió confirmando el `chat_id` real vía `getUpdates` del +bot correcto. + +## Horario activo y costo + +**Pausa nocturna (`ACTIVE_HOURS_START`/`END`, hora local del host):** +activo `06:00`–`23:00`, pausado `23:00`–`06:00`. El script chequea esto +como lo primero que hace tras inicializar logging — si está fuera de +horario, sale **antes** de tocar `kubectl`/`docker`/`curl` o invocar +`claude -p`, así que la pausa ahorra el costo completo de la corrida, +no solo la notificación. El timer de systemd además solo dispara dentro +de esa ventana (`OnCalendar=*-*-* 06..22:00/15:00`) — la doble +verificación es deliberada: si alguien edita la unidad de systemd sin +tocar `lab-agent.env` (o corre el script a mano), el chequeo interno +sigue protegiendo. + +**Tensión sin resolver con la ventana de `medusa-deploy`:** la ventana +de auto-restart para `medusa-deploy` (`COMMERCE_BACKEND_WINDOW_*`, +`00:00`–`06:00`) **no se solapa** con el horario activo del agente +(`06:00`–`23:00`). Esto significa que, en la práctica, `medusa-deploy` +nunca es candidato real a auto-restart: la única ventana en la que la +política lo permitiría es exactamente cuando el agente está pausado y +ni siquiera corre. La regla sigue viva en el código (por si el horario +activo cambia más adelante) pero hoy es efectivamente inalcanzable. +Pendiente de decisión: mover la ventana de `medusa-deploy` a que caiga +dentro del horario activo, o aceptar que ese recurso queda cubierto +solo por diagnóstico/notificación manual. + +**Estimación de costo mensual:** + +| | | +|---|---| +| Corridas/día (17h activas ÷ 15 min) | 68 | +| Costo por corrida (medido en la prueba e2e, Sonnet) | ~US$0.018–0.045 con cache tibia; ~US$0.12 en frío (primera corrida del día, tras 7h de pausa el cache de prompt ya expiró) | +| Estimado diario (1 corrida fría + 67 tibias) | ~US$2.10 | +| **Estimado mensual (× 30 días)** | **~US$60–65** (rango US$35–90 según variación real de cache) | + +Basado en solo ~7 corridas reales medidas durante la prueba — no es un +promedio estadísticamente robusto, es una primera estimación para +decidir si el timer se activa. Revisar el costo real después de la +primera semana en producción y ajustar frecuencia/modelo si hace falta. ## Pendiente antes de activar el timer en continuo - **Confirmación explícita del propietario del lab** para habilitar el - timer de systemd (Paso 4 original) — no se activa automáticamente - solo por haber pasado la prueba end-to-end. -- Unidad systemd corriendo como `devops` (no root), con límites de - CPU/memoria. + timer de systemd — no se activa automáticamente solo por haber + pasado la prueba end-to-end ni por tener el costo estimado. +- Unidad systemd de usuario (`systemctl --user`, corre como `devops`, + no `root`), con límites de CPU/memoria (`CPUQuota`, `MemoryMax`). + Requiere `loginctl enable-linger devops` (una vez, con sudo) para que + seguir corriendo sin sesión interactiva activa. - Opcional: `GITEA_TOKEN_FILE` para activar la señal de "runner atascado" vía API de Gitea Actions (hoy se omite, degradación segura). +- Decidir la tensión con la ventana de `medusa-deploy` (ver arriba). From 7c6f3d9c270304c1105413fb88a1963811464dac Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Wed, 26 Aug 2026 00:21:28 -0500 Subject: [PATCH 4/9] =?UTF-8?q?Documentar=20notificaci=C3=B3n=20silenciosa?= =?UTF-8?q?,=20hilos=20y=20adjunto=20de=20log=20en=20Telegram?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Actualiza la sección de Notificaciones: formato con íconos por tipo de evento, log completo adjunto como documento, nivel "info" silencioso (disable_notification), y respuestas en hilo cuando un recurso accionado se recupera solo -- con la limitación conocida de que un desbloqueo manual (borrando la entrada de state.json) pierde el message_id y no queda threadeado. Validado en vivo con el canario. --- .../docs/arquitectura/agente-monitoreo.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md index 45b5fe3..fc59a0d 100644 --- a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md +++ b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md @@ -197,6 +197,28 @@ de un usuario es el mismo across bots, pero Telegram igual devuelve persona. Se resolvió confirmando el `chat_id` real vía `getUpdates` del bot correcto. +**Formato:** cada notificación lleva un ícono según su naturaleza +(✅ acción ok, 🛑 acción falló/rechazada, 🚨 alerta de seguridad, +❌ error operativo, 👀 solo diagnóstico) y el log completo de esa +corrida va adjunto como documento (`sendDocument`), no solo como ruta — +útil para revisar desde el celular sin acceso a shell. + +**Notificación silenciosa y respuestas en hilo (2026-08-26):** el nivel +`info` (nada elegible, todo diagnóstico rutinario) se manda con +`disable_notification=true` — no interrumpe; acciones, fallas y alertas +de seguridad sí suenan. Cuando se ejecuta una acción correctiva, el +`message_id` de Telegram queda guardado por recurso en `state.json` +(`telegram_message_id`); si ese recurso se recupera solo en una corrida +posterior, se manda un aviso silencioso como **respuesta** (hilo) al +mensaje original antes de limpiar el estado — agrupa visualmente todo +un incidente. Limitación conocida: si un humano desbloquea el recurso a +mano borrando su entrada de `state.json` (ver más abajo), el +`message_id` se pierde con esa entrada, así que ese caso puntual no +queda threadeado — solo el "se recuperó solo" está cubierto hoy. +Validado en vivo con el canario: acción real → `message_id` capturado → +canario parcheado a una imagen sana → reply en hilo confirmado, +silencioso, al recuperarse. + ## Horario activo y costo **Pausa nocturna (`ACTIVE_HOURS_START`/`END`, hora local del host):** From 10e2db564370a9955348a50f753d943b1d7673e0 Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Wed, 26 Aug 2026 00:25:53 -0500 Subject: [PATCH 5/9] =?UTF-8?q?Documentar=20activaci=C3=B3n=20del=20timer?= =?UTF-8?q?=20y=20el=20gotcha=20de=20HOME=3D=20en=20systemd=20--user?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Timer activo desde 2026-08-26. Documenta el hallazgo en vivo: el manager de systemd --user de devops arranca con HOME=/DATA (el de /etc/passwd), no con el override de /etc/profile.d/zz-devops-home.sh que solo aplica a shells interactivas -- sin Environment=HOME=... en la unidad, claude -p habría fallado la autenticación en cada corrida del timer, silenciosamente. Se detectó y corrigió antes de activar, corriendo el servicio manualmente vía systemctl --user start con el entorno real como último paso de validación. --- .../docs/arquitectura/agente-monitoreo.md | 46 ++++++++++++++----- 1 file changed, 34 insertions(+), 12 deletions(-) diff --git a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md index fc59a0d..4324d12 100644 --- a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md +++ b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md @@ -8,9 +8,10 @@ como decisión de gobernanza — la lista blanca de abajo es lo que autoriza al agente a actuar sin intervención humana, y debe poder auditarse. -Estado: **script y prueba end-to-end validados en vivo (2026-08-26)**. -El timer de systemd (automatización continua) **todavía no está -activo** — pendiente de decisión explícita para habilitarlo. +Estado: **timer de systemd ACTIVO desde 2026-08-26** (`lab-agent.timer`, +usuario `devops`, cada 15 min entre 06:00–23:00 hora local). Script, +Telegram y las unidades systemd, todo validado en vivo antes de +activar. ## Lista blanca de acciones correctivas automáticas @@ -258,15 +259,36 @@ promedio estadísticamente robusto, es una primera estimación para decidir si el timer se activa. Revisar el costo real después de la primera semana en producción y ajustar frecuencia/modelo si hace falta. -## Pendiente antes de activar el timer en continuo +## Activación del timer (2026-08-26) + +Habilitado tras confirmación explícita del propietario del lab, viendo +antes el costo mensual estimado. Unidad de usuario (`systemctl --user`, +corre como `devops`, no `root`), con límites de CPU/memoria (`CPUQuota`, +`MemoryMax`) — instalada en `/DATA/.config/systemd/user/`, no en el +`~/.config/...` de una shell interactiva. + +**Gotcha encontrado y corregido en vivo:** el manager de `systemd +--user` de `devops` arranca con `HOME=/DATA` (el valor de +`/etc/passwd`), no `/DATA/AppData/home-devops` — ese override solo se +aplica al abrir una shell interactiva vía +`/etc/profile.d/zz-devops-home.sh`, que el manager de systemd nunca +carga. Sin corregirlo, `claude -p` habría buscado +`~/.claude/.credentials.json` en `/DATA/.claude/` (no existe) y la +autenticación habría fallado en cada corrida del timer, silenciosamente, +hasta la primera vez que alguien mirara el log. `lab-agent.service` +fija `Environment=HOME=/DATA/AppData/home-devops` explícitamente para +evitarlo. Se detectó y corrigió *antes* de habilitar el timer, corriendo +el servicio manualmente vía `systemctl --user start` con el entorno +real (no desde una shell interactiva) como último paso de validación. + +También requirió `sudo loginctl enable-linger devops` (una vez) — sin +eso, `systemctl --user` ni siquiera conecta (no hay `/run/user/` +sin una sesión de login o linger activo). + +**Pendiente, no bloqueante:** -- **Confirmación explícita del propietario del lab** para habilitar el - timer de systemd — no se activa automáticamente solo por haber - pasado la prueba end-to-end ni por tener el costo estimado. -- Unidad systemd de usuario (`systemctl --user`, corre como `devops`, - no `root`), con límites de CPU/memoria (`CPUQuota`, `MemoryMax`). - Requiere `loginctl enable-linger devops` (una vez, con sudo) para que - seguir corriendo sin sesión interactiva activa. - Opcional: `GITEA_TOKEN_FILE` para activar la señal de "runner atascado" vía API de Gitea Actions (hoy se omite, degradación segura). -- Decidir la tensión con la ventana de `medusa-deploy` (ver arriba). +- Decidir la tensión con la ventana de `medusa-deploy` (ver arriba) — + sigue sin resolver, el timer se activó igual porque no bloquea el + resto de la lista blanca. From ce8c96d3eed3396b9aae8cb3d8f7b34873eb6196 Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Wed, 26 Aug 2026 00:28:01 -0500 Subject: [PATCH 6/9] Actualizar costo estimado tras bajar el timer a 60 min MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 17 corridas/día en vez de 68. Nota importante: el costo por corrida sube al perder la ventaja del cache tibio de Claude Code (~1h TTL, corridas espaciadas 60 min lo pierden casi siempre) -- el ahorro real es ~1.5-2x, no 4x. También documenta el trade-off de latencia de detección (~70 min en vez de ~25 min hasta detectar un problema). --- .../docs/arquitectura/agente-monitoreo.md | 35 +++++++++++++------ 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md index 4324d12..a298c14 100644 --- a/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md +++ b/workloads/docs-portal/docs/arquitectura/agente-monitoreo.md @@ -9,7 +9,8 @@ autoriza al agente a actuar sin intervención humana, y debe poder auditarse. Estado: **timer de systemd ACTIVO desde 2026-08-26** (`lab-agent.timer`, -usuario `devops`, cada 15 min entre 06:00–23:00 hora local). Script, +usuario `devops`, cada 60 min entre 06:00–23:00 hora local — bajado de +15 a 60 min el mismo día para reducir costo). Script, Telegram y las unidades systemd, todo validado en vivo antes de activar. @@ -228,7 +229,7 @@ como lo primero que hace tras inicializar logging — si está fuera de horario, sale **antes** de tocar `kubectl`/`docker`/`curl` o invocar `claude -p`, así que la pausa ahorra el costo completo de la corrida, no solo la notificación. El timer de systemd además solo dispara dentro -de esa ventana (`OnCalendar=*-*-* 06..22:00/15:00`) — la doble +de esa ventana (`OnCalendar=*-*-* 06..22:00:00`) — la doble verificación es deliberada: si alguien edita la unidad de systemd sin tocar `lab-agent.env` (o corre el script a mano), el chequeo interno sigue protegiendo. @@ -245,19 +246,31 @@ Pendiente de decisión: mover la ventana de `medusa-deploy` a que caiga dentro del horario activo, o aceptar que ese recurso queda cubierto solo por diagnóstico/notificación manual. -**Estimación de costo mensual:** +**Estimación de costo mensual — actualizada 2026-08-26, frecuencia +bajada de 15 a 60 min explícitamente para reducir costo:** | | | |---|---| -| Corridas/día (17h activas ÷ 15 min) | 68 | -| Costo por corrida (medido en la prueba e2e, Sonnet) | ~US$0.018–0.045 con cache tibia; ~US$0.12 en frío (primera corrida del día, tras 7h de pausa el cache de prompt ya expiró) | -| Estimado diario (1 corrida fría + 67 tibias) | ~US$2.10 | -| **Estimado mensual (× 30 días)** | **~US$60–65** (rango US$35–90 según variación real de cache) | +| Corridas/día (17h activas ÷ 60 min) | 17 | +| Costo por corrida | ~US$0.04–0.12 — **más alto por corrida que a 15 min**: el cache de prompt de Claude Code dura ~1h, y con corridas espaciadas 60 min casi siempre expira entre una y la siguiente, así que la mayoría de las corridas pagan cache "fría" en vez de "tibia" | +| **Estimado mensual (× 30 días)** | **~US$20–60** (punto medio ~US$35) | -Basado en solo ~7 corridas reales medidas durante la prueba — no es un -promedio estadísticamente robusto, es una primera estimación para -decidir si el timer se activa. Revisar el costo real después de la -primera semana en producción y ajustar frecuencia/modelo si hace falta. +Ojo con la intuición: bajar la frecuencia 4× (68→17 corridas/día) NO +baja el costo 4× — el ahorro real es más cercano a 1.5–2× frente a la +estimación anterior (~US$60–65/mes), porque cada corrida individual +sale más cara al perder la ventaja del cache tibio. Sigue siendo menos +costo total, solo que no linealmente. Basado en pocas corridas reales +medidas — revisar el costo real después de la primera semana en +producción (Telegram/Gitea Actions no cambian este número, el costo es +100% de la API de Claude). + +**Trade-off de latencia de detección:** con corridas cada 60 min en vez +de 15, un problema que recién cruza el umbral de 10 minutos puede +tardar hasta ~70 min en ser detectado y potencialmente corregido (antes +era hasta ~25 min). Aceptado a cambio del ahorro de costo — si en la +práctica resulta muy lento para algún incidente real, la frecuencia se +puede volver a subir sin tocar nada más (`OnCalendar` en +`lab-agent.timer`). ## Activación del timer (2026-08-26) From f5d09059f028ff2a5d0f4a274b9b614a5e5f25c0 Mon Sep 17 00:00:00 2001 From: gitea-actions Date: Wed, 26 Aug 2026 05:38:36 +0000 Subject: [PATCH 7/9] chore(gitops): deploy Docs Portal v1.0.162 [skip ci] --- workloads/docs-portal/patches/deployment.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workloads/docs-portal/patches/deployment.yaml b/workloads/docs-portal/patches/deployment.yaml index 1725876..f9d8314 100644 --- a/workloads/docs-portal/patches/deployment.yaml +++ b/workloads/docs-portal/patches/deployment.yaml @@ -25,7 +25,7 @@ spec: runAsNonRoot: false containers: - name: app - image: gitea.cruzcloud.net/devops/docs-portal:v1.0.161 + image: gitea.cruzcloud.net/devops/docs-portal:v1.0.162 # El base saca TODAS las capabilities. Probado en vivo y # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al From 0189f2369ecbd425aecd6fe337f1873608973139 Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Wed, 26 Aug 2026 13:29:41 -0500 Subject: [PATCH 8/9] commerce-ingress: redirect root to /app instead of 404ing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit commerce.cruzcloud.net (medusa-svc) has no route at "/" — Medusa only serves /health, /app (admin), /store, etc. lab-agent's generic public domain check flagged the resulting 404 as an anomaly every cycle even though the service is healthy. Adds a Traefik Middleware (redirectRegex) scoped to the commerce host that 301s "/" to "/app", so the DNS/routing layer owns the entry point instead of every client (including monitoring) having to know to append /app manually. Regex includes the host explicitly because the same Ingress also routes media.cruzcloud.net and shares router.middlewares at the Ingress-annotation level. --- .../ecommerce/commerce/ingress-commerce.yaml | 1 + workloads/ecommerce/commerce/kustomization.yaml | 1 + .../commerce/middleware-commerce-redirect.yaml | 16 ++++++++++++++++ 3 files changed, 18 insertions(+) create mode 100644 workloads/ecommerce/commerce/middleware-commerce-redirect.yaml diff --git a/workloads/ecommerce/commerce/ingress-commerce.yaml b/workloads/ecommerce/commerce/ingress-commerce.yaml index ad28a57..15b5918 100644 --- a/workloads/ecommerce/commerce/ingress-commerce.yaml +++ b/workloads/ecommerce/commerce/ingress-commerce.yaml @@ -4,6 +4,7 @@ metadata: name: commerce-ingress annotations: traefik.ingress.kubernetes.io/router.entrypoints: web + traefik.ingress.kubernetes.io/router.middlewares: ecommerce-commerce-redirect-app@kubernetescrd spec: ingressClassName: traefik rules: diff --git a/workloads/ecommerce/commerce/kustomization.yaml b/workloads/ecommerce/commerce/kustomization.yaml index 3ff2459..145d729 100644 --- a/workloads/ecommerce/commerce/kustomization.yaml +++ b/workloads/ecommerce/commerce/kustomization.yaml @@ -9,3 +9,4 @@ resources: - minio-bootstrap-job.yaml - medusa/ - ingress-commerce.yaml + - middleware-commerce-redirect.yaml diff --git a/workloads/ecommerce/commerce/middleware-commerce-redirect.yaml b/workloads/ecommerce/commerce/middleware-commerce-redirect.yaml new file mode 100644 index 0000000..755a7ff --- /dev/null +++ b/workloads/ecommerce/commerce/middleware-commerce-redirect.yaml @@ -0,0 +1,16 @@ +apiVersion: traefik.io/v1alpha1 +kind: Middleware +metadata: + name: commerce-redirect-app +spec: + # Redirige solo la raíz exacta de commerce.cruzcloud.net a /app (admin de + # Medusa) — el regex incluye el host a propósito: esta Middleware se + # referencia desde el mismo Ingress que también enruta media.cruzcloud.net, + # y sin el host en el regex un request a la raíz de ese otro dominio + # también matchearía (ambas rutas comparten Ingress -> mismas + # router.middlewares). Si el regex no matchea, Traefik deja pasar el + # request sin modificarlo. + redirectRegex: + regex: "^https?://commerce\\.cruzcloud\\.net/$" + replacement: "https://commerce.cruzcloud.net/app" + permanent: true From 60766ae98eeac8a988ebdc5054327c8ff7ad2174 Mon Sep 17 00:00:00 2001 From: Cristian Felipe Cruz Buitron Date: Wed, 26 Aug 2026 14:08:12 -0500 Subject: [PATCH 9/9] Desactivar temporalmente el stack de monitoring (Grafana+Prometheus) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sin uso actual, y el host está evaluando capacidad de memoria para la Etapa 2 del ADR 0006 (Meilisearch) con swap bajo presión. Se quita del app-of-apps para liberar los recursos del namespace `monitoring` (Grafana, Prometheus, Alertmanager, kube-state-metrics, prometheus-operator -- estos dos últimos venían en CrashLoopBackOff desde hace 37 días, ~8000 reinicios cada uno, conexión rechazada contra el apiserver in-cluster -- y los 3 node-exporter). Reversible: reagregar ambos archivos re-despliega el stack completo vía Helm/kustomize sin pasos manuales. Sin pérdida de datos -- el namespace monitoring no tenía ningún PVC, confirmado antes de borrar (kubectl -n monitoring get pvc -> vacío). Se agregó el finalizer resources-finalizer.argocd.argoproj.io a ambas Applications (monitoring-app, monitoring-governance) antes de este commit para que Argo CD borre en cascada los recursos desplegados al podarlas, no solo el objeto Application -- sin eso quedarían pods huérfanos corriendo sin liberar memoria. --- apps/monitoring-app.yaml | 40 ----------------------------- apps/monitoring-governance-app.yaml | 20 --------------- 2 files changed, 60 deletions(-) delete mode 100644 apps/monitoring-app.yaml delete mode 100644 apps/monitoring-governance-app.yaml diff --git a/apps/monitoring-app.yaml b/apps/monitoring-app.yaml deleted file mode 100644 index b4c3e9e..0000000 --- a/apps/monitoring-app.yaml +++ /dev/null @@ -1,40 +0,0 @@ -apiVersion: argoproj.io/v1alpha1 -kind: Application - -metadata: - name: monitoring-app - namespace: argocd - -spec: - project: default - - source: - repoURL: https://prometheus-community.github.io/helm-charts - chart: kube-prometheus-stack - targetRevision: 58.3.3 - - helm: - parameters: - - name: prometheusOperator.admissionWebhooks.patch.ttlSecondsAfterFinished - value: "60" - - valuesObject: - grafana: - ingress: - enabled: true - ingressClassName: traefik - hosts: - - grafana.cruzcloud.net - - destination: - server: https://kubernetes.default.svc - namespace: monitoring - - syncPolicy: - automated: - prune: true - selfHeal: true - - syncOptions: - - CreateNamespace=true - - ServerSideApply=true \ No newline at end of file diff --git a/apps/monitoring-governance-app.yaml b/apps/monitoring-governance-app.yaml deleted file mode 100644 index cb82773..0000000 --- a/apps/monitoring-governance-app.yaml +++ /dev/null @@ -1,20 +0,0 @@ -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: monitoring-governance - namespace: argocd -spec: - project: default - source: - repoURL: https://gitea.cruzcloud.net/devops/platform-infra.git - path: monitoring-governance - targetRevision: main - destination: - server: https://kubernetes.default.svc - namespace: monitoring - syncPolicy: - automated: - prune: true - selfHeal: true - syncOptions: - - CreateNamespace=true \ No newline at end of file