Merge pull request #94765 from abrennan89/cohort-concepts

OSDOCS-14894: Adding docs about cohorts

Author: abrennan89

_topic_maps/_topic_map.yml

@@ -53,6 +53,8 @@ Distros: openshift-kueue
 Topics:
 - Name: Configuring quotas
   File: configuring-quotas
+- Name: Using cohorts
+  File: using-cohorts
 ---
 Name: Develop
 Dir: develop

configure/using-cohorts.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="using-cohorts"]
+= Using cohorts
+:context: using-cohorts
+
+toc::[]
+
+You can use cohorts to group cluster queues and determine which cluster queues are able to share borrowable resources with each other.
+Borrowable resources are defined as the unused nominal quota of all the cluster queues in a cohort.
+
+Using cohorts can help to optimize resource utilization by preventing under-utilization and enabling fair sharing configurations.
+Cohorts can also help to simplify resource management and allocation between teams, because you can group cluster queues for related workloads or for each team.
+You can also use cohorts to set resource quotas at a group level to define the limits for resources that a group of cluster queues can consume.
+
+include::modules/clusterqueue-configuring-cohorts-reference.adoc[leveloffset=+1]

modules/clusterqueue-configuring-cohorts-reference.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * configure/using-cohorts.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="clusterqueue-configuring-cohorts-reference_{context}"]
+= Configuring cohorts within a cluster queue spec
+
+You can add a cluster queue to a cohort by specifying the name of the cohort in the `.spec.cohort` field of the `ClusterQueue` object, as shown in the following example:
+
+[source,yaml]
+----
+apiVersion: kueue.x-k8s.io/v1beta1
+kind: ClusterQueue
+metadata:
+  name: example-clusterqueue
+spec:
+# ...
+  cohort: example-cohort
+# ...
+----
+
+All cluster queues that have a matching `spec.cohort` are part of the same cohort.
+
+If the `spec.cohort` field is omitted, the cluster queue does not belong to any cohort and cannot access borrowable resources.