OSDOCS-14877: Fair sharing Kueue docs

Author: abrennan89

_topic_maps/_topic_map.yml

@@ -55,6 +55,8 @@ Topics:
   File: configuring-quotas
 - Name: Using cohorts
   File: using-cohorts
+- Name: Configuring fair sharing
+  File: configuring-fairsharing
 ---
 Name: Support
 Dir: support

configure/configuring-fairsharing.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="configuring-fairsharing"]
+= Configuring fair sharing
+:context: configuring-fairsharing
+
+toc::[]
+
+Fair sharing is a preemption strategy that is used to achieve an equal or weighted share of borrowable resources between the tenants of a cohort. Borrowable resources are the unused nominal quota of all the cluster queues in a cohort.
+
+You can configure fair sharing by setting the `preemptionPolicy` value in the `Kueue` custom resource (CR) to `FairSharing`.
+
+include::modules/clusterqueue-share-value.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+* xref:../install/install-kueue.adoc#create-kueue-cr_install-kueue[Creating a `Kueue` custom resource]

modules/clusterqueue-share-value.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// * configure/configuring-fairsharing.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="clusterqueue-share-value_{context}"]
+= Cluster queue weights
+
+After you have enabled fair sharing, you must set share values for each cluster queue before fair sharing can take place. Share values are represented as the `weight` value in a `ClusterQueue` object.
+
+Share values are important because they allow administrators to prioritize specific job types or teams. Critical applications or high-priority teams can be configured with a weighted value so that they receive a proportionally larger share of the available resources. Configuring weights ensures that unused resources are distributed according to defined organizational or project priorities rather than on a first-come, first-served basis.
+
+The `weight` value, or share value, defines a comparative advantage for the cluster queue when competing for borrowable resources. Generally, {product-title} admits jobs with a lower share value first. Jobs with a higher share value are more likely to be preempted before those with lower share values.
+
+.Example cluster queue with a fair sharing weight configured
+[source,yaml]
+----
+apiVersion: kueue.x-k8s.io/v1beta1
+kind: ClusterQueue
+metadata:
+  name: example-queue
+spec:
+  namespaceSelector: {}
+  resourceGroups:
+  - coveredResources: ["cpu"]
+    flavors:
+    - name: default-flavor
+      resources:
+      - name: cpu
+        nominalQuota: 9
+  cohort: example-cohort
+  fairSharing:
+    weight: 2
+----
+
+[id="clusterqueue-share-value-zero_{context}"]
+== Zero weight
+
+A `weight` value of `0` represents an infinite share value. This means that the cluster queue is always at a disadvantage compared to others, and its workloads are always the first to be preempted when fair sharing is enabled.