system-docs/07_OPERACION/runbooks.md

Runbooks - Operación Skynet v8

Runbook: Reinicio de servicios

Objetivo

Reiniciar servicios del sistema sin afectar operaciones críticas.

Procedimiento

1. Verificar estado actual

   systemctl status skynet-core
   systemctl status skynet-database
   systemctl status skynet-api
   

2. Notificar a usuarios (si aplica)

   • Enviar notificación de mantenimiento planeado
   • Esperar confirmación de ventana de mantenimiento

3. Reiniciar servicios en orden

   # Primero servicios auxiliares
   systemctl restart skynet-cache
   systemctl restart skynet-broker
   
   # Luego servicios principales
   systemctl restart skynet-database
   sleep 30
   systemctl restart skynet-api
   sleep 20
   systemctl restart skynet-core
   

4. Verificar estado post-reinicio

   systemctl status skynet-core
   systemctl status skynet-database
   systemctl status skynet-api
   
   # Verificar conectividad
   curl -s http://localhost:8080/health
   curl -s http://localhost:5432/ping
   

5. Validar operación normal

   • Verificar logs sin errores críticos
   • Ejecutar health checks
   • Monitorear métricas durante 5 minutos

Rollback

Si hay fallos:

systemctl stop skynet-core
systemctl stop skynet-api
systemctl stop skynet-database

# Restaurar desde último snapshot conocido
pg_restore -d skynet /backups/skynet_latest.sql
systemctl start skynet-database
systemctl start skynet-api
systemctl start skynet-core

Tiempo estimado

20-30 minutos con validación

---

Runbook: Failover de base de datos

Objetivo

Cambiar a base de datos secundaria en caso de fallo de primaria.

Prerrequisitos

• Replicación configurada y activa
• Sistema de monitoreo detectó fallo de primaria
• Base de datos secundaria disponible

Procedimiento

1. Confirmar fallo de primaria

   # Intentar conectarse a primaria
   psql -h skynet-primary -U postgres -d skynet -c "SELECT 1"
   
   # Verificar lag de replicación
   psql -h skynet-primary -U postgres -c "SELECT slot_name, restart_lsn FROM pg_replication_slots"
   

2. Promover secundaria

   # En servidor secundario
   pg_ctl promote -D /var/lib/postgresql/14/main
   
   # Esperar 30 segundos para que complete
   sleep 30
   
   # Verificar estado
   psql -U postgres -c "SELECT pg_is_wal_replay_paused()"
   

3. Redirigir aplicaciones

   # Actualizar DNS o connection string
   # En skynet-api.conf:
   # database_host = skynet-secondary
   
   systemctl restart skynet-api
   

4. Verificar operación normal

   # Validar escrituras en nueva primaria
   psql -h skynet-secondary -U postgres -d skynet -c "INSERT INTO test VALUES (NOW())"
   
   # Monitorear performance
   watch -n 2 'psql -h skynet-secondary -U postgres -c "SELECT count(*) FROM skynet_logs"'
   

5. Informar del failover

   • Registrar en incident log
   • Notificar al equipo
   • Agendar recuperación de primaria

Recovery de primaria

# Una vez primaria se recupere:
pg_basebackup -h skynet-primary -D /var/lib/postgresql/14/main -U replication
systemctl start postgresql

Tiempo estimado

5-10 minutos

---

Runbook: Restauración de backups

Objetivo

Restaurar datos desde backups en caso de corrupción o pérdida de datos.

Tipos de restauración

1. Restauración completa

# Detener servicios
systemctl stop skynet-core
systemctl stop skynet-api
systemctl stop skynet-database

# Restaurar backup completo
pg_restore -C -d postgres /backups/skynet_full_2025-12-30.sql

# Reiniciar servicios
systemctl start skynet-database
sleep 30
systemctl start skynet-api
systemctl start skynet-core

2. Restauración point-in-time (PITR)

# Restaurar hasta timestamp específico
psql -U postgres -d skynet -c "
  SELECT pg_wal_replay_pause();
  SELECT pg_xact_xmin(xid) FROM pg_xact;
"

# Restaurar WAL archive hasta timestamp
pg_restore -U postgres -d skynet \
  -e -t tabla_critica /backups/skynet_full.sql

# Aplicar WAL hasta punto
pg_wal_replay_start()

3. Restauración de tabla específica

# Restaurar solo tabla corrupta
pg_restore -d skynet -t tabla_corrupta /backups/skynet_full.sql

# Validar integridad
ANALYZE tabla_corrupta;

Validación post-restauración

# Verificar integridad
psql -U postgres -d skynet -c "SELECT COUNT(*) FROM pg_stat_user_tables"

# Comparar checksums
pg_basebackup --wal-method=fetch -l "restore_$(date +%s)"

# Validar índices
REINDEX DATABASE skynet;

Tiempo estimado

• Completa: 30-60 minutos (depende tamaño)
• PITR: 15-45 minutos
• Tabla: 5-15 minutos

---

Runbook: Escalado de recursos

Objetivo

Aumentar capacidad de computo o almacenamiento sin downtime.

Escalado de CPU/RAM

1. Evaluar necesidad

   # Monitorear uso actual
   top -n 1 | head -20
   free -h
   
   # Proyectar crecimiento
   # Si uso > 80%, escalar inmediatamente
   # Si proyectado > 80% en 7 días, escalar
   

2. Escalar infraestructura

   # En cloud provider o hypervisor
   # Aumentar CPU cores
   # Aumentar memoria RAM
   # Aplicar cambios sin reinicio (si soportado)
   

3. Verificar en SO

   lscpu
   free -h
   

4. Rebalancear servicios

   # Aumentar workers/threads en config
   systemctl restart skynet-api
   
   # Aumentar shared_buffers en PostgreSQL
   # postgresql.conf: shared_buffers = 16GB (en lugar de 8GB)
   systemctl restart skynet-database
   

Escalado de almacenamiento

1. Monitorear uso

   df -h /var/lib/postgresql
   du -sh /backups
   
   # Alerta si > 80% utilizado
   

2. Agregar espacio

   # Opción 1: Aumentar volumen existente
   lvextend -l +50G /dev/vg0/lv_data
   resize2fs /dev/vg0/lv_data
   
   # Opción 2: Agregar nuevo volumen
   # Montar en /data2
   # Configurar replicación a nuevo volumen
   

3. Validar cambios

   df -h /var/lib/postgresql
   # Debe mostrar nuevo tamaño
   

4. Monitorear performance

   • Velocidad I/O
   • Latencia de queries
   • Crecimiento de espacios

Tiempo estimado

• CPU/RAM: 30 minutos - 2 horas (depende downtime)
• Almacenamiento: 1-4 horas (sin downtime posible)

---

Escalabilidad Matriz

Recurso	Umbral Acción	Aumento	Tiempo
CPU	>85% x 5min	+2 cores	30min-2h
RAM	>80% x 10min	+8GB	30min-2h
Disco	>85% utilizado	+50% capacidad	1-4h
Conexiones DB	>80% max_connections	+50 conexiones	15min
Replication lag	>10GB	Increase bandwidth	Immediate