Admission Fair Sharing

Admission Fair Sharing

Admission Fair Sharing helps distribute resources fairly between multiple LocalQueues targeting the same ClusterQueue. It orders workloads based on the historical resource usage of their source LocalQueues, giving preference to those that have consumed less resources over time.

How it works

When multiple workloads compete for resources within a ClusterQueue:

1. Kueue tracks resource usage history for each LocalQueue
2. Workloads from LocalQueues with lower historical usage get admitted before those from high-usage queues
3. Usage values decay over time based on configurable parameters

Entry Penalty

To prevent exploitation where tenants could submit many workloads quickly before usage statistics are updated, Kueue applies an entry penalty to each workload that reaches the accounting anchor. This penalty is immediately added to the LocalQueue’s usage statistics. This ensures that even if a tenant submits multiple workloads rapidly, subsequent workloads will be properly prioritized based on the updated usage including the penalty.

For example, if Tenant A has low historical usage and Tenant B has high usage, but Tenant B submits 100 workloads simultaneously, without the entry penalty all 100 workloads might be admitted before the usage statistics update. With the entry penalty, each admitted workload immediately increases Tenant B’s usage statistics, so subsequent workloads from Tenant B will be properly deprioritized in favor of workloads from Tenant A.

Accounting anchor

For ClusterQueues that use UsageBasedAdmissionFairSharing, usage is accounted from the point a workload reserves quota: it contributes to fair-sharing usage as soon as it actively holds quota, even while its AdmissionChecks are pending, and its entry penalty settles at the same point. Every other ClusterQueue accounts from admission. The reported consumedResources does not update immediately, since it is a decaying average: it closes half of the remaining gap every usageHalfLifeTime.

Configuration

Kueue configuration

The following parameters can be configured in Kueue’s configuration .admissionFairSharing:

• usageHalfLifeTime: Controls how quickly historical usage decays
• usageSamplingInterval: How frequently usage is sampled
• resourceWeights: Relative importance of different resource types

Example configuration:

admissionFairSharing:
  usageHalfLifeTime: "168h"
  usageSamplingInterval: "5m"
  resourceWeights:
    cpu: 2.0 # cpu usage is twice more important than memory usage
    memory: 1.0

ClusterQueue configuration

Enable Admission Fair Sharing by adding an AdmissionScope to your ClusterQueue:

apiVersion: kueue.x-k8s.io/v1beta2
kind: ClusterQueue
metadata:
  name: sample-queue
spec:
  admissionScope:
    admissionMode: UsageBasedAdmissionFairSharing
  resources:
    # ...existing resource configuration...

LocalQueue configuration

You can define a fairSharing section in your LocalQueue to adjust its weight in the fair sharing calculation (defaults to 1):

apiVersion: kueue.x-k8s.io/v1beta2
kind: LocalQueue
metadata:
  name: team-a-queue
  namespace: team-a
spec:
  clusterQueue: shared-queue
  fairSharing:
    weight: "2"  # This queue will be treated as if it used half as many resources

Observability

You can track the historical resource usage of each LocalQueue in its status.FairSharing e.g. using command:

kubectl get lq user-queue -o jsonpath={.status.fairSharing}

Output should be similar to:

{"admissionFairSharingStatus":{"consumedResources":{"cpu":"31999m"},"lastUpdate":"2025-06-03T14:25:15Z"},"weightedShare":0}