Kueue : pourquoi votre job Kubernetes reste en attente

Avec Kueue, un job Kubernetes qui reste en attente n'est pas forcément en panne. Vous lancez un entraînement ou un batch d'inférence, vous attendez que les Pods apparaissent, et rien ne se passe : pas de logs applicatifs, parfois même pas de Pod à inspecter. Dans un cluster géré par Kueue, c'est souvent un comportement normal. Le job est suspendu tant que Kueue n'a pas décidé s'il peut consommer les ressources demandées.

Le 14 octobre 2026, le blog officiel de Kubernetes a présenté le plugin Kueue pour Headlamp, publié en version 0.1.0-alpha. Il ne change rien au fonctionnement de Kueue : il rend lisible le chemin de décision qui mène à l'admission, ou au blocage, d'un job. Pour les équipes qui partagent des GPU entre plusieurs projets, c'est un gain de temps réel au moment du diagnostic.

Le contexte

Kueue est un système de mise en file d'attente pour Kubernetes, développé dans le cadre des projets SIG. Il ne remplace pas le scheduler : il décide quand un job a le droit de démarrer, en fonction de quotas, de politiques de file et des autres jobs en attente. Tant que la réponse est non, le job reste suspendu.

Quelques notions reviennent tout au long de cet article :

• Workload : l'objet que Kueue crée pour représenter la demande de ressources d'un job et son état d'admission.
• LocalQueue : la file d'entrée, propre à un namespace, dans laquelle un job est soumis.
• ClusterQueue : le pool de quota au niveau du cluster, avec ses règles d'admission, partagé par une ou plusieurs LocalQueues.
• ResourceFlavor : une classe de ressources (par exemple des nœuds GPU), décrite par des labels, des taints ou une topologie.
• Cohort : un groupe de ClusterQueues qui peuvent se prêter le quota qu'elles n'utilisent pas.

Headlamp est l'interface web extensible de Kubernetes, qui remplace progressivement l'ancien Dashboard. Ses plugins ajoutent des vues dédiées à des outils de l'écosystème.

Kueue n'est pas le scheduler : la distinction qui change le diagnostic

Le point le plus utile de l'article du blog Kubernetes tient en une règle : Kueue et le scheduler répondent à deux questions différentes.

• L'admission par Kueue : ce Workload doit-il démarrer maintenant, compte tenu de la politique de file, du quota, des ResourceFlavors, des contrôles d'admission et des autres Workloads en attente ?
• Le placement par le scheduler : une fois le Workload admis et le job relancé, sur quels nœuds ses Pods peuvent-ils tourner ?

Cette frontière oriente toute l'enquête. Si le Workload n'est pas admis, le problème est dans la configuration de Kueue. S'il est admis mais que ses Pods restent en Pending, il faut regarder du côté du scheduler : capacité des nœuds, affinités, taints et tolérances, contraintes de topologie, volumes persistants ou échec de téléchargement d'image.

Beaucoup d'équipes perdent du temps parce qu'elles commencent par kubectl describe pod alors qu'aucun Pod n'a encore été créé. La bonne première question n'est pas « pourquoi mon Pod est-il en attente ? » mais « Kueue a-t-il admis mon Workload ? ».

Ce que montre le plugin Kueue pour Headlamp

La version 0.1.0-alpha ajoute à Headlamp des vues en lecture seule pour les objets Kueue v1beta2 : Cohorts, ClusterQueues, LocalQueues, ResourceFlavors et Workloads. L'idée est de partir du Workload et de suivre des liens, au lieu de reconstituer le chemin d'admission à partir de plusieurs commandes et de gros objets YAML.

Partir du Workload

Dans la section Kueue, la vue Workloads affiche déjà, pour chaque entrée, la LocalQueue, la priorité, l'état actif, admis ou terminé, un statut lisible (Admitted, Finished, Inadmissible) et l'âge. La page de détail met en avant deux conditions :

• Admitted=True : Kueue a admis le Workload, le job peut reprendre. Tout Pod encore en Pending relève du scheduler.
• QuotaReserved=False, avec une raison comme Pending : Kueue n'a pas pu réserver de quota, et le message de la condition explique pourquoi.

Le statut Inadmissible signale que le Workload ne rentre pas dans la configuration actuelle : ressource non couverte, ResourceFlavor inadapté, file arrêtée ou contrôle d'admission bloquant. La même page affiche aussi les événements récents, qui montrent ce que Kueue a tenté.

Comparer la demande et le quota

Le plugin affiche les PodSets et les ressources demandées : nombre de Pods, CPU, mémoire. Le détail compte, parce que Kueue évalue la demande totale. Un job avec parallelism: 3 et un CPU par Pod demande trois CPU, pas un.

Depuis le Workload, un lien mène à la LocalQueue (son état, sa ClusterQueue, le nombre de Workloads en attente ou admis), puis à la ClusterQueue. C'est là que se lit la réponse : ressources couvertes, quota nominal par ResourceFlavor, réservations en cours, limites d'emprunt et de prêt, stratégie de file, réglages de préemption et de partage équitable.

Dans l'exemple du blog Kubernetes, la ClusterQueue offre un quota de deux CPU et deux emplacements de Pods, alors que le Workload en demande trois de chaque. Kueue laisse donc le job suspendu. C'est un problème de capacité d'admission, pas un échec du scheduler.

ResourceFlavor et Cohort pour les cas GPU

Le quota n'est pas toujours un seul pool. Quand la condition mentionne l'attribution d'un flavor, ou que le job exige une classe matérielle comme des nœuds GPU, le lien vers le ResourceFlavor permet de vérifier comment cette classe est définie. Si la ClusterQueue appartient à une Cohort, sa page montre les files membres, les limites d'emprunt et le partage équitable. On peut alors distinguer trois causes : pas de quota propre, impossibilité d'emprunter assez, ou aucun flavor adapté.

Les limites de la version alpha

Le blog Kubernetes est clair sur le périmètre de cette première version :

• les vues sont en lecture seule : pas de création, modification, pause, reprise ou suppression propres au plugin ;
• les références de propriétaire d'un Workload s'affichent en texte et ne sont pas encore cliquables ;
• ce que l'on voit dépend des droits Kubernetes de l'identité utilisée par Headlamp ;
• les métriques et une carte visuelle des relations sont des pistes pour la suite, pas des fonctions de cette version.

Le plugin ne remplace pas non plus la ligne de commande. Pour les scripts, les sorties exactes et les workflows GitOps, kubectl et le plugin kubectl-kueue restent les bons outils. Il remplace surtout la navigation répétitive d'une enquête interactive. Le code source, le README et des manifestes d'exemple pour reproduire le scénario sont disponibles dans le dépôt des plugins Headlamp.

Ce que ça change pour les équipes IA

Dès qu'une équipe partage un cluster de GPU entre plusieurs projets, Kueue devient vite indispensable : sans file d'attente, les jobs se disputent les nœuds et les plus gros bloquent tout le monde. Mais la file d'attente ajoute une couche d'opacité. Un data scientist qui voit son entraînement « ne pas démarrer » ouvre un ticket, et l'équipe plateforme doit reconstituer l'état de quatre ou cinq objets pour répondre.

Le plugin Kueue pour Headlamp réduit ce coût de diagnostic. Nous en retenons trois conséquences pratiques.

Rendre le diagnostic autonome. Avec une identité en lecture seule bien configurée, les équipes ML peuvent vérifier elles-mêmes si leur Workload est admis et pourquoi il ne l'est pas, sans passer par l'équipe plateforme. Cela suppose de donner les droits de lecture sur les objets Kueue, et seulement ceux-là.

Documenter la règle admission/scheduling. La distinction « non admis : regarder Kueue ; admis mais Pods en attente : regarder le scheduler » mérite d'apparaître dans le runbook de la plateforme. C'est la règle qui évite le plus de fausses pistes.

Vérifier le dimensionnement des quotas. Quand un job reste Inadmissible parce qu'il demande plus que le quota nominal de sa ClusterQueue, la question devient une question de gouvernance : faut-il augmenter le quota, autoriser l'emprunt via une Cohort, ou découper le job ? Le plugin rend ces arbitrages visibles, mais ne les tranche pas.

Pour une plateforme en production, nous recommandons de garder kubectl et la documentation de dépannage de Kueue comme référence, et d'utiliser Headlamp comme porte d'entrée pour les questions du quotidien. Le plugin étant en alpha, il est plus prudent de l'évaluer d'abord sur un cluster de préproduction.

En bref

• Avec Kueue, un job en attente est souvent simplement non admis : Kueue n'a pas encore réservé de quota.
• Le plugin Kueue pour Headlamp (0.1.0-alpha, présenté le 14/10/2026) relie Workload, LocalQueue, ClusterQueue, ResourceFlavor et Cohort dans une seule enquête.
• La règle clé : non admis, regarder Kueue ; admis mais Pods en attente, regarder le scheduler.
• La version alpha est en lecture seule et ne remplace pas kubectl pour les scripts et le GitOps.
• Pour les clusters GPU partagés, c'est un moyen simple de rendre les équipes ML autonomes sur le diagnostic de Kueue.

Vous industrialisez vos agents IA ? SeedVision propose des audits IA en 3-5 jours et des forfaits de mise en production de 15 à 30 jours. Voir les packages ou réserver un appel de 30 min.

Photo de couverture : Photo by İsmail Enes Ayhan on Unsplash.