message_bus/reports/0011-2026-06-07-unibus-cluster-deploy.md

# Report 0011 — Despliegue del cluster unibus de 3 nodos (magnus + homer + datardos)

- **Fecha:** 07/06/2026
- **Autor:** agente (Claude) + operador
- **Ámbito:** `projects/message_bus/apps/unibus/` (sub-repo `dataforge/unibus`) — despliegue del bus como cluster HA de 3 nodos sobre VPS OVH. Issue 0006g.
- **Estado:** done — cluster en producción, R3 (HA real), posture enforce+ACL+TLS homogénea, chaos test de pérdida de 1 nodo superado.

## Resumen

unibus está desplegado como un **cluster de 3 nodos** (magnus, homer, datardos) con
replicación **R3** del plano de control (rooms/members/keys/users en JetStream KV + el
bucket de nonces anti-replay). La posture de seguridad es idéntica en los tres nodos
(`enforce` + per-subject ACL + TLS de datos + mutual-TLS de routes + `--store kv`), el
admin operador está sembrado en el KV replicado, y el cluster tolera la caída de
cualquier nodo (quórum 2/3). El material de deploy estaba preparado pero **nunca se había
probado contra VPS reales**; durante el despliegue se encontraron y corrigieron **tres
defectos de arranque en frío del cluster** que impedían la convergencia.

## Topología real (Fase 0)

| Nodo | SSH | IP pública | Rol | Notas |
|---|---|---|---|---|
| magnus | `magnus` (root) | 135.125.201.30 | seed / nodo | **= organic-machine.com = `om` = vps-3546abf9** |
| homer | `homer` (root) | 141.94.69.66 | nodo | vps-0db0572c |
| datardos | `dd` (root) | 51.91.100.142 | nodo | vps-ba7da64f |

**Hallazgo crítico — identidad de magnus:** el prompt describía magnus como un VPS con
coolify + minio + postgres + authentik + portainer + dagu. La realidad: **magnus es el
mismo host que `organic-machine.com` / `om`** (confirmado por DNS → 135.125.201.30, por la
nota del entry `pass` `MAGNUS_ovh_ssh_-_ubuntu_organic-machine` → `ssh ubuntu@organic-machine.com`,
y por el label `"node":"magnus"` del fleet-agent). Tras la reinstalación de `om` del
06/06/2026, coolify fue removido; magnus hoy corre **caddy + grafana-fleet +
victoriametrics + docker(registry-api, gitea, gitea-postgresql) + fleet-agent** — es el
host crítico del ecosistema (Gitea de todos los sub-repos + registry-api + hub de
monitorización). El bus se desplegó **conviviendo** con todo eso, sin tocar ningún
servicio existente.

**Acceso SSH:** los tres nodos exponen `PermitRootLogin without-password`. Se instaló la
clave pública del operador (`id_ed25519`) en `/root/.ssh/authorized_keys` de los tres vía
`sudo` (NOPASSWD disponible como `ubuntu`). Se creó el alias `magnus` en `~/.ssh/config`.

**Puertos del bus libres (regla dura):** 8470 (HTTP), 4250 (NATS cliente), 6250 (routes)
estaban **LIBRES en los tres** antes de tocar nada; cero colisión con caddy(80/443),
gitea(3000/22222), registry-api(8420), VM(8428), grafana(3001).

## Decisión WireGuard vs público

El runbook prefiere `ROUTE_NETWORK=wg` (routes server-to-server por mesh WireGuard privado).
Se verificó con `wg show` que **NO existe mesh WireGuard entre los tres nodos del cluster**:
homer y datardos **ni siquiera tienen el binario `wg` instalado**, y los únicos peers WG de
magnus(om) son los PCs personales del operador (`home-wsl`, `windows-lucas`), no los VPS.
La "datardos-wg 10.21.0.x" mencionada en el issue 0006 no está montada.

**Decisión (autorizada por el runbook): `ROUTE_NETWORK=public` + mutual-TLS.** Las routes
viajan por las IPs públicas pero están protegidas por la **CA de routes separada** (un cert
de cliente del plano de datos no puede presentarse en el puerto de routes). No se montó un
mesh WG a ciegas. Trade-off: el puerto 6250 escucha en la IP pública; en magnus (único nodo
con ufw activo) se restringió por ufw a las IPs de homer y datardos; en homer/datardos (ufw
inactivo, hosts Docker) el mutual-TLS de routes es la protección — activar un firewall desde
cero en hosts Docker en producción se evitó por riesgo de romper su networking y de lockout
SSH.

## Cambios

### Configuración de deploy (`deploy/cluster/`)
- `nodes.env`: rellenado con la topología real (IP de magnus, `ROUTE_NETWORK=public`,
  `KV_REPLICAS=3`). Se limpió la sintaxis `<PLACEHOLDER>`/`<SSH_HOST>` de los **comentarios**,
  que el guard `grep -q '<[A-Z_]\+>'` de los scripts interpretaba como placeholders sin
  rellenar y abortaba (defecto del material: los comentarios mismos disparaban el guard).
- TLS: `generate-cluster-certs.sh` generó la CA de routes separada + cert de route y cert de
  datos por nodo (SANs con IP pública + hostname). Secreto de route: `openssl rand -hex 32`.
- Secretos guardados en `pass`: `unibus/operator-identity` (clave privada del operador),
  `unibus/operator-sign-pub` (hex), `unibus/cluster-route-secret`. Las claves TLS y el
  `cluster.pass` quedan gitignored en `secrets/`+`out/`, nunca a git.

### Fixes de código (mergeados a `master` del sub-repo unibus, vía TBD `--no-ff`)

Tres defectos en la ruta de arranque en frío del cluster, ninguno visible en single-node
(donde JetStream está listo al instante):

| # | Archivo | Defecto | Fix |
|---|---|---|---|
| 1 | `pkg/embeddednats/embeddednats.go` | El pooling de routes de nats-server 2.10 (pool de 3 por defecto) generaba churn de "duplicate route"/"client closed" en el cluster pequeño, interrumpiendo los heartbeats RAFT del meta-group → re-elecciones perpetuas de líder. | `Cluster.PoolSize = -1` (una route por par). |
| 2 | `pkg/embeddednats/embeddednats.go` | Los nodos son hosts Docker; NATS anunciaba las IPs de los bridges Docker (172.x / 10.0.x) a los peers, que intentaban conectar a esas IPs privadas inalcanzables → desestabilizaba el meta-group. | `Cluster.NoAdvertise = true` (solo las routes explícitas a IPs públicas). Más un toggle `UNIBUS_NATS_DEBUG` (off por defecto) que habilita el logger y el puerto de monitoreo del nats embebido para depurar. |
| 3 | `pkg/membership/jetstream_store.go` | Una op de KV es request/reply de NATS; en un cluster frío la op se publicaba una vez, antes de que el nodo tuviera contacto con el meta-leader, así que el request se descartaba (no se encola) y la única llamada con context largo se bloqueaba hasta el timeout. | Reintentar cada bucket con contexts cortos hasta éxito o agotar un budget de bootstrap (120s); aterriza en cuanto el meta-group converge. |

Con los tres, el cluster forma limpio, crea los buckets KV, escala R1→R3 in-place y sobrevive
la pérdida de un nodo.

## Verificación (evidencia ejecutable)

### Fase 4 — posture homogénea + cluster formado
```
$ for h in magnus homer dd; do curl -fsS https://127.0.0.1:8470/healthz --cacert ...; done
[magnus] {"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}
[homer]  {"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}
[dd]     {"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}

/jsz: meta-leader=datardos, cluster_size=3, 6 streams creados, NRestarts=0 en los 3.
```

### Fase 5 — admin sembrado en el KV replicado
```
$ membershipd user add --db seed.db --handle operator --sign-pub 48bc...73fa --role admin
$ membershipd migrate-to-kv --replicas 1
migrated to KV: 0 rooms, 0 members, 0 keys, 1 users
$ /jsz KV_UNIBUS_users -> msgs=1   (admin presente en el cluster)
```
(El seed se hace por el bootstrap loopback no-auth del runbook, antes de arrancar el cluster;
con los fixes y arranque escalonado magnus→homer→datardos, el cluster adopta el store seedeado
y converge.)

### Fase 6 — escalado R1 → R3 in-place (HA real)
```
Antes:  cada bucket  leader=magnus, 0 followers   (R1, SPOF en magnus)
$ KV_REPLICAS=3 en los 3 cluster.env; restart rolling (homer primero)
Después: cada uno de los 6 buckets  leader=magnus, followers_current=2/2  (R3, quórum 2/3)
```

### Fase 7 — chaos test (pérdida de 1 nodo)
```
$ systemctl stop membershipd-cluster  (magnus, líder de los 6 streams)  -> magnus DOWN
[homer] healthz ok   [dd] healthz ok
meta-leader re-electo: homer (era datardos), meta_size=3
los 6 streams re-eligieron líder a homer automáticamente, sirviendo con quórum 2/3
KV operativo degradado: KV_UNIBUS_users accesible, admin msgs=1
$ systemctl start membershipd-cluster (magnus)  -> rejoin
los 6 streams: followers_current=2/2  (magnus re-sincronizó como follower R3)
```
No se mataron 2 nodos (sería pérdida de quórum esperada, fuera de scope).

### Sanity — servicios existentes de magnus intactos
```
caddy/grafana-fleet/victoriametrics/fleet-agent = active
docker: registry-api, gitea, gitea-postgresql corriendo;  gitea HTTP=200
puertos 80/443/3000/3001/8420/8428 (existentes) + 4250/6250/8470 (bus) coexisten
```

### Producción limpia
- `UNIBUS_NATS_DEBUG` retirado de los 3 `cluster.env`; rolling restart; puerto de monitoreo
  8222 cerrado; los 3 healthz OK.
- ufw de magnus: añadidas (aditivas, sin tocar reglas existentes) `8470/tcp`, `4250/tcp`
  públicas y `6250/tcp` restringido a homer+datardos.
- `go vet` + `go test ./pkg/embeddednats/ ./pkg/membership/` → ambos `ok`.

## Gaps / pendientes

- **Push a Gitea pendiente:** los 2 commits de fix están en `master` local del sub-repo
  `unibus`, **no pusheados**. El operador debe `git push` (o `/full-git-push`).
- **Seed del admin en cluster corriendo (GAP del report 0009):** no existe `user add --store
  kv`; añadir usuarios requiere el bootstrap loopback con el cluster parado. Para sembrar el
  admin hubo que limpiar stores, seedear en magnus standalone y arrancar el cluster (orden
  escalonado magnus→homer→datardos). Mientras no exista una vía de alta de usuarios al KV con
  el cluster vivo, cada alta requiere ese procedimiento. Recomendación: implementar `user add
  --store kv` que use la conexión interna privilegiada.
- **Verificación de cliente end-to-end no ejecutada:** el chaos test validó el plano de
  control (healthz + failover de meta/stream leaders + KV legible con 2/3), pero no se conectó
  un cliente del bus autenticado (nkey+TLS) a crear/publicar en una room durante el corte.
  Queda como verificación complementaria con la identidad `operator` (en `pass`).
- **R1 fue inservible en este cluster:** el rollout R1→R3 del runbook asume que R1 funciona
  primero; en la práctica R1 dejaba los 6 buckets en un único nodo (SPOF) y, sobre todo, el
  arranque solo convergió tras los 3 fixes. El despliegue saltó directo a R3 una vez formado.
- **Orden de arranque del runbook:** el runbook indica arrancar "magnus solo y verificar
  healthz" antes de los demás; con `--cluster-name` de 3 un nodo solo no tiene quórum del
  meta-group, así que magnus solo nunca sirve healthz hasta que se une un segundo nodo. El
  arranque correcto es simultáneo (cluster limpio) o escalonado con el retry loop que tolera
  la espera de quórum. Conviene corregir esa instrucción del README.

---

**Gaps cerrados en report 0012** (`0012-2026-06-07-unibus-deploy-gaps-closed.md`): GAP A
`user add --store kv` (alta al KV con el cluster vivo), GAP B verificación cliente end-to-end
real + failover (`cmd/clientcheck`), GAP C runbook corregido. Verificado contra los 3 VPS.