virtmanager

VirtManager (por C.Rey)

Una API REST y interfaz web para gestionar máquinas virtuales en Ubuntu usando FastAPI, libvirt y noVNC para consola web.

Características

• Gestión completa de VMs: Crear, listar, iniciar, detener y eliminar máquinas virtuales.
• Configuración de arranque: Cambiar el orden de arranque de las VMs (disco duro, CD-ROM, etc.).
• Subida de ISOs: Sube imágenes ISO directamente desde la interfaz web para usar en la creación de VMs.
• Gestión de ISOs: Lista y elimina ISOs subidas.

Instalación

Prerrequisitos del Sistema

Asegúrate de que libvirt esté instalado y configurado:

sudo apt update
sudo apt install -y libvirt-daemon-system libvirt-dev pkg-config python3-libvirt novnc websockify
sudo apt install python3-pip python3.12-venv

Crea el directorio para ISOs (opcional, se crea automáticamente):

sudo mkdir -p /var/lib/libvirt/images/isos

Instalación del Proyecto

1. Clona o descarga el proyecto en /home/creylopez/virtmanager (o ajusta las rutas según corresponda).

2. Crea y activa un entorno virtual:

   python3 -m venv venv
   source venv/bin/activate
   pip install libvirt-python
   

3. Instala las dependencias de Python:

   pip install -r requirements.txt
   

4. Configura permisos para libvirt (opcional, si no usas sudo):

   sudo usermod -a -G libvirt $USER
   # Reinicia la sesión para aplicar cambios
   

5. Configurar permisos para crear discos virtuales:

VirtManager necesita crear discos en /var/lib/libvirt/images/ con permisos correctos. Para esto, configura el script helper con permisos sudo:

   # El script ya está en el proyecto
   chmod +x create_disk.sh
   
   # Configura sudoers para permitir crear discos sin contraseña
   echo "creylopez ALL=(ALL) NOPASSWD: /home/creylopez/virtmanager/create_disk.sh" | sudo tee /etc/sudoers.d/virtmanager
   
   # Verifica que la configuración sea correcta
   sudo visudo -c -f /etc/sudoers.d/virtmanager

Configuración del Servicio Systemd (Auto-inicio)

Para que VirtManager se inicie automáticamente con el sistema:

1. Crea el archivo de servicio:

   sudo tee /etc/systemd/system/virtmanager.service > /dev/null <<EOF
   [Unit]
   Description=VirtManager API
   After=network.target libvirtd.service
   
   [Service]
   Type=simple
   User=root
   WorkingDirectory=/home/creylopez/virtmanager
   ExecStart=/home/creylopez/virtmanager/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
   Restart=always
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

2. Recarga systemd y habilita el servicio:

   sudo systemctl daemon-reload
   sudo systemctl enable virtmanager
   sudo systemctl start virtmanager
   

3. Verifica el estado:

   sudo systemctl status virtmanager
   

La aplicación estará disponible en http://localhost:8000 o http://tu-ip:8000.

Uso

Ejecución Manual (sin servicio)

Si prefieres ejecutar manualmente:

source venv/bin/activate
sudo uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Nota: Se requiere sudo porque libvirt necesita permisos de root.

Variables de Entorno

• LIBVIRT_IMAGES_PATH: Ruta para almacenar imágenes de disco (por defecto /var/lib/libvirt/images).

  export LIBVIRT_IMAGES_PATH=/ruta/a/imagenes
  

Endpoints de la API

VMs

• GET /: Página de inicio (interfaz web).
• GET /vms: Lista todas las VMs con estado, ID, nombre y puerto VNC si aplica.
• POST /vms?name={name}&memory={memory}&disk_size={disk_size}&iso={iso}: Crea una nueva VM.
  • name: Nombre de la VM.
  • memory: Memoria en MiB.
  • disk_size: Tamaño del disco en GB.
  • iso: Ruta al archivo ISO para instalación.
• GET /vms/{vm_name}/start: Inicia una VM por nombre.
• GET /vms/{vm_name}/stop: Detiene una VM por nombre.
• DELETE /vms/{vm_name}: Elimina una VM por nombre.
• PUT /vms/{vm_name}/boot-order: Cambia el orden de arranque.
  • Body JSON: {"order": ["hd", "cdrom"]} (ejemplo).

Discos

• POST /disks?name={name}&size={size}: Crea una imagen de disco.
  • name: Nombre del archivo (sin extensión).
  • size: Tamaño en GB.

ISOs

• GET /isos: Lista todas las ISOs subidas.
• POST /upload-iso: Sube un archivo ISO.
  • Body: Archivo multipart (file).
• DELETE /isos/{iso_name}: Elimina una ISO por nombre.

Consola

• GET /console/{vm_name}: Obtiene la URL para la consola web noVNC de la VM.

Interfaz Web

Accede a http://localhost:8000 en tu navegador.

• Lista de VMs: Tabla con estado (badges coloreados), acciones (iniciar/detener/eliminar/consola).
• Crear VM: Formulario para especificar nombre, memoria, disco e ISO (seleccionar de ISOs subidas).
• Set Boot Order: Selecciona una VM y define el orden de arranque (ej. "hd,cdrom").
• Upload ISO: Sube archivos ISO para usar en la creación de VMs.
• Manage ISOs: Tabla con ISOs subidas, opción para eliminar.
• Consola: Botón para abrir la consola web en una nueva pestaña (solo para VMs corriendo).

Documentación de la API

Accede a http://localhost:8000/docs para la documentación interactiva de Swagger UI.

Notas

• Las operaciones de VMs requieren que libvirt esté corriendo (sudo systemctl start libvirtd).
• Para crear discos virtuales, el script create_disk.sh debe estar configurado con permisos sudo sin contraseña (ver sección de instalación).
• Para crear VMs, asegúrate de que el usuario tenga permisos en /var/lib/libvirt/images o ajusta LIBVIRT_IMAGES_PATH.
• La consola web usa websockify para proxy VNC a WebSocket.
• El servicio systemd ejecuta como root para acceso completo a libvirt.
• Si recibes error "undefined" al crear una VM, verifica que:
  1. El script create_disk.sh tenga permisos de ejecución (chmod +x create_disk.sh)
  2. Esté configurado en sudoers correctamente
  3. Los permisos de /var/lib/libvirt/images/ sean correctos

Contribución

Siéntete libre de contribuir con mejoras o reportar issues.

Licencia

Este proyecto es de código abierto. Ajusta según tus necesidades.