Consistently Capitalize Fair Sharing - Docs (#4649)

Author: gabesaba

CHANGELOG/CHANGELOG-0.7.md

@@ -72,7 +72,7 @@ Changes since `v0.6.0`:
 - Add configuration to register Kinds as being managed by an external Kueue-compatible controller (#2059, @dgrove-oss)
 - Add fair sharing when borrowing unused resources from other ClusterQueues in a cohort.
 
-  Fair sharing is based on DRF for usage above nominal quotas.
+  Fair Sharing is based on DRF for usage above nominal quotas.
   When fair sharing is enabled, Kueue prefers to admit workloads from ClusterQueues with the lowest share first.
   Administrators can enable and configure fair sharing preemption using a combination of two policies: `LessThanOrEqualtoFinalShare`, `LessThanInitialShare`.
 

README.md

@@ -18,7 +18,7 @@ Read the [overview](https://kueue.sigs.k8s.io/docs/overview/) and watch the Kueu
 ## Features overview
 
 - **Job management:** Support job queueing based on [priorities](https://kueue.sigs.k8s.io/docs/concepts/workload/#priority) with different [strategies](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/#queueing-strategy): `StrictFIFO` and `BestEffortFIFO`.
-- **Advanced Resource management:** Comprising: [resource flavor fungibility](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/#flavorfungibility), [fair sharing](https://kueue.sigs.k8s.io/docs/concepts/preemption/#fair-sharing), [cohorts](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/#cohort) and [preemption](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/#preemption) with a variety of policies between different tenants.
+- **Advanced Resource management:** Comprising: [resource flavor fungibility](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/#flavorfungibility), [Fair Sharing](https://kueue.sigs.k8s.io/docs/concepts/preemption/#fair-sharing), [cohorts](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/#cohort) and [preemption](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/#preemption) with a variety of policies between different tenants.
 - **Integrations:** Built-in support for popular jobs, e.g. [BatchJob](https://kueue.sigs.k8s.io/docs/tasks/run/jobs/), [Kubeflow training jobs](https://kueue.sigs.k8s.io/docs/tasks/run/kubeflow/), [RayJob](https://kueue.sigs.k8s.io/docs/tasks/run/rayjobs/), [RayCluster](https://kueue.sigs.k8s.io/docs/tasks/run/rayclusters/), [JobSet](https://kueue.sigs.k8s.io/docs/tasks/run/jobsets/),  [plain Pod and Pod Groups](https://kueue.sigs.k8s.io/docs/tasks/run/plain_pods/).
 - **System insight:** Build-in [prometheus metrics](https://kueue.sigs.k8s.io/docs/reference/metrics/) to help monitor the state of the system, and on-demand visibility endpoint for [monitoring of pending workloads](https://kueue.sigs.k8s.io/docs/tasks/manage/monitor_pending_workloads/pending_workloads_on_demand/).
 - **AdmissionChecks:** A mechanism for internal or external components to influence whether a workload can be [admitted](https://kueue.sigs.k8s.io/docs/concepts/admission_check/).

keps/1714-fair-sharing/README.md

@@ -27,7 +27,7 @@
 <!-- /toc -->
 
 ## Summary
-This KEP introduces weight-based fair sharing of unused resources across 
+This KEP introduces weight-based Fair Sharing of unused resources across 
 needing ClusterQueues, respecting borrowing and lending limits, multi-level
 hierarchy and preferences of cohorts to distribute unused resources 
 internally.
@@ -44,7 +44,7 @@ use the highest one, breaking the whole idea altogether). Thus a more comprehens
 solution of distributing unused resources is needed.
 
 ### Goals
-* Create a mechanism to enforce fair sharing of resources. Two equally important
+* Create a mechanism to enforce Fair Sharing of resources. Two equally important
 sub-organizations (Cohorts or ClusterQueues), placed in the similar spots in the
 whole organization (hierarchy of Cohorts), actively competing for the same
 resources (having workloads needing more than nominal quota), should 
@@ -59,10 +59,10 @@ under the same parent.
 sub-organization and only after they have been fulfilled, proceed with distribution
 outside of the suborganization.
 
-* When enforcing fair sharing, ignore workload priorities unless:
+* When enforcing Fair Sharing, ignore workload priorities unless:
 
    * The workload's priority is above admin-defined high priority. Super high
-priority workloads overrule fair sharing and are treated according to KEP [#1337](https://github.com/kubernetes-sigs/kueue/tree/main/keps/1337-preempt-within-cohort-while-borrowing).
+priority workloads overrule Fair Sharing and are treated according to KEP [#1337](https://github.com/kubernetes-sigs/kueue/tree/main/keps/1337-preempt-within-cohort-while-borrowing).
 
    * There is a need to preempt some non top priority workload from a ClusterQueue.
 Then the lowest priority workloads from a CQ that is over its fair share should
@@ -76,30 +76,30 @@ in particular:
    * Guaranteed/nominal quota
    * Hierarchical cohorts
 
-* Fair sharing should not limit Kueue scalability. Kueue, with fair sharing enabled,
+* Fair Sharing should not limit Kueue scalability. Kueue, with Fair Sharing enabled,
 should be able to handle >1k ClusterQueues, >100 Cohorts and >10k workloads (that
 are either running or queued) within a single hierarchical organization.
 
 * The proposed system should be hard to game, for example by creating big workloads
 that consume all capacity.
 
-* Fair sharing enforcement should not significantly decrease overall utilization,
+* Fair Sharing enforcement should not significantly decrease overall utilization,
 however, pathological situations (like a single workload consuming all otherwise
-unused capacity) should be resolved in favor of fair sharing than maximizing the
+unused capacity) should be resolved in favor of Fair Sharing than maximizing the
 utilization (the big greedy workload should be preempted to admit smaller
 workloads from other CQ that consume only their fair share).
 
 ### Non-Goals
 * Use historical data (for example CQ A used a lot of shared capacity for the last
 week, so now it should get less because others, who didn't need anything then, have
-pending workloads). Fair sharing should be based on point-in-time situation, although,
-ideally it should be expandable to support history-based fair sharing(for example with #26)
+pending workloads). Fair Sharing should be based on point-in-time situation, although,
+ideally it should be expandable to support history-based Fair Sharing(for example with #26)
 without major redesign.
 
-* Enable fair sharing only for some part of the resources or Cohort hierarchy.
-Fair sharing will be a global switch (at least initially).
+* Enable Fair Sharing only for some part of the resources or Cohort hierarchy.
+Fair Sharing will be a global switch (at least initially).
 
-* Maximize utilization at the cost of fair sharing.
+* Maximize utilization at the cost of Fair Sharing.
 
 ## Proposal
 
@@ -108,7 +108,7 @@ on top of the given nominal quota, that doesn't justify "complains" against
 any other similar CQ about excessive extra resources that CQ was given. Basically
 the sharing of unused resources is fair, if no CQ can say it is grossly unfair.
 
-Introduce a global fair sharing mechanism that is based on preemptions. As long
+Introduce a global Fair Sharing mechanism that is based on preemptions. As long
 as there are some free and accessible resources in the cohort hierarchy, Kueue
 will admit workloads without any limits. However, once the capacity is gone,
 new workloads from Cohorts/CQ that have not received their fair share yet will
@@ -126,7 +126,7 @@ We will add an optional weight field to both Cohorts and CQ. The weight will
 indicate how to fair share resources between sub-organizations (CQs or Cohorts)
 under the same Cohort.
 
-Fair sharing will be configured for the whole cluster, using the configuration
+Fair Sharing will be configured for the whole cluster, using the configuration
 file. In Alpha it will be just a feature gate.
 
 ### User Stories (Optional)
@@ -176,13 +176,13 @@ to execute. I want to distribute the resources from CS in the following way:
 
 ### Risks and Mitigations
 
-* Fair sharing may increase the number of preemptions in the system vs current
+* Fair Sharing may increase the number of preemptions in the system vs current
 state where the first workload to acquire unused resources keeps them until it
 finishes. Mitigations include:
-    * Introduce minimum execution time before workloads can be preempted for fair sharing.
+    * Introduce minimum execution time before workloads can be preempted for Fair Sharing.
     * Introduce delayed fair share enforcement - new workloads have to wait a bit before preempting others to get their share.
 
-* Fair sharing may decrease utilization of the unused resources while attempting to
+* Fair Sharing may decrease utilization of the unused resources while attempting to
 distribute them fairly, vs provide the tighties bin-packing. To avoid these scenarios,
 users should prefer to run massive workloads under nominal quotas.
 
@@ -255,7 +255,7 @@ When a CQ x fails to admit a workload w, one of the following scenarios may occu
 
 * [S2] A sub-organization to which CQ x belongs is borrowing, however it seems that it is
 borrowing too little compared to other sub-organizations that are also borrowing, so some
-action is needed to enforce fair sharing. We should compare how much the sub-orgs are
+action is needed to enforce Fair Sharing. We should compare how much the sub-orgs are
 borrowing compared to each other, and preempt some workloads up to the point when its fair
 share would be smaller than the sub-org for which preemptions are executed.
 
@@ -291,7 +291,7 @@ For each workload z in y we check whether if:
 
 [S2-a] value of AlmostLCA(y,x) **without z** is still higher (or equal) than value of AlmostLCA(x,y)
 with admitted workload w. Y’s sub-orgs will still be better than X’s sub-org after we
-preempt z and admit w, thus z is a reasonable candidate to re-balance fair sharing.
+preempt z and admit w, thus z is a reasonable candidate to re-balance Fair Sharing.
 
 
 [S2-b] value of AlmostLCA(y,x) (with z) is strictly higher than AlmostLCA(x,y) with admitted workload w.
@@ -355,8 +355,8 @@ This is a very complex feature so there will be lots of unit, integration and e2
 #### Alpha
 
 The alpha will be split among two releases.
-Release v0.7 will only implement fair sharing in the existing flat structure (cohorts don’t have parents).
-Release v0.8 will incorporate fair sharing with arbitrary hierarchies (KEP #79)
+Release v0.7 will only implement Fair Sharing in the existing flat structure (cohorts don’t have parents).
+Release v0.8 will incorporate Fair Sharing with arbitrary hierarchies (KEP #79)
 
 The following metrics will be added:
 * ClusterQueue fairness value

keps/1714-fair-sharing/kep.yaml

@@ -1,4 +1,4 @@
-title: Fair sharing
+title: Fair Sharing
 kep-number: 1714
 authors:
   - "@mwielgus"

keps/79-hierarchical-cohorts/README.md

@@ -43,7 +43,7 @@ team and quota/budget structures.
 
 * Change the existing API and mechanics in a not backward-compatible way.
 * Introduce an alternative API to ClusterQueue.
-* Introduce new ways of fair sharing, like ratio-based sharing (at least 
+* Introduce new ways of Fair Sharing, like ratio-based sharing (at least 
 not in this KEP).
 * Introduce additional preemption models (this will be in a separate KEP).
 

site/content/en/docs/concepts/_index.md

@@ -22,7 +22,7 @@ resources such as availability, pricing, architecture, models, etc.
 ### [Cluster Queue](/docs/concepts/cluster_queue)
 
 A cluster-scoped resource that governs a pool of resources, defining usage
-limits and fair sharing rules.
+limits and Fair Sharing rules.
 
 ### [Local Queue](/docs/concepts/local_queue)
 
@@ -75,7 +75,7 @@ A _cohort_ is a group of ClusterQueues that can borrow unused quota from each ot
 
 _Queueing_ is the state of a Workload since the time it is created until Kueue admits it on a ClusterQueue.
 Typically, the Workload will compete with other Workloads for available
-quota based on the fair sharing rules of the ClusterQueue.
+quota based on the Fair Sharing rules of the ClusterQueue.
 
 ### [Preemption](/docs/concepts/preemption)
 

site/content/en/docs/concepts/cluster_queue.md

@@ -3,15 +3,15 @@ title: "Cluster Queue"
 date: 2023-03-14
 weight: 3
 description: >
-  A cluster-scoped resource that governs a pool of resources, defining usage limits and fair sharing rules.
+  A cluster-scoped resource that governs a pool of resources, defining usage limits and Fair Sharing rules.
 ---
 
 A ClusterQueue is a cluster-scoped object that governs a pool of resources
 such as pods, CPU, memory, and hardware accelerators. A ClusterQueue defines:
 
 - The quotas for the [resource _flavors_](/docs/concepts/resource_flavor) that the ClusterQueue manages,
   with usage limits and order of consumption.
-- Fair sharing rules across the multiple ClusterQueues in the cluster.
+- Fair Sharing rules across the multiple ClusterQueues in the cluster.
 
 Only [batch administrators](/docs/tasks#batch-administrator) should create `ClusterQueue` objects.
 

site/content/en/docs/concepts/preemption.md

@@ -66,7 +66,7 @@ already above the nominal quota. The algorithms are:
 
   This algorithm is the most lightweight of the two.
 
-- **[Fair sharing](#fair-sharing)**: ClusterQueues with pending Workloads can preempt other Workloads in their cohort
+- **[Fair Sharing](#fair-sharing)**: ClusterQueues with pending Workloads can preempt other Workloads in their cohort
   until the preempting ClusterQueue obtains an equal or weighted share of the borrowable resources.
   The borrowable resources are the unused nominal quota of all the ClusterQueues in the cohort.
 
@@ -118,10 +118,10 @@ admitted when accounting back the quota usage of the target Workload.
 
 ## Fair Sharing
 
-Fair sharing introduces the concepts of ClusterQueue share values and preemption
+Fair Sharing introduces the concepts of ClusterQueue share values and preemption
 strategies. These work together with the preemption policies set in
 `withinClusterQueue` and `reclaimWithinCohort` (but __not__ `borrowWithinCohort`) to determine if a pending
-Workload can preempt an admitted Workload in Fair sharing. Fair sharing uses preemptions to
+Workload can preempt an admitted Workload in Fair Sharing. Fair Sharing uses preemptions to
 achieve an equal or weighted share of the borrowable resources between the
 tenants of a cohort.
 
@@ -132,7 +132,7 @@ parent) as of v0.11. Using these features together in V0.9 and V0.10 is
 unsupported, and results in undefined behavior.
 {{% /alert %}}
 
-To enable fair sharing, [use a Kueue Configuration](/docs/installation#install-a-custom-configured-release-version) similar to the following:
+To enable Fair Sharing, [use a Kueue Configuration](/docs/installation#install-a-custom-configured-release-version) similar to the following:
 
 ```yaml
 apiVersion: config.kueue.x-k8s.io/v1beta1
@@ -146,7 +146,7 @@ The attributes in this Kueue Configuration are described in the following sectio
 
 ### ClusterQueue share value
 
-When you enable fair sharing, Kueue assigns a numeric share value to each ClusterQueue to summarize
+When you enable Fair Sharing, Kueue assigns a numeric share value to each ClusterQueue to summarize
 the usage of borrowed resources in a ClusterQueue, in comparison to others in the same cohort.
 The share value is weighted by the `.spec.fairSharing.weight` defined in a ClusterQueue.
 

site/content/en/docs/overview/_index.md

@@ -17,15 +17,15 @@ You can install Kueue on top of a vanilla Kubernetes cluster. Kueue does not rep
 
 Kueue APIs allow you to express:
 
-* Quotas and policies for fair sharing among tenants.
+* Quotas and policies for Fair Sharing among tenants.
 * Resource fungibility: if a resource flavor is fully utilized, Kueue can admit the job using a different flavor.
 
 A core design principle for Kueue is to avoid duplicating mature functionality in Kubernetes components and well-established third-party controllers. Autoscaling, pod-to-node scheduling and job lifecycle management are the responsibility of cluster-autoscaler, kube-scheduler and kube-controller-manager, respectively. Advanced admission control can be delegated to controllers such as gatekeeper.
 
 ## Features overview
 
 - **Job management:** Support job queueing based on [priorities](/docs/concepts/workload/#priority) with different [strategies](/docs/concepts/cluster_queue/#queueing-strategy): `StrictFIFO` and `BestEffortFIFO`.
-- **Advanced Resource management:** Comprising: [resource flavor fungibility](/docs/concepts/cluster_queue/#flavorfungibility), [fair sharing](/docs/concepts/preemption/#fair-sharing), [cohorts](/docs/concepts/cluster_queue/#cohort) and [preemption](/docs/concepts/cluster_queue/#preemption) with a variety of policies between different tenants.
+- **Advanced Resource management:** Comprising: [resource flavor fungibility](/docs/concepts/cluster_queue/#flavorfungibility), [Fair Sharing](/docs/concepts/preemption/#fair-sharing), [cohorts](/docs/concepts/cluster_queue/#cohort) and [preemption](/docs/concepts/cluster_queue/#preemption) with a variety of policies between different tenants.
 - **Integrations:** Built-in support for popular jobs, e.g. [BatchJob](/docs/tasks/run/jobs/), [Kubeflow training jobs](/docs/tasks/run/kubeflow/), [RayJob](/docs/tasks/run/rayjobs/), [RayCluster](/docs/tasks/run/rayclusters/), [JobSet](/docs/tasks/run/jobsets/),  [AppWrappers](/docs/tasks/run/appwrappers/), [plain Pod and Pod Groups](/docs/tasks/run/plain_pods/).
 - **System insight:** Build-in [prometheus metrics](/docs/reference/metrics/) to help monitor the state of the system, and on-demand visibility endpoint for [monitoring of pending workloads](/docs/tasks/manage/monitor_pending_workloads/pending_workloads_on_demand/).
 - **AdmissionChecks:** A mechanism for internal or external components to influence whether a workload can be [admitted](/docs/concepts/admission_check/).

site/content/en/docs/reference/metrics.md

@@ -37,7 +37,7 @@ Use the following metrics to monitor the status of your ClusterQueues:
 | `kueue_cluster_queue_status`               | Gauge     | Reports the status of the ClusterQueue                                              | `cluster_queue`: The name of the ClusterQueue<br> `status`: Possible values are `pending`, `active` or `terminated`. For a ClusterQueue, the metric only reports a value of 1 for one of the statuses. |
 | `kueue_reserving_active_workloads`         | Gauge     | The number of Workloads that are reserving quota, per `cluster_queue`.              | `cluster_queue`: the name of the ClusterQueue                                                                                                                                                          |
 | `kueue_admission_cycle_preemption_skips`   | Gauge     | The number of Workloads in the ClusterQueue that got preemption candidates but had to be skipped because other ClusterQueues needed the same resources in the same cycle | `cluster_queue`: the name of the ClusterQueue                                                                     |
-| `kueue_preempted_workloads_total`          | Counter   | The number of preempted workloads per `preempting_cluster_queue`                    | `preempting_cluster_queue`: the name of the ClusterQueue<br> `reason`: possible values are `InClusterQueue` means that the workload was preempted by a workload in the same ClusterQueue; `InCohortReclamation` means that the workload was preempted by a workload in the same cohort due to reclamation of nominal quota; `InCohortFairSharing` means that the workload was preempted by a workload in the same cohort due to fair sharing; `InCohortReclaimWhileBorrowing` means that the workload was preempted by a workload in the same cohort due to reclamation of nominal quota while borrowing |
+| `kueue_preempted_workloads_total`          | Counter   | The number of preempted workloads per `preempting_cluster_queue`                    | `preempting_cluster_queue`: the name of the ClusterQueue<br> `reason`: possible values are `InClusterQueue` means that the workload was preempted by a workload in the same ClusterQueue; `InCohortReclamation` means that the workload was preempted by a workload in the same cohort due to reclamation of nominal quota; `InCohortFairSharing` means that the workload was preempted by a workload in the same cohort due to Fair Sharing; `InCohortReclaimWhileBorrowing` means that the workload was preempted by a workload in the same cohort due to reclamation of nominal quota while borrowing |
 
 ## LocalQueue Status (alpha)