Kueue v0.20.2: What's New and How to Upgrade
Kueue v0.20.2 patch release notes: KueueViz pod-group dashboard, quota bypass fix, metrics leaks fixed, and upgrade steps.
💡 Quick Answer: Kueue v0.20.2 is a patch release on the 0.20 line with one small KueueViz feature and ~20 bug fixes, including a quota-bypass fix for Pod groups and several Prometheus metric-leak fixes. Upgrade is a straightforward
helm upgrade/kubectl apply, but read thev0.19.0andv0.20.0release notes first if you’re crossing those minor versions.
The Problem
Teams running Kueue for batch/AI job queueing need to know whether a patch release contains fixes worth taking immediately — especially anything touching quota accounting, admission correctness, or observability (metrics used for autoscaling/capacity dashboards). v0.20.2 bundles several of these.
The Solution
Apply v0.20.2. It’s a drop-in patch upgrade for anyone already on the 0.20.x line (no CRD schema changes called out). If you’re coming from an older minor version, Kueue’s release notes explicitly require reading the intermediate .0 minor release notes first.
What’s New
Feature
- KueueViz: the workloads dashboard now shows the Pods belonging to pod-group Workloads, including
StatefulSetandLeaderWorkerSetworkloads (#17186).
Notable bug fixes (operator-relevant)
- Security/quota bypass (Pods): a Pod could bypass ClusterQueue quota by setting the
kueue.x-k8s.io/role-hashannotation to another role’s value and run an oversized Pod under that role’s reservation. Kueue now re-verifies each Pod against its PodSet’s effective spec before ungating it; a Pod that doesn’t fit stays gated and emits a Warning event instead of admitting over-quota (PR referenced in release, no number given in notes — see release page). - Pod/AdmissionCheck deadlock: with the Alpha
SkipReassignmentForPodOwnedWorkloadsfeature enabled, single-Pod Workloads preempted/evicted while scheduling-gated (e.g. pending AdmissionCheck) could get stuck forever withRequeued=False. Fixed, and Workloads already stuck in this state are automatically requeued on upgrade (#17173). - DRA: a Workload updated mid-scheduling could be requeued with quota charged against its previous spec, causing over/under-admission. Now handed back to the workload controller to recompute (#17208).
- FairSharing: workloads within nominal quota were incorrectly preempted when the ClusterQueue borrowed on an uncontested flavor or within an internal sub-cohort (#17031).
- JobSet: an evicted Workload could keep quota reserved (and never requeue) if a JobSet restart recreated already-succeeded child Jobs (#17215).
- Observability: stale Prometheus series after ClusterQueue deletion/move for
kueue_cluster_queue_weighted_share,kueue_replaced_workload_slices_total,kueue_cohort_subtree_quota,kueue_cohort_subtree_resource_reservations, plus stale gauge series after custom-label updates on ClusterQueue/LocalQueue (#17239, #17219, #16941). If you alert on these metrics, expect cleaner series after upgrade — don’t be surprised if old series disappear. - CLI (
kueuectl): fixedcreate clusterqueuerejecting hyphenated resource names (#16987),list workloadfailing on Workloads with emptyspec.queueName(#16986),versionprinting only the client version under non-default Helm release names (#16953), duplicate rows inlist workload --forpagination (#17084), and unnecessary remote lookups increate localqueue --dry-run=client(#17109). - Configuration validation:
admissionFairSharing.usageSamplingIntervalandadmissionFairSharing.resourceWeightsvalidation errors now report the offending field correctly (#16943).
⚠️ The upstream release notes text was truncated mid-sentence for one entry describing an Alpha feature gate controlling the role-hash check (“The check is controlled by the Alpha PodI…”). Check the release page for the full, untruncated wording and exact feature-gate name before relying on it in automation.
Upgrade Steps
Required reading first if you’re crossing minor versions:
- v0.19.0 release notes
- v0.20.0 release notes
- v0.20.1 release notes (patch line you’re crossing)
Option A — Helm:
helm upgrade --install kueue oci://registry.k8s.io/kueue/charts/kueue \
--version 0.20.2 \
--namespace kueue-system \
--create-namespaceOption B — kubectl manifest:
kubectl apply --server-side -f \
https://github.com/kubernetes-sigs/kueue/releases/download/v0.20.2/manifests.yamlUpgrade kueuectl (CLI):
kubectl krew upgrade kueue
# or download the binary directly
curl -LO https://github.com/kubernetes-sigs/kueue/releases/download/v0.20.2/kubectl-kueue-linux-amd64
chmod +x kubectl-kueue-linux-amd64 && sudo mv kubectl-kueue-linux-amd64 /usr/local/bin/kubectl-kueueVerify
# Controller manager is on the new image/tag
kubectl get deployment kueue-controller-manager -n kueue-system \
-o jsonpath='{.spec.template.spec.containers[0].image}'
# Pods healthy
kubectl get pods -n kueue-system
# CLI reports matching server/client versions
kueuectl version
# Spot-check that previously stuck Pod-group Workloads (if any) requeued
kubectl get workloads -A -o json | \
jq '.items[] | select(.status.conditions[]?.type=="Requeued" and .status.conditions[]?.status=="False")'Common Issues
- Dashboards show fewer metric series after upgrade: expected — stale gauge/counter series from deleted ClusterQueues or label updates are now correctly garbage-collected (#17239, #17219, #16941). Update alert thresholds if they depended on the stale series lingering.
- Previously-stuck Workloads suddenly move: Workloads parked with
Requeued=Falsedue to theSkipReassignmentForPodOwnedWorkloadsbug are auto-requeued on upgrade (#17173) — expect a short burst of scheduling activity right after rollout. - Skipping the
.0minor notes: if you jump from, say, v0.18.x straight to v0.20.2, you’ll miss breaking changes introduced in v0.19.0/v0.20.0. Always read those first.
Best Practices
- Pin the exact Kueue version in Helm/GitOps manifests (
--version 0.20.2) rather than trackinglatest. - Treat the role-hash quota-bypass fix as a security patch for multi-tenant clusters running Pod-group workloads — prioritize this upgrade on shared clusters.
- Audit any custom Prometheus alerting rules referencing
kueue_cluster_queue_weighted_share,kueue_cohort_subtree_quota, orkueue_cohort_subtree_resource_reservationsafter upgrading, since stale series cleanup changes cardinality. - If you enable Alpha feature gates (
SkipReassignmentForPodOwnedWorkloads, admission fair sharing), re-test in a staging cluster before promoting — these remain under active bugfixing. - Keep
kueuectlin sync with the controller version to avoid the version-mismatch CLI bug fixed in #16953.

Recommended
Kubernetes Recipes — The Complete Book100+ production-ready patterns with detailed explanations, best practices, and copy-paste YAML. Everything in one place.
Get the Book →