Introducción
Cuando un Job de Kubernetes permanece en estado Pending durante minutos, la reacción instintiva es inspeccionar los eventos del Pod o revisar los logs del scheduler. Sin embargo, en clusters gestionados por Kueue, esta aproximación puede ser un callejón sin salida. Es posible que el Job no tenga ni siquiera un Pod creado, o que este esté en un estado inicial que no refleja la verdadera razón del bloqueo. La pregunta crítica no es solo «¿Por qué el Pod está pendiente?», sino primero «¿Ha admitido Kueue el Workload?».
En arquitecturas con batch workload management, Kueue actúa como una capa de admisión previa al scheduler de Kubernetes. Si Kueue decide que el Job no puede usar los recursos solicitados debido a políticas de cuota, colas o flavors, el Job permanece suspendido (suspended) y nunca llega al etapa de scheduling de nodos. Reconstruir esta lógica de admisión desde la línea de comandos requiere correlacionar múltiples objetos YAML (Workload, LocalQueue, ClusterQueue, ResourceFlavor). Este tutorial detalla cómo utilizar el plugin de Headlamp para visualizar este camino de admisión de forma inmediata, permitiendo identificar si el bloqueo es una cuestión de capacidad de cola o de asignación de nodos.
Qué es y para qué sirve
Kueue introduce el concepto de Workload como la representación de la solicitud de recursos y el estado de admisión de un Job. Mientras que el scheduler de Kubernetes se encarga de «¿qué nodo puede ejecutar este Pod?», Kueue responde a «¿debería este Workload comenzar ahora, considerando la política de cola, la cuota, los ResourceFlavors y otros Workloads en espera?». Esta distinción es fundamental porque cambia el vector de diagnóstico. Si el Workload no ha sido admitido, cualquier análisis del scheduler será irrelevante; el problema reside en la configuración de Kueue.
El plugin de Kueue para Headlamp (versión alpha actual) expone estos recursos en la interfaz gráfica. En lugar de ejecutar kubectl get workloads -o yaml y parsear manualmente las condiciones, el plugin permite navegar desde el Workload hacia atrás, siguiendo los enlaces a su LocalQueue, ClusterQueue, ResourceFlavor y Cohort. Esto proporciona una visión holística de la capacidad disponible frente a la solicitada. El objetivo es reducir el tiempo de resolución de incidentes (MTTR) al ofrecer lecturas claras de las condiciones QuotaReserved y Admitted, y al visualizar los límites de cuota en tiempo real dentro de la UI.
Prerequisitos
Para seguir esta guía, necesitas un entorno con las siguientes especificaciones exactas:
- Cluster Kubernetes: Versión 1.25 o superior.
- Kueue: Instalado y operativo. El plugin soporta recursos v1beta2.
- Headlamp: Instalación funcional (vía Helm o contenedor).
- Plugin Kueue para Headlamp: Versión 0.1.0-alpha o superior instalada en la instancia de Headlamp.
- Permisos RBAC: El usuario de Kubernetes utilizado para acceder a Headlamp debe tener permisos de lectura (get, list, watch) sobre los recursos de Kueue: Workloads, LocalQueues, ClusterQueues, ResourceFlavors y Cohorts.
Nota: El plugin actual es de solo lectura para la lógica de admisión de Kueue. No permite crear, editar, detener ni reanudar Workloads desde la interfaz; para eso, se siguen utilizando las acciones estándar de YAML de Headlamp o kubectl.
Guía paso a paso
1. Identificar el Workload asociado al Job
En la interfaz de Headlamp, navega a la sección Kueue → Workloads. Filtra por el namespace donde se lanzó el Job. Si no ves ningún Workload, verifica tres cosas: que el namespace sea correcto, que el Job haya sido enviado a un LocalQueue (y no al default si el default está configurado para ignorar admisiones) y que tu identidad tenga permisos para listar Workloads.
En la tabla de listados, busca el Workload cuyo nombre contenga el nombre del Job. Presta atención a las columnas clave:
- Active: Si el Workload está activo.
- Admitted: Estado booleano de admisión.
- Status: Mensajes como Admitted, Finished, Inadmissible o Pending.
Si el estado es Inadmissible o Pending, procedemos a la inspección detallada.
2. Analizar las Condiciones del Workload
Abre el detalle del Workload. No te detengas en el YAML completo. Busca la sección Conditions. Las dos condiciones más importantes para el diagnóstico son QuotaReserved y Admitted.
- Si Admitted=True: Kueue ha dado luz verde al Job. El Job debería reanudarse. Si los Pods siguen Pending, el problema es de scheduling (nodos, taints, etc.), no de Kueue. Sal de esta guía y revisa los eventos del Pod.
- Si QuotaReserved=False con motivo Pending: Kueue no ha reservado la cuota. El mensaje de la condición es la primera pista real. Por ejemplo, «insufficient CPU quota».
- Si Inadmissible: El Workload no cabe en la configuración actual de la cola. Puede ser un recurso no cubierto, un ResourceFlavor incompatible o una cola detenida.
Revisa también la sección Events en la página del Workload. Las condiciones muestran el estado actual, pero los eventos indican qué intentos de admisión fallaron recientemente y por qué.
3. Verificar la solicitud de recursos (PodSets)
En la misma página del Workload, inspecciona los PodSets. Kueue evalúa los recursos totales solicitados por el Job, no solo por un Pod individual. Un Job con parallelism: 3 y 1 CPU por Pod solicita 3 CPUs en total.
Asegúrate de que la lectura de Headlamp refleja esto. Si ves que el Workload solicita 3 CPUs y 600 MiB de memoria, anota estos números. Este es el «costo» que la cola debe pagar para admitir el Job.
4. Trazar el camino hacia la Cola (LocalQueue y ClusterQueue)
Desde el detalle del Workload, haz clic en el enlace del LocalQueue. Esta es la entrada a nivel de namespace.
- Verifica que el LocalQueue esté Active y no detenido.
- Revisa los contadores de Workloads pendientes y admitidos en esta cola.
Si la cola está activa, sigue el enlace al ClusterQueue. Aquí es donde reside la cuota real del cluster. Compara la solicitud del Workload (3 CPUs) con la Nominal Quota definida en el ClusterQueue para el ResourceFlavor correspondiente.
En un caso típico de bloqueo por cuota, el ClusterQueue podría tener una cuota nominal de 2 CPUs. Como el Workload pide 3, el ClusterQueue no puede reservar la cuota. La página del ClusterQueue mostrará explícitamente la cuota disponible, el uso actual y los límites de préstamo (borrowing). Si la cuota es insuficiente y el préstamo está deshabilitado o agotado, el resultado es inevitable: el Job permanece suspendido.
5. Revisar ResourceFlavors y Cohorts
Si el mensaje de condición menciona ResourceFlavor, haz clic en el enlace del ResourceFlavor desde el ClusterQueue. Los flavors representan clases de cómputo (etiquetas de nodo, taints, GPUs). Asegúrate de que el Job no esté pidiendo un flavor que no tenga cuota asignada en el ClusterQueue, o que los nodos con ese flavor estén saturados.
Si el ClusterQueue pertenece a una Cohort, sigue ese enlace. Las Cohorts permiten compartir cuota no utilizada entre ClusterQueues. La página de la Cohort mostrará los límites de préstamo y la cuota total disponible para el grupo. Esto responde a la pregunta: «¿Está bloqueado porque el ClusterQueue individual tiene poca cuota, o porque la Cohort entera está agotada?».
Consideraciones y buenas prácticas
La versión actual del plugin es alpha. Los enlaces de «owner references» (como el Job padre de un Workload) pueden mostrarse como texto (Kind/name) pero no ser clicables, dependiendo de la versión exacta. Utiliza la búsqueda de la tabla con el nombre del Job como workaround.
Es crucial no confundir el estado Pending de un Pod con un fallo de Kueue. Si el Workload está Admitted=True, el Job ya pasó el filtro de capacidad. Cualquier demora posterior es responsabilidad del scheduler de Kubernetes o de la infraestructura subyacente (ej. autoscaling de nodos). Kueue gestiona la admisión lógica, no la disponibilidad física de hardware.
Para entornos de producción, configura alertas basadas en la métrica kueue_workload_admission_wait_seconds. Si este tiempo supera un umbral esperado, probablemente haya una saturación de cuota en los ClusterQueues críticos, lo cual es un indicador de salud del sistema de batch que debe monitorearse proactivamente.
Conclusión
Diagnósticar Jobs suspendidos en Kueue requiere cambiar el enfoque del Pod al Workload. El plugin de Headlamp simplifica este proceso al visualizar la cadena de admisión: Workload → LocalQueue → ClusterQueue → ResourceFlavor. Al leer correctamente las condiciones QuotaReserved y comparar la solicitud de PodSets contra la cuota nominal y los límites de préstamo, los ingenieros de plataforma pueden determinar inmediatamente si el problema es de configuración de cuotas, de flavors de hardware o de scheduling de nodos. Esta claridad evita horas perdidas investigando logs del scheduler cuando la raíz del problema es una política de admisión correcta pero restrictiva.
Fuentes
https://kubernetes.io/blog/2026/10/14/tracing-kueue-admission-with-headlamp/