Runbook — CDP Unomi¶

Deploy¶

Dónde corre: VM devops-vm de GCP (zona southamerica-east1-a), Docker Compose, proyecto cdp en /opt/cdp/unomi-eval/deploy. Acceso por SSH a través de IAP (sin puerto 22 público):

gcloud compute ssh devops-vm --zone southamerica-east1-a --tunnel-through-iap

Desplegar la última versión de main:

cd /opt/cdp && git pull
cd unomi-eval/deploy
docker compose build inoyu-ui        # solo si cambió inoyu-ui/ (Dockerfile o parches); ~5 min
docker compose up -d                 # recrea únicamente lo que cambió
docker compose ps                    # esperar "healthy" en cdp-es, cdp-unomi y cdp-inoyu-ui (Unomi: 20 a 60 s)

Los secretos viven en /opt/cdp/unomi-eval/deploy/.env (modo 600; nunca en git). Cambiar un valor de .env y ejecutar docker compose up -d recrea el servicio afectado. Las variables UNOMI_URL, NEXT_PUBLIC_UNOMI_URL y UNOMI_VERSION de Inoyu se incrustan al compilar: cambiarlas exige docker compose build inoyu-ui.

Cómo verificar que el deploy salió bien (desde la VM):

set -a; . /opt/cdp/unomi-eval/deploy/.env; set +a
curl -s -o /dev/null -w '%{http_code}\n' -u "karaf:$UNOMI_ROOT_PASSWORD" http://127.0.0.1:8181/cxs/cluster   # 200
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8181/cxs/cluster                                   # 401
curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:8181/cxs/context.json?sessionId=deploy-check'     # 200
curl -s http://127.0.0.1:3131/api/health                                                                     # {"status":"healthy","unomi":{"connected":true,...}}

Desde internet: https://cdp.compulandia.com.py debe redirigir al login de Access; https://cdp-api.compulandia.com.py/cxs/cluster debe responder 403 de Cloudflare sin token de servicio.

Logs¶

Qué	Dónde	Cómo verlos
Unomi (Karaf, reglas, validación de esquemas)	`docker logs cdp-unomi` (json-file, 50 MB × 5)	`docker logs -f --since 10m cdp-unomi`
Eventos rechazados por esquema	mismo log, líneas `SchemaServiceImpl`	`docker logs --since 1h cdp-unomi 2>&1 \\| grep -A3 "Schema validation"`
Errores de Unomi	mismo log	`docker logs --since 1h cdp-unomi 2>&1 \\| grep -E "ERROR\\|Exception" \\| grep -v "^\s*at "`
Elasticsearch	`docker logs cdp-es`	`docker logs --since 10m cdp-es`; salud: `docker exec cdp-es curl -s localhost:9200/_cluster/health?pretty`
Inoyu UI	`docker logs cdp-inoyu-ui`	`docker logs -f cdp-inoyu-ui`
Acceso a la UI y a la API	Cloudflare Zero Trust → Logs → Access	Panel de Cloudflare
Host y contenedores	Prometheus/Grafana/Loki/cAdvisor ya instalados en `devops-vm`	Grafana en la VM (puerto 3200)

Rollback¶

Condiciones: los datos viven en Elasticsearch (volumen cdp-es-data) y no se tocan en un rollback de configuración o de imagen de Inoyu. No volver a una versión mayor anterior de Unomi o de Elasticsearch: Unomi migra índices al arrancar y no hay camino inverso; en ese caso restaurar desde snapshot.

cd /opt/cdp
git log --oneline -5                              # elegir el commit anterior conocido bueno
git checkout <commit>
cd unomi-eval/deploy
docker compose build inoyu-ui                     # solo si el rollback toca inoyu-ui/
docker compose up -d
docker compose ps                                 # healthy en los tres servicios
git checkout main                                 # dejar el árbol en main tras confirmar; corregir hacia adelante

Rollback de datos: POST /_snapshot/<repo>/<snapshot>/_restore en Elasticsearch con cdp-unomi detenido (docker compose stop unomi), luego docker compose start unomi. El repositorio de snapshots y la política diaria están pendientes de configurar (ver lista de pendientes en el diseño de despliegue).

Fallas frecuentes¶

1. `cdp-unomi` queda `unhealthy` tras recrear el contenedor; el 8181 no responde¶

Ocurrió el 2026-09-11 al cambiar los puertos publicados. Síntoma: docker compose ps muestra health: starting y luego unhealthy; curl localhost:8181 devuelve 000; en el log, External configuration /opt/apache-unomi/etc/jetty.xml is not available y decenas de Unable to start container for blueprint bundle ... unresolved dependencies.

Diagnóstico: docker logs cdp-unomi 2>&1 | grep -m1 "jetty.xml". La causa es una caché de Karaf persistida (/opt/apache-unomi/data) de un contenedor anterior: las features figuran instaladas y no se regeneran los archivos de etc/.
Resolución: confirmar que el compose no monta un volumen en /opt/apache-unomi/data (se eliminó ese día). Si existe: docker compose down unomi && docker volume rm cdp-unomi-data && docker compose up -d. Unomi vuelve a healthy en ~20 s. El estado real está en Elasticsearch; no se pierde nada.

2. `docker compose build inoyu-ui` falla en `apk add --no-cache git` con `DNS: transient error`¶

Ocurrió el 2026-09-11 en el primer deploy. En devops-vm los contenedores de la red bridge por defecto reciben el resolver 169.254.169.254 y no lo alcanzan; las redes definidas por el usuario y la red de host sí resuelven.

Diagnóstico: docker run --rm alpine nslookup dl-cdn.alpinelinux.org falla; con --network host funciona.
Resolución: el compose ya declara build.network: host para inoyu-ui. Si vuelve a fallar, comprobar que esa línea sigue en docker-compose.yml y que el host resuelve (curl -sI https://dl-cdn.alpinelinux.org).

3. Los eventos llegan (HTTP 200) pero el perfil no cambia y no aparecen en Inoyu¶

Observado repetidamente en el banco de pruebas (2026-09-03 y 2026-09-07). Unomi valida cada evento contra el esquema JSON de su tipo y, si lo rechaza, responde igual 200 {"updated":0}: Jitsu no ve el error.

Diagnóstico: docker logs --since 30m cdp-unomi 2>&1 | grep -A3 "Schema validation". Causas ya vistas: propiedad no declarada en el esquema (is not defined in the schema), source/target no declarados, Unknown scope value (scope inexistente o creado hace menos de 2 s), Schema not found for event type.
Resolución: corregir el esquema con POST /cxs/jsonSchema (ver esquemas de eventos) o el mapeo en Jitsu; validar antes de enviar con POST /cxs/jsonSchema/validateEvent. Los eventos rechazados no se recuperan: Jitsu debe reenviarlos.

Otras señales conocidas¶

/cxs/context.json responde 500 (No service defined for : setRemoteHostInfoAction) durante los primeros ~10 s tras el arranque aunque /cxs/cluster ya dé 200: transitorio, esperar.
GET /cxs/client/myprofile.* responde 500 siempre: bug de Unomi 3.0.0 (ConfigSharingService nulo). Usar POST /cxs/profiles/export.
Pantalla "Groovy Actions" de Inoyu vacía con error: Unomi 3.0.0 devuelve 500 en GET /cxs/groovy-actions.
Memoria de la VM: el CDP tiene límites (ES 2,5 GiB, Unomi 2 GiB, Inoyu 512 MiB) pero la VM comparte 16 GB con otras 14 aplicaciones y no tiene swap. Si docker stats muestra a cdp-es pegado a su límite, revisar docker logs cdp-es | grep -i "circuit\|OutOfMemory" y considerar bajar ES_ROLLOVER_MAXSIZE o subir el límite.