k8s-manifests/CLAUDE.md

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:

SELECT name, count FROM workflow_statistics WHERE workflowId='<id>';
-- 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.

kubectl -n argocd patch app <app> --type json \
  -p '[{"op":"remove","path":"/spec/syncPolicy/automated"}]'
# ... trabajo ...
kubectl -n argocd patch app <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.