# Comandos básicos de administración de TIBCO ActiveSpaces 5.2

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/comandos-administracion-tibco-activespaces-5-2/

## ¿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 `tibdg` al 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

### Componentes

- Servicio de realm: clúster de servidores FTL (tibftlserver), 1 o 3/5/7
- State keepers (tibdgkeeper): 3 en producción, quórum 2
- Nodos (tibdgnode) en copysets: 2 por copyset en producción
- Proxies (tibdgproxy)
- Servicio de administración (tibdgadmind) para SQL DDL

### Servicio de realm

```bash
# 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
```

### Conectar tibdg

```bash
# 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
```

### Script del grid (migrid.tibdg)

```text
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
```

```bash
tibdg -r http://ftl1:8080 -g migrid -s migrid.tibdg -m "Definición inicial del grid"
```

### Tablas, columnas e índices

```bash
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
```

### Arranque (keepers, nodos, proxies)

```bash
# 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
```

### Estado

```bash
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
```

### Escalar con copysets

```bash
# 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
```

### Proxies

```bash
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
```

### Checkpoints

```bash
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
```

### Restaurar

```bash
# 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
```

### Servicio de administración

```bash
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 `tibdg` y aplicarlos desde un pipeline en cada entorno.

Fuente: TIBCO ActiveSpaces 5.2.0 Administration (docs.tibco.com).
