Skip to main content

Admission fair sharing

Use admission fair sharing to fairly distribute workloads across local Queues that share a single ClusterQueue.

You can balance workload admission by prioritizing workloads from local Queues that have used fewer resources historically. With admission fair sharing, you can track usage over time with a configurable decay function and apply admission penalties when workloads are admitted.

When multiple tenants share a single ClusterQueue, some tenants risk resource starvation. Admission fair sharing adresses this issue by meeting the following requirements:

Enforce multi-tenant fairness (business critical)
Ensure fair distribution of cluster resources across all tenants based on their usage history.
Improve service predictability
Guarantee each tenant gets a consistent share of resources, reducing latency spikes and preventing starvation.
Enable scalable governance
Complement static quotas with dynamic, usage-based admission ordering that adapts as tenant demand changes.

Configuring the Red Hat build of Kueue instance for admission fair sharing​

Configure Red Hat build of Kueue admission fair sharing using either the Default or Custom configuration.

Procedure

  1. Choose the configuration type you want to use:
    • Default: Uses predefined values.
    • Custom: Uses values that you specify.
  2. Apply your chosen configuration:

    • Use the following command to create a Default configuration:

      $ oc patch kueue.kueue.openshift.io/cluster --type=merge -p \ '{"spec":{"config":{"admissionFairSharing":{"configuration":"Default","custom":null}}}}'
      Example of Kueue instance output
      config:
          admissionFairSharing:
            configuration: Default

    • Use the following command to create a Custom configuration that applies values that you specify:

      $ oc patch kueue.kueue.openshift.io/cluster --type=merge -p \ '{"spec":{"config":{"admissionFairSharing":{"configuration":"Custom","custom":{"usageHalfLifeTimeSeconds":10,"usageSamplingIntervalSeconds":10,"resourceWeights":[{"name":"cpu","weight":"2.0"}]}}}}}'
      Example of Kueue instance output
        config:
          admissionFairSharing:
            configuration: Custom
            custom:
              resourceWeights:
              - name: cpu
                weight: "2.0"
              usageHalfLifeTimeSeconds: 10
              usageSamplingIntervalSeconds: 10
      resourceWeights
      Assigns weights to resources. The higher the weight, the higher the penalty.
usageHalfLifeTimeSeconds
The time in seconds after which the current usage will decrease by half. That is, it controls how long the past consumption should impact future admission.
usageSamplingIntervalSeconds
The frequency in seconds that Red Hat build of Kueue updates the consumedResources component in the FairSharingStatus component.

Set resource weights​

Resources measured in bytes, like memory, require scaled-down resourceWeights values. Kubernetes represents memory in bytes, creating values that are billions of times larger than CPU core counts.

This numeric difference makes CPU weights ineffective unless you scale memory weights down. Without this adjustment, the raw byte value of these resources will numerically dominate human-scale resources, such as CPU cores, by several orders of magnitude, effectively making their weights meaningless.

For example, if you want to achieve an effective memory weight of 1.0, you would need to instead specify 9.31e-10, which corresponds to 1.0 / 1,073,741,824.

Configuring a cluster queue for admission fair sharing​

Configure the admissionScope section in your ClusterQueue object to be UsageBasedAdmissionFairSharing.

Procedure

  • Specify UsageBasedAdmissionFairSharing as shown in the following example: 
    apiVersion: kueue.x-k8s.io/v1beta2
    kind: ClusterQueue
    metadata:
      name: shared-queue
    spec:
      namespaceSelector: {}
      admissionScope:
        admissionMode: UsageBasedAdmissionFairSharing
      resourceGroups:
        - coveredResources: ["cpu", "memory"]
          flavors:
            - name: afs-rf
              resources:
                - name: cpu
                  nominalQuota: 2
                - name: memory
                  nominalQuota: 2Gi

Configuring a local queue for admission fair sharing (optional)​

Optionally, you can configure fairSharing section in your LocalQueue object to adjust its weight in the fair sharing calculation. The higher the weight, the lower the penalty. For example, specifying a weight of 2 treats the queue as if it is used by half as many resources.

Procedure

  • Specify a weight value as shown in the following example: 
    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

Verifying the admission fair sharing status​

Check the admissionFairSharingStatus status in the local queue.

Procedure

  • Use the following command to verify the status of admission fair sharing:

    $ oc get lq <local-queue-name> -n <local-queue-namespace> -o jsonpath={.status.fairSharing}
    Example output
    {"admissionFairSharingStatus":{"consumedResources":{"cpu":"31999m"},"lastUpdate":"2025-06-03T14:25:15Z"},"weightedShare":0}