Runbook de operaciones

Este documento se basa en la aplicación offline Enterprise New.

Inspección diaria

1. Ejecuta los siguientes comandos desde el directorio raíz del paquete de despliegue:

   ./bin/verify.sh --site config/site.conf
   ./bin/smoke-business-emqx.sh --site config/site.conf

2. Confirma los siguientes elementos:
   • Los 3 nodos Swarm están en estado Ready.
   • APP VIP /healthz y /readyz devuelven 200.
   • DB VIP:5432 es accesible.
   • La topología PostgreSQL primary, standby y witness es normal.
   • backend, redis, emqx, sourceflow, eventflow, marimo y opcua-server se ejecutan en el nodo de aplicación activo.

Comprobaciones de aplicación

1. Ejecuta los siguientes comandos en el nodo de aplicación activo:

   cd /opt/tier0-enterprise/tier0-deploy
   bash bin/compose.sh ps
   bash bin/compose.sh logs --tail=200 backend
   curl -fsS http://127.0.0.1:8088/healthz
   curl -fsS http://127.0.0.1:8088/readyz

   Nota

   No omitas bin/compose.sh ni ejecutes comandos docker compose sin envolver directamente. El script wrapper carga el entorno de runtime generado por el instalador.

2. Interpretación de health-check:
   • Fallo de healthz: revisa primero el proceso backend, la imagen y los logs del contenedor.
   • Fallo de readyz: revisa también DB VIP, Redis y logs de migración de base de datos.
   • Página inicial accesible pero login no disponible: confirma ADMIN_INITIAL_PASSWORD en .env, luego revisa los logs de migración IAM del backend y las tablas de usuarios. No juzgues el éxito del despliegue solo por el puerto HTTP.

Comprobaciones de entrada de protocolo

nc -vz <APP_VIP> 1883
nc -vz <APP_VIP> 8883
nc -vz <APP_VIP> 8083
nc -vz <APP_VIP> 8084
nc -vz <APP_VIP> 4840

Nota

EMQX y OPC UA Server están fijados al nodo de aplicación activo. El failover de APP VIP solo garantiza la entrada HTTP APP VIP:80. Los puertos de protocolo no se enrutan mediante proxy TCP de HAProxy, por lo que este diseño no promete alta disponibilidad para entradas de protocolo.

Comprobaciones de base de datos

Ejecuta lo siguiente en los nodos de base de datos:

systemctl status tier0-postgresql
systemctl status tier0-repmgrd
sudo -iu postgres psql -Atqc 'select pg_is_in_recovery();'
sudo -iu postgres /usr/local/bin/repmgr -f /etc/repmgr.conf cluster show

• pg_is_in_recovery=false significa primary.
• pg_is_in_recovery=true significa standby.
• DB VIP solo debe ubicarse en el primary actual.
• Si la replicación standby se interrumpe o el witness reporta errores upstream, preserva primero el sitio. No vuelvas a ejecutar directamente el despliegue completo.

Failover de APP VIP

1. Antes de probar, registra el nodo que posee actualmente el VIP y verifica:

   curl -fsS http://<APP_VIP>/healthz
   curl -fsS http://<APP_VIP>/readyz

2. Después de detener keepalived en el nodo VIP actual, confirma que otro nodo de aplicación tome el VIP y vuelve a probar ambas URL. El backend de HAProxy apunta al nodo de aplicación activo en 8088/TCP, por lo que los tres nodos de aplicación deben poder alcanzar el puerto 8088 del nodo activo.

3. Después de restaurar keepalived, ejecuta de nuevo verify.sh y smoke checks. No detengas contenedores de aplicación activos durante el simulacro.

Conmutación por fallo del DB Primary

Antes de un simulacro de fallo, crea un backup y confirma que la replication está sana:

./bin/backup-db.sh --site config/site.conf

Después de detener tier0-postgresql en el primary actual, observa cómo repmgr promueve el standby y cómo DB VIP toma control. El RTO objetivo está dentro de 2 minutos. Pruebas históricas en la misma arquitectura fueron de unos 59-64 segundos.

Precaución

• El primary anterior no debe iniciarse directamente de vuelta en la topología de producción. Primero detén PostgreSQL, repmgrd y keepalived; elimina cualquier DB VIP restante; después ejecuta basebackup desde el nuevo primary actual, registra el nodo como standby y finalmente reconecta el witness.
• Después del failover, no vuelvas a ejecutar directamente el instalador completo. Las definiciones estáticas de primary/standby en el inventory pueden alterar la topología actual.

Backup y restore

• Backup:

  ./bin/backup-db.sh --site config/site.conf

• Restore:

  ./bin/restore-db.sh --site config/site.conf --restore-file /backup/tier0-db/postgres-YYYYmmddTHHMMSS.dump

Nota

Antes de restaurar, confirma el primary actual. Después de restaurar, ejecuta verify.sh, smoke checks y verificación real de login en la plataforma para la ruta de usuario predeterminado.

Limpieza y nueva prueba

./full-cleanup.sh --env install.env --yes
./install.sh --auto --yes

Precaución

La limpieza completa elimina los datos de runtime de Tier0, los datos de Docker/Swarm y las copias de seguridad de base de datos en los 6 nodos. También realiza una limpieza final en el nodo de control después de que sale el contenedor de control. Usa esta entrada solo en entornos de prueba confirmados como descartables. Si se deben conservar datos del cliente o un sitio de incidente, usa el --cleanup normal y completa primero una copia de seguridad.

Problemas comunes

Fallo de arranque de Backend

cd /opt/tier0-enterprise/tier0-deploy
bash bin/compose.sh logs --tail=300 backend
bash bin/compose.sh ps

Nota

Concéntrate en DB URL, DB VIP, Redis, migration y permisos de directorios montados.

Fallo de arranque de EMQX

cd /opt/tier0-enterprise/tier0-deploy
bash bin/compose.sh logs --tail=200 emqx

Nota

Comprueba certificados, archivos de configuración, permisos de volumen y si los puertos 1883/8883/8083/8084 están ocupados.

Reinicios repetidos de repmgrd

systemctl status tier0-repmgrd
tail -100 /var/log/repmgr/repmgr.log
sudo -iu postgres psql -Atqc 'show shared_preload_libraries;'

Nota

Confirma que shared_preload_libraries incluye repmgr y que la unidad systemd usa repmgrd --daemonize=false.

Fallo de verificación de materiales

./bin/verify-materials.sh

Precaución

No omitas la verificación SHA256 para continuar el despliegue. Vuelve a obtener el paquete de entrega o reconstruye los materiales siguiendo el proceso trazable.