1. Resolución de problemas y trampas operativas

En entornos de virtualización de misión crítica, los incidentes operativos deben diagnosticarse con rapidez y precisión técnica. Este módulo provee el catálogo de errores tipificados de NorTK VM bajo la anatomía de cuatro partes de IBM y expone las trampas operativas más frecuentes en entornos de producción.

1.1. Anatomía formal de diagnósticos

Todo evento crítico en NorTK VM se descompone en cuatro elementos:

Identificador único de mensaje: Código con formato NTK-VM-<NUMERO><SEVERIDAD>, donde E denota error crítico, W advertencia e I información.
Texto del mensaje: Descripción concisa y objetiva de la anomalía observada.
Explicación técnica: Desglose de las causas raíz comprobables en el hipervisor, almacenamiento o red.
Respuesta del operador: Pasos de remediación obligatorios y directos redactados en modo imperativo.

1.2. Catálogo de mensajes de error de NorTK VM

1.2.1. NTK-VM-0101E: Falló la inicialización del dominio QEMU por permiso denegado en la imagen de disco

Explicación: El proceso QEMU, confinado por las políticas sVirt de SELinux bajo la cuenta de servicio qemu, no tiene autorización para abrir o escribir en el archivo de imagen de disco. Esta condición se produce habitualmente cuando el archivo QCOW2 reside en una ruta no estándar sin el contexto de seguridad virt_image_t, o cuando los permisos de archivo en el sistema de archivos anfitrión no otorgan lectura/escritura al grupo qemu.
Respuesta del operador:
1. Restaure el contexto de seguridad de SELinux ejecutando restorecon -Rv /var/lib/libvirt/images o aplique la etiqueta correspondiente con semanage fcontext -a -t virt_image_t "/mnt/custom-storage(/.*)?" && restorecon -Rv /mnt/custom-storage.
2. Verifique la propiedad de los archivos ejecutando chown -R qemu:qemu /var/lib/libvirt/images.

1.2.2. NTK-VM-0204E: No se pudo conectar con el daemon libvirt en qemu:///system

Explicación: El cliente de administración (Cockpit, virt-manager o virsh) no puede establecer comunicación con el socket UNIX de libvirt (/run/libvirt/virtqemud-sock o /run/libvirt/libvirt-sock). Las causas probables son la detención del servicio del sistema o la falta de privilegios del usuario ejecutor en el grupo libvirt.
Respuesta del operador:
1. Inicie y habilite los sockets de libvirt ejecutando systemctl enable --now virtqemud.socket virtstoraged.socket virtnetworkd.socket.
2. Confirme que el usuario operador pertenece al grupo del sistema libvirt mediante usermod -aG libvirt <usuario>.
3. Cierre y vuelva a abrir su sesión de terminal o cliente gráfico para recargar los identificadores de grupo.

1.2.3. NTK-VM-0312E: La máquina virtual no responde al comando de congelamiento del sistema de archivos

Explicación: La solicitud de captura de instantánea consistente o respaldo falló al intentar ejecutar fsfreeze porque el daemon qemu-guest-agent no se encuentra en ejecución dentro del huésped, o el canal VirtIO serie org.qemu.guest_agent.0 no está configurado en el hardware virtual.
Respuesta del operador:
1. Acceda a la máquina virtual e inicie el servicio del agente mediante systemctl start qemu-guest-agent.
2. En virt-manager o en el XML del dominio, compruebe que existe un dispositivo de tipo canal con el nombre org.qemu.guest_agent.0.

1.3. Trampa operativa 1: Bloqueos de acceso a imágenes por SELinux

Síntoma: La máquina virtual no arranca desde virt-manager o Cockpit reportando un error genérico Permission denied en el descriptor del archivo ISO o disco virtual, a pesar de que el archivo posee permisos 777 o pertenece a root.
Causa raíz: En CentOS Stream, SELinux opera en modo Enforcing de manera obligatoria. El proceso QEMU está confinado por sVirt y tiene terminantemente prohibido acceder a archivos etiquetados como admin_home_t, user_home_t o default_t.
Prevención y remediación: Nunca almacene imágenes ISO o discos de máquinas virtuales en el directorio personal del usuario (como /home/administrador/ o /root/). Aloje todos los archivos de virtualización exclusivamente en rutas gestionadas por pools de libvirt o aplique la etiqueta virt_image_t.

1.4. Trampa operativa 2: Pérdida de conectividad por filtrado en el puente de red

Síntoma: Las máquinas virtuales conectadas a un puente Linux Bridge (br0) obtienen dirección IP pero no pueden comunicarse con otros servidores de la red física local, o pierden conectividad de forma intermitente.
Causa raíz: El módulo del kernel br_netfilter está activo y transfiere el tráfico de capa 2 del puente hacia la pila de filtrado de capa 3 de firewalld y nftables, bloqueando el tráfico entre puertos del puente que no coincide con las zonas del anfitrión.

Prevención y remediación:

Cargue el módulo del kernel br_netfilter de forma inmediata y persistente, y desactive el filtrado de iptables/nftables sobre el puente:

# echo "br_netfilter" > /etc/modules-load.d/br_netfilter.conf
# modprobe br_netfilter
# echo "net.bridge.bridge-nf-call-iptables = 0" > /etc/sysctl.d/99-netfilter-bridge.conf
# echo "net.bridge.bridge-nf-call-ip6tables = 0" >> /etc/sysctl.d/99-netfilter-bridge.conf
# sysctl --system

1.5. Trampa operativa 3: Máquinas virtuales no arrancan en el reinicio del servidor

Síntoma: Tras un reinicio programado del host anfitrión, las máquinas virtuales de producción permanecen apagadas y deben encenderse manualmente desde Cockpit.
Causa raíz: La bandera de autoinicio (autostart) no está activada en la configuración del dominio en libvirt, o la máquina virtual fue creada erróneamente en el contexto de usuario (qemu:///session) en lugar del contexto del sistema (qemu:///system).
Prevención y remediación:
Active el inicio automático permanente ejecutando:
# virsh autostart vm-app01.infra.nortk.com
Confirme que la bandera se encuentra activa mediante:
# virsh dominfo vm-app01.infra.nortk.com | grep Autostart
Salida esperada:
Autostart: enable