Compare commits

...
15 Commits
Author SHA1 Message Date
devops c243f02ec4 docs(adr): marcar ADR 0006 como aceptada, nota de implementación
Build and Push Docs Portal / Escaneo de Secretos (Gitleaks) (pull_request) Successful in 51s
Build and Push Docs Portal / Construir y publicar Docs Portal (pull_request) Skipped
Aprobada tras el diagnóstico de memoria del host (swap saturado
resuelto, ~500-700MiB liberados al desactivar monitoring). Agrega
nota de implementación con 3 desviaciones reales encontradas al
verificar el código fuente del plugin en el tag v1.4.1 antes de
escribir código: no hace falta subscriber propio (el plugin trae los
suyos), las rutas del plugin no devuelven facetDistribution (se
agrega una ruta Store API propia), y se conecta vía plugins: no
modules:. Ninguna cambia la decisión, solo el cómo.
2026-08-26 14:56:19 -05:00
devops 31782a2838 Merge main into fix/adr0006-motor-busqueda-facetas 2026-08-26 14:55:47 -05:00
devops 9069f165c0 Merge fix/disable-monitoring-stack into main 2026-08-26 14:08:28 -05:00
devops 60766ae98e Desactivar temporalmente el stack de monitoring (Grafana+Prometheus)
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.
2026-08-26 14:08:12 -05:00
devops 69467d5f4d Merge fix/commerce-root-redirect-app into main 2026-08-26 13:33:19 -05:00
devops 0189f2369e commerce-ingress: redirect root to /app instead of 404ing
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.
2026-08-26 13:29:41 -05:00
gitea-actions f5d09059f0 chore(gitops): deploy Docs Portal v1.0.162 [skip ci] 2026-08-26 05:38:36 +00:00
devops 56ab9d1862 Merge branch 'fix/lab-agent-telegram-horario' into main
Build and Push Docs Portal / Escaneo de Secretos (Gitleaks) (push) Successful in 40s
Build and Push Docs Portal / Construir y publicar Docs Portal (push) Successful in 8m43s
Documenta el cambio a Telegram (silencioso para info, hilos al
recuperarse, log adjunto), la pausa nocturna 06:00-23:00 con su
tensión sin resolver con la ventana de medusa-deploy, la activación
del timer de systemd (60 min, bajado de 15 para reducir costo) con el
gotcha de Environment=HOME= para systemd --user, y el costo mensual
estimado actualizado.
2026-08-26 00:29:13 -05:00
devops ce8c96d3ee Actualizar costo estimado tras bajar el timer a 60 min
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).
2026-08-26 00:28:01 -05:00
devops 10e2db5643 Documentar activación del timer y el gotcha de HOME= en systemd --user
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.
2026-08-26 00:25:53 -05:00
devops 7c6f3d9c27 Documentar notificación silenciosa, hilos y adjunto de log en Telegram
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.
2026-08-26 00:21:28 -05:00
devops e493f7d39e Documentar cambio a Telegram, pausa nocturna y costo estimado
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).
2026-08-26 00:01:08 -05:00
gitea-actions 680f3ba068 chore(gitops): deploy Docs Portal v1.0.161 [skip ci] 2026-08-26 04:29:35 +00:00
devops 5014903c51 Merge branch 'fix/lab-agent-docs-arquitectura' into main
Build and Push Docs Portal / Escaneo de Secretos (Gitleaks) (push) Successful in 3m25s
Build and Push Docs Portal / Construir y publicar Docs Portal (push) Successful in 9m42s
Documentación de gobernanza y arquitectura del agente lab-agent:
lista blanca aprobada, diseño de seguridad (--allowedTools "" en vez
de un Bash tool con patrón, por la vulnerabilidad de coincidencia por
prefijo encontrada en vivo), autenticación por login de suscripción, y
evidencia completa de la prueba end-to-end del 2026-08-26.
2026-08-25 23:16:25 -05:00
devops 0052dfa1da Documentar lab-agent: lista blanca, diseño de seguridad y prueba e2e
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).
2026-08-25 23:11:10 -05:00
9 changed files with 369 additions and 62 deletions

No files matched your search

-40
View File
@@ -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
-20
View File
@@ -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
@@ -0,0 +1,307 @@
# 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: **timer de systemd ACTIVO desde 2026-08-26** (`lab-agent.timer`,
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.
## 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/<nombre>`
| 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 <contenedor>`
| 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 (&gt;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: 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.
**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):**
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: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 — actualizada 2026-08-26, frecuencia
bajada de 15 a 60 min explícitamente para reducir costo:**
| | |
|---|---|
| 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) |
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)
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/<uid>`
sin una sesión de login o linger activo).
**Pendiente, no bloqueante:**
- 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) —
sigue sin resolver, el timer se activó igual porque no bloquea el
resto de la lista blanca.
@@ -1,6 +1,6 @@
# ADR 0006 — Motor de búsqueda y filtros facetados (Fase 5, Etapa 3) # ADR 0006 — Motor de búsqueda y filtros facetados (Fase 5, Etapa 3)
**Estado:** propuesta — pendiente de aprobación antes de Etapa 2 (implementación) **Estado:** aceptada — Etapa 2 en implementación (aprobada 2026-08-26 tras diagnóstico de memoria del host)
**Fecha:** 2026-08-25 **Fecha:** 2026-08-25
## Contexto ## Contexto
@@ -254,3 +254,44 @@ Medusa.
— no hay migración de datos que deshacer, porque Meilisearch nunca — no hay migración de datos que deshacer, porque Meilisearch nunca
es la fuente de verdad, solo una copia de solo lectura indexada es la fuente de verdad, solo una copia de solo lectura indexada
desde Medusa. desde Medusa.
## Nota de implementación (2026-08-26, antes de escribir código de Etapa 2)
Antes de tocar código se verificó el código fuente real de
`@rokmohar/medusa-plugin-meilisearch` en el tag exacto `v1.4.1`
(`github.com/rokmohar/medusa-plugin-meilisearch`), no su README
genérico ni memoria de entrenamiento — misma disciplina que ya destapó
el bug de `+categories` en `/store/products`. Aparecieron tres
desviaciones reales respecto al diseño de §4/§5 de este ADR:
1. **No se escribe un subscriber nuevo.** El plugin trae sus propios
subscribers (`meilisearch-product-upsert.ts`,
`meilisearch-category-upsert.ts`, variantes/colección/inventario),
auto-registrados al instalar el paquete — el propio README dice
*"You don't need custom subscribers anymore, you can remove them."*
Escribir `sync-search-index.ts` como describe §4 causaría doble
indexado. La escucha de `product-category.*` que pedía §4 ya viene
incluida en los subscribers del plugin.
2. **Las rutas Store API del plugin no devuelven `facetDistribution`**,
pese a que §5 asume que sí. El servicio interno
(`MeiliSearchService.search()`) sí puede pedirlo vía
`additionalOptions: { facets: [...] }`, pero las rutas
empaquetadas nunca lo piden ni lo reenvían. Se agrega una ruta
Store API propia (`src/api/store/search/route.ts`) que resuelve el
servicio del plugin desde el container y arma
`{ products, facetDistribution }`. Consecuencia positiva no
buscada: Meilisearch queda 100% `ClusterIP`-only, sin Ingress, sin
key pública ni ruta de red navegador→Meilisearch — todo pasa por
Medusa.
3. **El plugin se conecta vía un array `plugins:` nuevo en
`medusa-config.ts`**, no otra entrada en `modules:` (el único
precedente en este repo, el file-provider S3, usa `modules:`), y
usa nombres de env var propios (`MEILISEARCH_HOST`/
`MEILISEARCH_API_KEY`, leídos por el plugin) distintos del env var
del servidor Meilisearch en sí (`MEILI_MASTER_KEY`, leído por el
contenedor `getmeili/meilisearch`) — mismo valor, dos nombres de
secret.
Ninguna de las tres cambia la decisión ni sus consecuencias — cambian
el cómo, no el qué. Plan de implementación completo, fase por fase,
en la sesión que aprobó esta Etapa 2 (2026-08-26).
+1
View File
@@ -84,6 +84,7 @@ nav:
- Visión general: arquitectura/vision-general.md - Visión general: arquitectura/vision-general.md
- Red y exposición: arquitectura/red-y-exposicion.md - Red y exposición: arquitectura/red-y-exposicion.md
- Flujo GitOps: arquitectura/gitops-flujo.md - Flujo GitOps: arquitectura/gitops-flujo.md
- Agente de monitoreo: arquitectura/agente-monitoreo.md
- Glosario: arquitectura/glosario.md - Glosario: arquitectura/glosario.md
- Decisiones (ADRs): - Decisiones (ADRs):
- "0001 · Por qué k3d": decisiones/0001-por-que-k3d.md - "0001 · Por qué k3d": decisiones/0001-por-que-k3d.md
@@ -25,7 +25,7 @@ spec:
runAsNonRoot: false runAsNonRoot: false
containers: containers:
- name: app - name: app
image: gitea.cruzcloud.net/devops/docs-portal:v1.0.159 image: gitea.cruzcloud.net/devops/docs-portal:v1.0.162
# El base saca TODAS las capabilities. Probado en vivo y # El base saca TODAS las capabilities. Probado en vivo y
# revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE # revertido: con drop: ALL (aunque se agregue NET_BIND_SERVICE
# de vuelta) el propio entrypoint de nginx:1.27-alpine falla al # de vuelta) el propio entrypoint de nginx:1.27-alpine falla al
@@ -4,6 +4,7 @@ metadata:
name: commerce-ingress name: commerce-ingress
annotations: annotations:
traefik.ingress.kubernetes.io/router.entrypoints: web traefik.ingress.kubernetes.io/router.entrypoints: web
traefik.ingress.kubernetes.io/router.middlewares: ecommerce-commerce-redirect-app@kubernetescrd
spec: spec:
ingressClassName: traefik ingressClassName: traefik
rules: rules:
@@ -9,3 +9,4 @@ resources:
- minio-bootstrap-job.yaml - minio-bootstrap-job.yaml
- medusa/ - medusa/
- ingress-commerce.yaml - ingress-commerce.yaml
- 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