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**
   ```bash
   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**
   ```bash
   # 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**
   ```bash
   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:
```bash
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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # Actualizar DNS o connection string
   # En skynet-api.conf:
   # database_host = skynet-secondary

   systemctl restart skynet-api
   ```

4. **Verificar operación normal**
   ```bash
   # 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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**
   ```bash
   # 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**
   ```bash
   # En cloud provider o hypervisor
   # Aumentar CPU cores
   # Aumentar memoria RAM
   # Aplicar cambios sin reinicio (si soportado)
   ```

3. **Verificar en SO**
   ```bash
   lscpu
   free -h
   ```

4. **Rebalancear servicios**
   ```bash
   # 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**
   ```bash
   df -h /var/lib/postgresql
   du -sh /backups

   # Alerta si > 80% utilizado
   ```

2. **Agregar espacio**
   ```bash
   # 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**
   ```bash
   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 |