Una chuleta práctica con los comandos de administración de TIBCO ActiveSpaces 5.2: el servicio de realm sobre servidores FTL, la definición del grid con tibdg, el arranque de los procesos, el estado, el escalado, los checkpoints y los logs. Todos los comandos están comprobados en el manual oficial de administración de la versión 5.2, y los tienes también en el README.md de la izquierda.
¿Qué vas a aprender?
- Las piezas de ActiveSpaces 5.2 y qué cambió frente a 4.x: el servicio de realm ahora son servidores FTL.
- Conectar
tibdgal realm y definir un grid completo con un script. - Crear tablas, columnas e índices, y arrancar los procesos en el orden correcto.
- Revisar el estado del grid, escalarlo con copysets y repartir clientes entre proxies.
- Hacer checkpoints, restaurar desde ellos y saber dónde están los logs y las métricas.
Requisitos previos
- TIBCO ActiveSpaces 5.2 instalado y su licencia o servicio de activación.
- TIBCO FTL 7.2 o superior para el servicio de realm.
- Acceso por terminal (bash) a las máquinas del grid y a la URL del servidor FTL.
- Conocer los conceptos básicos de un data grid: tablas, claves, réplicas y quórum.
Paso a paso
1. Entiende los componentes
| Componente | Qué hace |
|---|---|
| Servicio de realm (servidores FTL) | Guarda la configuración del grid y coordina el resto. En 5.x es un clúster de servidores TIBCO FTL (tibftlserver): 1 en desarrollo, 3, 5 o 7 en producción. Ya no hay un realm server aparte. |
State keepers (tibdgkeeper) | Llevan el estado del grid (qué nodo es primario en cada copyset). En producción, 3 en máquinas distintas: el grid funciona mientras haya quórum (2 de 3). |
Nodos (tibdgnode) | Guardan los datos en memoria y disco. Se agrupan en copysets: cada copyset guarda una parte de los datos replicada en sus nodos (2 por copyset en producción). |
Proxies (tibdgproxy) | Reciben las conexiones de las aplicaciones y las llevan al nodo que tiene cada dato. |
Servicio de administración (tibdgadmind) | Necesario para las operaciones SQL de definición (por ejemplo, DROP TABLE). Se recomienda ejecutarlo como servicio dentro del servidor FTL. |
Para producción, la configuración mínima recomendada es: 3 state keepers en máquinas distintas y 2 nodos por copyset.
2. Arranca el servicio de realm
Arranca los servidores FTL antes que cualquier otro componente:
# Un servidor FTL (desarrollo)
tibftlserver -n ftl1@host1:8080 --license https://activacion.empresa.local:7070
# Clúster de servidores FTL (producción: 3, 5 o 7), cada uno con el mismo YAML
tibftlserver -c ftl-cluster.yaml -n ftl1 --license https://activacion.empresa.local:7070
3. Conecta tibdg al realm
tibdg es la herramienta de administración. Su sintaxis general es tibdg [-r url_realm] [-g grid] [-s script] [-m mensaje] comando argumentos. Si no indicas -g, trabaja sobre el grid _default.
# La URL del servicio de realm se indica con -r (por defecto http://localhost:8080)
tibdg -r http://ftl1:8080 status
# Con un clúster de servidores FTL, las URL separadas por |
tibdg -r "http://ftl1:8080|http://ftl2:8080|http://ftl3:8080" status
# O una sola vez, en una variable de entorno
export TIBDG_FTL="http://ftl1:8080|http://ftl2:8080|http://ftl3:8080"
tibdg -g migrid status
# Ayuda de cualquier comando
tibdg help
tibdg help grid create
tibdg help table
Con seguridad activada, las credenciales van en TIBDG_FTL_USER, TIBDG_FTL_PASSWD y TIBDG_FTL_TRUSTFILE.
4. Define el grid con un script
Guarda la definición en un archivo (migrid.tibdg) para poder repetirla en cada entorno: el grid, su copyset, los nodos, los state keepers y los proxies, con checkpoints automáticos cada 10 minutos y los 5 últimos guardados.
grid create statekeeper_count=3 copyset_size=2 checkpoint_interval=600 checkpoint_retention_limit=5 migrid
copyset create cs1
node create --copyset cs1 --dir ./n1_data n1
node create --copyset cs1 --dir ./n2_data n2
keeper create --dir ./k1_data k1
keeper create --dir ./k2_data k2
keeper create --dir ./k3_data k3
proxy create p1
proxy create p2
Y aplícalo de una vez, con un mensaje que queda en el histórico de despliegues:
tibdg -r http://ftl1:8080 -g migrid -s migrid.tibdg -m "Definición inicial del grid"
Si prefieres que te lo pregunte paso a paso, tibdg grid generate migrid.tibdg genera el script de forma interactiva.
5. Crea tablas, columnas e índices
Cada tabla se crea con su clave y después se añaden columnas (tipos: long, double, string, datetime, opaque y, en 5.2, vector_float32[dim]). Los índices solo admiten columnas long o string.
tibdg -g migrid table create default_ttl=0 pedidos id long
tibdg -g migrid column create pedidos cliente string
tibdg -g migrid column create pedidos importe double
tibdg -g migrid column create pedidos creado datetime
tibdg -g migrid index create pedidos idx_cliente cliente
tibdg -g migrid table list
6. Arranca los procesos en orden
Siempre state keepers, luego nodos y luego proxies. Las opciones -k (prefijo del archivo de log), -q (tamaño máximo en bytes) y -w (número de archivos que se conservan) controlan la rotación de logs.
# 1. State keepers (los tres; el grid necesita el quórum: al menos 2)
tibdgkeeper -n k1 -r http://ftl1:8080 -g migrid -k /var/log/as/k1 -q 10485760 -w 5
tibdgkeeper -n k2 -r http://ftl1:8080 -g migrid -k /var/log/as/k2 -q 10485760 -w 5
tibdgkeeper -n k3 -r http://ftl1:8080 -g migrid -k /var/log/as/k3 -q 10485760 -w 5
# 2. Nodos, de uno en uno: esperar a que cada uno esté sincronizado antes del siguiente
tibdgnode -n n1 -r http://ftl1:8080 -g migrid -k /var/log/as/n1
tibdgnode -n n2 -r http://ftl1:8080 -g migrid -k /var/log/as/n2
# 3. Proxies (con -e si los clientes llegan por otra dirección)
tibdgproxy -n p1 -r http://ftl1:8080 -g migrid -e proxy1.empresa.local:8888
tibdgproxy -n p2 -r http://ftl1:8080 -g migrid -e proxy2.empresa.local:8888
7. Revisa el estado del grid
tibdg status es el primer comando ante cualquier duda: muestra los procesos y el tamaño estimado de cada nodo, y una sección de reindexado cuando hay un índice en construcción.
tibdg -g migrid status # procesos (nodos, keepers, proxies) y tamaño estimado
tibdg -g migrid node status n1 # detalle de un proceso
tibdg -g migrid table list # tablas definidas
tibdg -g migrid copyset list # copysets
tibdg -g migrid proxy clients p1 # clientes conectados a un proxy
8. Escala el grid con copysets
La capacidad crece añadiendo copysets. Tras arrancar los nodos nuevos, grid redistribute reparte los datos; para reducir, se desactiva el copyset, se redistribuye y se elimina:
# Añadir capacidad: un copyset nuevo con sus dos nodos
tibdg -g migrid copyset create cs2
tibdg -g migrid node create --copyset cs2 --dir ./n3_data n3
tibdg -g migrid node create --copyset cs2 --dir ./n4_data n4
# ... arrancar n3 y n4 con tibdgnode ...
tibdg -g migrid grid redistribute
tibdg -g migrid status # seguir el reparto de los datos
# Quitar capacidad: vaciar el copyset, redistribuir y eliminarlo
tibdg -g migrid copyset deactivate cs2
tibdg -g migrid grid redistribute
tibdg -g migrid copyset remove cs2
9. Reparte los clientes entre proxies
Si un proxy se carga más que los demás, o antes de pararlo para mantenimiento, mueve sus clientes a otros proxies sin cortar el servicio:
tibdg -g migrid proxy clients p1 # conexiones de clientes del proxy
tibdg -g migrid proxy shed p1 clients 10 # mover 10 clientes a otros proxies
tibdg -g migrid proxy shed p1 connection 4711 # mover una conexión concreta
10. Haz checkpoints
Un checkpoint es una copia consistente de los datos del grid. Además de los automáticos (paso 4), haz uno manual antes de cualquier cambio importante:
tibdg -g migrid checkpoint create antes-de-la-subida
tibdg -g migrid checkpoint list # ID, nombre, directorio, fecha y estado
tibdg -g migrid checkpoint tables antes-de-la-subida
tibdg -g migrid checkpoint validate antes-de-la-subida
tibdg -g migrid checkpoint delete antes-de-la-subida
11. Restaura desde un checkpoint
La restauración vuelve el grid entero al momento del checkpoint:
# 1. Cargar la definición del grid guardada con el checkpoint
tibdg -g migrid -r http://ftl1:8080 grid load -rollback realmserver-grid.json
# 2. Marcar el checkpoint al que se vuelve
tibdg -g migrid rollback create 12
# 3. Restaurar el directorio de datos de cada nodo desde checkpoints/<fecha>_..._chkpt y arrancarlo
# 4. Al terminar, quitar la marca de rollback
tibdg -g migrid -r http://ftl1:8080 rollback delete
12. Revisa logs y métricas
- Si los procesos corren como servicios dentro del servidor FTL, cada uno puede tener su
logfileen el YAML; si no, su salida va al log del servidor FTL, con el nombre del componente delante. - Si corren por separado, el log de cada uno es el que indicaste con
-k. - El servidor FTL recoge las métricas de los procesos de ActiveSpaces y las expone para que Prometheus las recoja.
Y el servicio de administración, si lo ejecutas por separado, con su propio log y nivel de traza (severe, warn, info o debug):
tibdgadmind -r http://ftl1:8080 -l http://0.0.0.0:7171 --logfile /var/log/as/admind --max-log-size 10485760 --max-logs 5 --trace warn
Errores habituales
tibdg no encuentra el grid o el realm
Sin -r ni TIBDG_FTL, tibdg se conecta a http://localhost:8080; sin -g, usa el grid _default. Indícalos siempre, sobre todo si administras varios entornos desde la misma máquina.
El grid deja de responder al caer un state keeper
Con 3 state keepers hace falta quórum (2 en marcha). Si solo hay uno, el grid no puede funcionar: arranca otro y repártelos en máquinas distintas para que una sola caída no se lleve dos.
Los nodos tardan o no se sincronizan al arrancar
Arráncalos de uno en uno y espera a que cada nodo termine de sincronizarse (tibdg status) antes de arrancar el siguiente.
«grid redistribute» no mueve datos al copyset nuevo
Los nodos del copyset nuevo tienen que estar arrancados antes de redistribuir. Revisa con tibdg status que aparecen en marcha.
No hay comando tibdg para borrar una tabla
Las tablas se borran con SQL (DROP TABLE) desde la API, y para eso tiene que estar en marcha el servicio de administración (tibdgadmind o el servicio dentro del servidor FTL). tibdg table purge solo limpia tablas ya borradas.
Error al crear un índice
Las columnas de un índice tienen que ser de tipo long o string.
Comportamiento extraño tras actualizar desde 4.x
ActiveSpaces 5.2 necesita FTL 7.2 o superior y ya no usa un realm server propio. Revisa la versión de los servidores FTL y las notas de la versión antes de actualizar.
Siguientes pasos
- Activar la seguridad de FTL 7: certificados propios, mTLS y OAuth2.
- Configurar el forwarding entre grids de 5.2 para recuperación ante desastres.
- Llevar las métricas del servidor FTL a Prometheus y Grafana, con alertas sobre el quórum y el espacio de los nodos.
- Versionar los scripts de
tibdgy aplicarlos desde un pipeline en cada entorno.