Kueue: why your Kubernetes job is still pending

If you run Kueue, a pending Kubernetes job is not necessarily broken. You submit a training run or a batch inference job, wait for Pods, and nothing shows up: no application logs, sometimes no Pod to inspect at all. In a Kueue-managed cluster that is often expected behaviour. The job stays suspended until Kueue decides whether it may use the resources it asked for.

On October 14, 2026, the official Kubernetes blog introduced the Kueue plugin for Headlamp, released as 0.1.0-alpha. It does not change how Kueue works. What it changes is how quickly a human can read the decision path that leads to a job being admitted, or held back. For teams sharing GPUs across several projects, that is where the hours go.

The context

Kueue is a job queueing system for Kubernetes, developed under the Kubernetes SIGs. It does not replace the scheduler. It decides when a job is allowed to start, based on quotas, queue policies and the other jobs waiting. As long as the answer is no, the job stays suspended.

A handful of objects matter for the rest of this article:

• Workload: the object Kueue creates to represent a job's resource request and admission state.
• LocalQueue: the namespace-scoped entry point a job is submitted to.
• ClusterQueue: the cluster-level quota pool and admission policy, shared by one or more LocalQueues.
• ResourceFlavor: a class of compute, such as GPU nodes, described through labels, taints or topology.
• Cohort: a group of ClusterQueues that can lend each other unused quota.

Headlamp is the extensible web UI for Kubernetes that is gradually taking over from the old Dashboard. Plugins add dedicated views for ecosystem tools.

Admission is not scheduling, and that changes the investigation

The single most useful idea in the Kubernetes blog post is that Kueue and the scheduler answer two different questions.

• Kueue admission: should this Workload start now, given queue policy, quota, ResourceFlavors, admission checks and the other Workloads waiting?
• Pod scheduling: once the Workload is admitted and the job resumes, which nodes can run its Pods?

That boundary decides where you look. If the Workload is not admitted, the answer lives in your Kueue configuration. If it is admitted but its Pods are still Pending, the scheduler is your suspect: node capacity, affinity, taints and tolerations, topology constraints, persistent volume binding or image pull failures.

A lot of time is lost because people reach for kubectl describe pod when no Pod has been created yet. The first question is not "why is my Pod pending?" but "has Kueue admitted my Workload?".

What the Kueue plugin for Headlamp shows

Version 0.1.0-alpha adds read-only views to Headlamp for Kueue v1beta2 objects: Cohorts, ClusterQueues, LocalQueues, ResourceFlavors and Workloads. The workflow is to start from the Workload and follow links, instead of rebuilding the admission path from several commands and large YAML dumps.

Start from the Workload

The Kueue Workloads list already gives a useful first pass: LocalQueue, priority, active, admitted and finished state, a readable status (Admitted, Finished, Inadmissible) and age. The detail page puts two conditions front and centre:

• Admitted=True: Kueue has admitted the Workload and the job can resume. Any Pod still Pending is a scheduling issue.
• QuotaReserved=False with a reason such as Pending: Kueue could not reserve quota, and the condition message says why.

An Inadmissible status means the Workload cannot fit the current queue setup: an uncovered resource, an unsuitable ResourceFlavor, a stopped queue or a blocking admission check. Recent events sit on the same page and show what Kueue tried.

Compare the request with the quota

The plugin lists PodSets and requested resources: Pod count, CPU, memory. The total is what counts, because Kueue evaluates the request as a whole. A job with parallelism: 3 and one CPU per Pod asks for three CPUs, not one.

From the Workload, a link leads to the LocalQueue (its status, its ClusterQueue, pending and admitted counts), then on to the ClusterQueue. That is where the answer usually is: covered resources, nominal quota per ResourceFlavor, current reservations, borrowing and lending limits, queueing strategy, preemption and fair-sharing settings.

In the Kubernetes blog example, the ClusterQueue offers two CPUs and two Pod slots, while the Workload asks for three of each. Kueue keeps the job suspended. This is an admission capacity problem, not a scheduler failure.

ResourceFlavor and Cohort for GPU cases

Quota is not always a single pool. When the condition mentions flavor assignment, or the job needs a specific hardware class such as GPU nodes, the ResourceFlavor link shows how that class is defined. If the ClusterQueue belongs to a Cohort, its page shows member queues, borrowing limits and fair sharing. That lets you separate three causes: no quota of its own, not enough to borrow, or no suitable flavor.

What the alpha does not do yet

The Kubernetes blog is explicit about the scope of this first release:

• views are read-only, with no plugin-specific create, edit, pause, resume or delete flows;
• Workload owner references are shown as text and are not clickable yet;
• what you see depends on the Kubernetes permissions of the identity Headlamp uses;
• metrics and a visual relationship map are possible follow-ups, not features of this release.

Nor does the plugin replace the command line. For scripts, exact output and GitOps workflows, kubectl and the kubectl-kueue plugin remain the right tools. What it replaces is the repetitive navigation of an interactive investigation. Source code, README and sample manifests to reproduce the scenario live in the Headlamp plugins repository.

What this means for AI teams

As soon as several projects share a GPU cluster, Kueue becomes hard to live without: without a queue, jobs fight over nodes and the largest ones starve everyone else. But the queue also adds opacity. A data scientist whose training run "will not start" opens a ticket, and the platform team has to piece together the state of four or five objects to answer.

The Kueue plugin for Headlamp lowers that diagnostic cost. We see three practical consequences.

Make diagnosis self-service. With a properly scoped read-only identity, ML teams can check for themselves whether their Workload is admitted and why not, without going through the platform team. That means granting read access to Kueue objects, and nothing more.

Write the admission/scheduling rule into your runbook. "Not admitted: look at Kueue. Admitted but Pods pending: look at the scheduler." It is the rule that prevents the most wild-goose chases.

Treat quota sizing as governance. When a job is Inadmissible because it asks for more than its ClusterQueue's nominal quota, the real question is a policy one: raise the quota, allow borrowing through a Cohort, or split the job? The plugin makes those trade-offs visible. It does not make them for you.

For a production platform, we would keep kubectl and the Kueue troubleshooting guide as the source of truth, and use Headlamp as the front door for day-to-day questions. Since the plugin is alpha, try it on a staging cluster first.

Key takeaways

• With Kueue, a pending job is often simply not admitted yet: no quota has been reserved.
• The Kueue plugin for Headlamp (0.1.0-alpha, announced on 14 October 2026) links Workload, LocalQueue, ClusterQueue, ResourceFlavor and Cohort into one investigation.
• The key rule: not admitted, check Kueue; admitted but Pods pending, check the scheduler.
• The alpha is read-only and does not replace kubectl for scripts and GitOps.
• On shared GPU clusters, it is an easy way to let ML teams diagnose Kueue admission on their own.

Industrialising AI agents? SeedVision offers 3-5 day AI audits and 15-30 day production rollouts. See the packages or book a 30-min call.

Cover photo: Photo by İsmail Enes Ayhan on Unsplash.