Introduce FS at admission time

apis/config/v1beta1/configuration_types.go

@@ -95,6 +95,9 @@ type Configuration struct {
 	// FairSharing controls the Fair Sharing semantics across the cluster.
 	FairSharing *FairSharing `json:"fairSharing,omitempty"`
 
+	// admissionFairSharing indicates configuration of FairSharing with the `AdmissionTime` mode on
+	AdmissionFairSharing *AdmissionFairSharing `json:"admissionFairSharing,omitempty"`
+
 	// Resources provides additional configuration options for handling the resources.
 	Resources *Resources `json:"resources,omitempty"`
 
@@ -472,3 +475,18 @@ type FairSharing struct {
 	// The default strategy is ["LessThanOrEqualToFinalShare", "LessThanInitialShare"].
 	PreemptionStrategies []PreemptionStrategy `json:"preemptionStrategies,omitempty"`
 }
+
+type AdmissionFairSharing struct {
+	// usageHalfLifeTime indicates the time after which the current usage will decay by a half
+	// If set to 0, usage will be reset to 0 immediately.
+	UsageHalfLifeTime metav1.Duration `json:"usageHalfLifeTime,omitempty"`
+
+	// usageSamplingInterval indicates how often Kueue updates consumedResources in FairSharingStatus
+	// Defaults to 5min.
+	UsageSamplingInterval metav1.Duration `json:"usageSamplingInterval,omitempty"`
+
+	// resourceWeights assigns weights to resources which then are used to calculate LocalQueue's
+	// resource usage and order Workloads.
+	// Defaults to 1.
+	ResourceWeights map[corev1.ResourceName]float64 `json:"resourceWeights,omitempty"`
+}

apis/config/v1beta1/defaults.go

@@ -210,6 +210,11 @@ func SetDefaults_Configuration(cfg *Configuration) {
 	if fs := cfg.FairSharing; fs != nil && fs.Enable && len(fs.PreemptionStrategies) == 0 {
 		fs.PreemptionStrategies = []PreemptionStrategy{LessThanOrEqualToFinalShare, LessThanInitialShare}
 	}
+	if afs := cfg.AdmissionFairSharing; afs != nil {
+		if afs.UsageSamplingInterval.Duration == 0 {
+			afs.UsageSamplingInterval = metav1.Duration{Duration: 5 * time.Minute}
+		}
+	}
 
 	if cfg.Resources != nil {
 		for idx := range cfg.Resources.Transformations {

apis/kueue/v1beta1/clusterqueue_types.go

@@ -137,6 +137,10 @@ type ClusterQueueSpec struct {
 	// if FairSharing is enabled in the Kueue configuration.
 	// +optional
 	FairSharing *FairSharing `json:"fairSharing,omitempty"`
+
+	// admissionScope indicates whether ClusterQueue uses the Admission Fair Sharing
+	// +optional
+	AdmissionScope *AdmissionScope `json:"admissionScope,omitempty"`
 }
 
 // AdmissionChecksStrategy defines a strategy for a AdmissionCheck.

apis/kueue/v1beta1/fairsharing_types.go

@@ -16,7 +16,11 @@ limitations under the License.
 
 package v1beta1
 
-import "k8s.io/apimachinery/pkg/api/resource"
+import (
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/resource"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
 
 // FairSharing contains the properties of the ClusterQueue or Cohort,
 // when participating in FairSharing.
@@ -49,4 +53,31 @@ type FairSharingStatus struct {
 	// weight of zero and is borrowing, this will return
 	// 9223372036854775807, the maximum possible share value.
 	WeightedShare int64 `json:"weightedShare"`
+
+	// admissionFairSharingStatus represents information relevant to the Admission Fair Sharing
+	AdmissionFairSharingStatus *AdmissionFairSharingStatus `json:"admissionFairSharingStatus,omitempty"`
 }
+
+type AdmissionFairSharingStatus struct {
+	// ConsumedResources represents the aggregated usage of resources over time,
+	// with decaying function applied.
+	// The value is populated if usage consumption functionality is enabled in Kueue config.
+	ConsumedResources corev1.ResourceList `json:"consumedResources,omitempty"`
+
+	// LastUpdate is the time when share and consumed resources were updated.
+	LastUpdate metav1.Time `json:"lastUpdate,omitempty"`
+}
+
+type AdmissionScope struct {
+	AdmissionMode AdmissionMode `json:"admissionMode,omitempty"`
+}
+
+type AdmissionMode string
+
+const (
+	// AdmissionFairSharing based on usage, with QueuingStrategy as defined in CQ.
+	UsageBasedAdmissionFairSharing AdmissionMode = "UsageBasedAdmissionFairSharing"
+
+	// AdmissionFairSharing is disabled for this CQ
+	NoAdmissionFairSharing AdmissionMode = "NoAdmissionFairSharing"
+)

apis/kueue/v1beta1/localqueue_types.go

@@ -48,6 +48,12 @@ type LocalQueueSpec struct {
 	// +kubebuilder:validation:Enum=None;Hold;HoldAndDrain
 	// +kubebuilder:default="None"
 	StopPolicy *StopPolicy `json:"stopPolicy,omitempty"`
+
+	// fairSharing defines the properties of the LocalQueue when
+	// participating in AdmissionFairSharing.  The values are only relevant
+	// if AdmissionFairSharing is enabled in the Kueue configuration.
+	// +optional
+	FairSharing *FairSharing `json:"fairSharing,omitempty"`
 }
 
 type LocalQueueFlavorStatus struct {
@@ -149,6 +155,10 @@ type LocalQueueStatus struct {
 	// +kubebuilder:validation:MaxItems=16
 	// +optional
 	Flavors []LocalQueueFlavorStatus `json:"flavors,omitempty"`
+
+	// FairSharing contains the information about the current status of fair sharing.
+	// +optional
+	FairSharing *FairSharingStatus `json:"fairSharing,omitempty"`
 }
 
 const (

charts/kueue/templates/crd/kueue.x-k8s.io_clusterqueues.yaml

@@ -115,6 +115,13 @@ spec:
                       type: object
                     type: array
                 type: object
+              admissionScope:
+                description: admissionScope indicates whether ClusterQueue uses the
+                  Admission Fair Sharing
+                properties:
+                  admissionMode:
+                    type: string
+                type: object
               cohort:
                 description: |-
                   cohort that this ClusterQueue belongs to. CQs that belong to the
@@ -590,6 +597,28 @@ spec:
                   when participating in Fair Sharing.
                   This is recorded only when Fair Sharing is enabled in the Kueue configuration.
                 properties:
+                  admissionFairSharingStatus:
+                    description: admissionFairSharingStatus represents information
+                      relevant to the Admission Fair Sharing
+                    properties:
+                      consumedResources:
+                        additionalProperties:
+                          anyOf:
+                          - type: integer
+                          - type: string
+                          pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                          x-kubernetes-int-or-string: true
+                        description: |-
+                          ConsumedResources represents the aggregated usage of resources over time,
+                          with decaying function applied.
+                          The value is populated if usage consumption functionality is enabled in Kueue config.
+                        type: object
+                      lastUpdate:
+                        description: LastUpdate is the time when share and consumed
+                          resources were updated.
+                        format: date-time
+                        type: string
+                    type: object
                   weightedShare:
                     description: |-
                       WeightedShare represents the maximum of the ratios of usage

charts/kueue/templates/crd/kueue.x-k8s.io_cohorts.yaml

@@ -252,6 +252,28 @@ spec:
                   when participating in Fair Sharing.
                   The is recorded only when Fair Sharing is enabled in the Kueue configuration.
                 properties:
+                  admissionFairSharingStatus:
+                    description: admissionFairSharingStatus represents information
+                      relevant to the Admission Fair Sharing
+                    properties:
+                      consumedResources:
+                        additionalProperties:
+                          anyOf:
+                          - type: integer
+                          - type: string
+                          pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                          x-kubernetes-int-or-string: true
+                        description: |-
+                          ConsumedResources represents the aggregated usage of resources over time,
+                          with decaying function applied.
+                          The value is populated if usage consumption functionality is enabled in Kueue config.
+                        type: object
+                      lastUpdate:
+                        description: LastUpdate is the time when share and consumed
+                          resources were updated.
+                        format: date-time
+                        type: string
+                    type: object
                   weightedShare:
                     description: |-
                       WeightedShare represents the maximum of the ratios of usage