Introducción
crad-virsh-manager.pyc es una herramienta de línea de comandos para la gestión y monitorización de máquinas virtuales basadas en KVM/libvirt (virsh). Su característica principal es la capacidad de detectar y recuperar automáticamente instancias que han dejado de responder.
Requisitos
- Acceso root al servidor hipervisor
- libvirt/KVM configurado
- QEMU Guest Agent instalado en las máquinas virtuales (para recuperación automática)
Características principales
- Listado de instancias: Visualizar todas las VMs con su estado, recursos y configuración
- Recuperación automática: Detectar y reiniciar VMs que no responden
- Gestión básica: Iniciar, detener y reiniciar instancias
- Interacción con Guest Agent: Comunicación directa con el agente QEMU dentro de las VMs
- Estadísticas de I/O: Monitorización de operaciones de lectura/escritura en disco
Opciones disponibles
Listado y monitorización
| Opción | Descripción |
|---|---|
--list-all |
Listar todas las instancias con su estado y configuración |
--include-io-stats |
Incluir estadísticas de I/O en el listado |
--find-recoverable |
Buscar instancias que soportan recuperación automática |
-j, --json |
Salida en formato JSON |
Recuperación automática
| Opción | Descripción |
|---|---|
--check-and-recover |
Verificar instancias y recuperar las que no responden |
--reset-db |
Reiniciar la base de datos de seguimiento |
Gestión de instancias
| Opción | Descripción |
|---|---|
--start=INSTANCIA |
Iniciar una instancia |
--stop=INSTANCIA |
Detener una instancia |
--restart=INSTANCIA |
Reiniciar una instancia |
Interacción con Guest Agent
| Opción | Descripción |
|---|---|
--guest-ping=INSTANCIA |
Enviar ping al Guest Agent de la instancia |
--get-guest-info=INSTANCIA |
Obtener información del Guest Agent |
--read-file=ARCHIVO INSTANCIA |
Leer un archivo desde dentro de la instancia |
Opciones adicionales
| Opción | Descripción |
|---|---|
-v, --verbose |
Modo verboso |
--debug |
Modo depuración |
Ejemplos de uso
Listar todas las instancias
>> crad-virsh-manager.pyc --list-all
Salida:
Id Name State Hostname Flavor Vcpus Memory Started VNC port Recovery Avail. Waiting for Recovery
-- ---- ----- -------- ------ ----- ------ ------- -------- --------------- --------------------
1 |instance-00000001 |running |servidor-web |m1.medium|2 |4096 |2024-01-15 10:30:00 |5901 |[*] |[ ]
2 |instance-00000002 |running |base-datos |m1.large |4 |8192 |2024-01-15 10:35:00 |5902 |[*] |[ ]
3 |instance-00000003 |shut off|servidor-backup |m1.small |1 |2048 |2024-01-10 08:00:00 |5903 |[ ] |[ ]
Listar con estadísticas de I/O
>> crad-virsh-manager.pyc --list-all --include-io-stats
Incluye columnas adicionales:
- wr_req: Peticiones de escritura
- wr_bytes: Bytes escritos
- rd_req: Peticiones de lectura
- rd_bytes: Bytes leídos
- flush_operations: Operaciones de flush
Verificar y recuperar instancias
>> crad-virsh-manager.pyc --check-and-recover
Este comando:
- Lista todas las instancias en estado “running”
- Verifica que el Guest Agent responde (intentando leer /proc/loadavg)
- Si una instancia no responde y tiene soporte de recuperación, la reinicia automáticamente
- Registra la actividad en la base de datos y logs
Verificar conectividad con Guest Agent
>> crad-virsh-manager.pyc --guest-ping=instance-00000001
Salida:
Guest agent ping successful for instance-00000001
Obtener información del Guest Agent
crad-virsh-manager.pyc --get-guest-info=instance-00000001
Reiniciar una instancia
>> crad-virsh-manager.pyc --restart=instance-00000001
Salida en JSON
>> crad-virsh-manager.pyc --list-all --json
Útil para integración con otros sistemas o scripts.
Sistema de recuperación automática
¿Cómo funciona?
- Detección de soporte: La herramienta verifica si cada instancia tiene el QEMU Guest Agent funcionando intentando leer /proc/loadavg
- Marcado de instancias: Las instancias con Guest Agent funcional se marcan como recovery_supported = 1
- Monitorización continua: Con --check-and-recover, se verifica periódicamente que las instancias marcadas respondan
- Recuperación: Si una instancia no responde:
- Se marca como recovery_triggered = 1
- Se intenta reiniciar la instancia
- Se envía notificación por email (si está configurado)
Estados de recuperación
┌────────────────────┬──────────────────────────────────────────────┐
│ Campo │ Descripción │
├────────────────────┼──────────────────────────────────────────────┤
│ recovery_supported │ La instancia tiene Guest Agent y puede ser monitoreada │
├────────────────────┼──────────────────────────────────────────────┤
│ recovery_triggered │ Se ha detectado un fallo y se está intentando recuperar │
├────────────────────┼──────────────────────────────────────────────┤
│ recovery_disabled │ La recuperación automática está deshabilitada para esta instancia │
└────────────────────┴──────────────────────────────────────────────┘
Configurar monitorización automática
Para ejecutar la verificación periódicamente, añadir al crontab:
Verificar y recuperar instancias cada 5 minutos
*/5 * * * * /usr/sbin/crad-virsh-manager.pyc --check-and-recover >> /var/log/virsh-recovery.log 2>&1
Requisitos para recuperación automática
Para que una instancia soporte recuperación automática, debe tener:
-
QEMU Guest Agent instalado y funcionando:
# Debian/Ubuntu
>> apt-get install qemu-guest-agent
>> systemctl enable qemu-guest-agent
>> systemctl start qemu-guest-agent -
Canal de comunicación configurado en la definición de la VM (automático en OpenStack/Nova)
Base de datos de seguimiento
La herramienta mantiene una base de datos SQLite en:
/etc/core-admin/databases/virsh-manager-db.sql
Contiene:
- Tabla instances: Estado de recuperación de cada instancia
- Tabla log: Historial de acciones y recuperaciones
Para reiniciar la base de datos:
>> crad-virsh-manager.pyc --reset-db
Integración con OpenStack/Nova
La herramienta es compatible con entornos OpenStack, extrayendo automáticamente:
- Nombre de host (nova:name)
- Flavor de la instancia
- vCPUs y memoria asignados
- Fecha de creación
- Puerto VNC
Notas técnicas
- La herramienta detecta automáticamente el URI de libvirt (qemu:///system por defecto)
- Soporta múltiples ejecuciones simultáneas con protección contra procesos duplicados
- Los logs de recuperación se mantienen durante 1 hora antes de ser purgados automáticamente
- Compatible con Python 2.7 (Debian Lenny en adelante)