From 6454b56fe3b1801014f263092b53cc698d08999c Mon Sep 17 00:00:00 2001 From: chemavx Date: Thu, 30 Jul 2026 21:03:59 +0000 Subject: [PATCH] CLAUDE.md: las trampas que enganan al mirarlas Este directorio es el WorkingDirectory de hermes-bot, o sea el sitio donde un agente lee el contexto del cluster, y no tenia ninguno. Se ha notado hoy: tras poner EXECUTIONS_DATA_SAVE_ON_SUCCESS=none en n8n, las ejecuciones exitosas quedan como status='running' con deletedAt puesta hasta que pasa el barrido. Hermes las vio, las tomo por ejecuciones colgadas y se gasto un turno entero de quince minutos diagnosticando una averia inexistente en un workflow que corria clavado cada cinco minutos. Solo van aqui las cosas que enganan: lo que parece roto y no lo esta, y lo que parece inofensivo y no lo es. El resto sigue en el skill k8s-infra. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3612b3c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,85 @@ +# Notas para agentes que trabajan en este cluster + +Este es el directorio de trabajo de **Hermes** (el agente de Telegram) y de +cualquier sesión de Claude Code sobre el homelab. Aquí van solo las cosas que +**engañan al mirarlas**: lo que parece una avería y no lo es, y lo que parece +inofensivo y no lo es. Lo demás está en el skill `k8s-infra`. + +## n8n: las ejecuciones «running» que nunca terminan NO están colgadas + +Desde el **2026-07-30** el deployment lleva `EXECUTIONS_DATA_SAVE_ON_SUCCESS=none`. +Cuando un workflow sale **bien**, n8n crea igualmente la fila en +`execution_entity`, le pone `deletedAt` al instante y **no actualiza el estado**, +porque la va a tirar. El barrido duro se las lleva cada ~15 min. + +O sea que `SELECT ... FROM execution_entity` enseña filas con +`status='running'` y `stoppedAt=NULL` que son **ejecuciones exitosas ya +borradas**. No hay nada que arreglar. Ya provocó un diagnóstico en falso el +mismo día que se puso. + +Para saber si un workflow corre de verdad, mirar **`workflow_statistics`**: + +```sql +SELECT name, count FROM workflow_statistics WHERE workflowId=''; +-- production_success sube en cada vuelta aunque la ejecución no se guarde +``` + +Sale también en `deletedAt IS NOT NULL`. Y ojo: `startedAt` y `deletedAt` no +llevan el mismo huso, así que restarlas no significa nada. + +## n8n: lo que se ejecuta es la versión PUBLICADA, no el borrador + +`workflow_entity.nodes` es el **borrador**. Producción usa la versión de +`workflow_history` apuntada por `workflow_entity.activeVersionId`. Editar +`nodes` a mano y reiniciar **no cambia nada y no da ningún error**. La API +pública (`PUT /api/v1/workflows/{id}`) sí publica; parcheando SQLite hay que +escribir en las dos tablas. + +Diagnóstico rápido: comparar las dos columnas. Si difieren, lo que corre no es +lo que estás leyendo. + +## Antes de tocar una BD de un pod: desarmar ArgoCD + +Casi todo está bajo Applications con `automated{selfHeal,prune}`. Un +`kubectl scale --replicas=0` para hacer un `VACUUM` se revierte solo a mitad. + +```sh +kubectl -n argocd patch app --type json \ + -p '[{"op":"remove","path":"/spec/syncPolicy/automated"}]' +# ... trabajo ... +kubectl -n argocd patch app --type merge \ + -p '{"spec":{"syncPolicy":{"automated":{"prune":true,"selfHeal":true}}}}' +``` + +Rearmarlo al final levanta el pod y aplica la config nueva de una vez. + +## ArgoCD: una Application de directorio se traga los `.json` + +`path: n8n` incluye `*.yaml`, `*.yml` **y `*.json`** como manifiestos. Un JSON +que no sea un objeto de Kubernetes deja la app en `ComparisonError` («Object +'Kind' is missing»). Por eso `application-n8n.yaml` tiene +`directory.exclude: "workflow-*.json"`. Los `.md` no se parsean: este fichero es +seguro. + +## El auto-reinicio de Uptime Kuma sí funciona (desde 2026-07-30) y va cerrado + +Kuma cae → notificación «n8n Auto-Restart» → webhook público de n8n → PATCH del +`restartedAt`. Antes no reiniciaba nada (sin RBAC: 403), y sus «éxitos» eran el +aviso de FALLO enviándose bien. + +- La SA es `n8n-restarter`, con **un RoleBinding por namespace** (ver + `n8n/rbac-restarter.yaml`). Si añades un servicio al `SERVICE_MAP` del + workflow, hace falta también su RoleBinding o dará 403. +- La clave del mapa es el **nombre exacto del monitor en Kuma**. Renombrarlo + allí lo desconecta en silencio. +- El webhook exige la cabecera `X-Kuma-Token` (secret `n8n-kuma-webhook`, fuera + de git). Sin secreto configurado la comprobación se salta a propósito, para + que un despiste no te deje sin avisos. +- Para apps bajo ArgoCD, el `restartedAt` se **revierte** tras el reinicio. El + pod sí se reinicia; la anotación no queda. No es un fallo. + +## Un workflow que termina en verde no dice que haya hecho su trabajo + +Vale para n8n y para cualquier automatismo de aquí: comprobar el **efecto** +(que el `restartedAt` cambió, que el pod es nuevo, que el fichero está), no el +código de salida ni el contador de éxitos.