feat: add ScaleGate field to ScaleStrategy for fast fallback on quota exceeded

docs/reference/api.md

@@ -780,6 +780,7 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `workersToDelete` _string array_ | WorkersToDelete workers to be deleted |  |  |
+| `scaleGate` _string array_ | ScaleGate contains a list of scaling gates blocking this worker group from<br />scaling up. When Kueue encounters a quota-exceeded error for this worker<br />group, it appends "kueue.k8s.io/quota-exceeded" to ScaleGate. The Autoscaler<br />initiates fallback behavior whenever ScaleGate is non-empty. KubeRay defines<br />this field but does not read or write it, and preserves its value across<br />reconciles. |  |  |
 
 
 #### SubmitterConfig

helm-chart/kuberay-operator/crds/ray.io_raycronjobs.yaml

@@ -5457,6 +5457,10 @@ spec:
                               type: object
                             scaleStrategy:
                               properties:
+                                scaleGate:
+                                  items:
+                                    type: string
+                                  type: array
                                 workersToDelete:
                                   items:
                                     type: string

ray-operator/apis/ray/v1/raycluster_types.go

@@ -489,6 +489,14 @@ type WorkerGroupSpec struct {
 type ScaleStrategy struct {
 	// WorkersToDelete workers to be deleted
 	WorkersToDelete []string `json:"workersToDelete,omitempty"`
+	// ScaleGate contains a list of scaling gates blocking this worker group from
+	// scaling up. When Kueue encounters a quota-exceeded error for this worker
+	// group, it appends "kueue.k8s.io/quota-exceeded" to ScaleGate. The Autoscaler
+	// initiates fallback behavior whenever ScaleGate is non-empty. KubeRay defines
+	// this field but does not read or write it, and preserves its value across
+	// reconciles.
+	// +optional
+	ScaleGate []string `json:"scaleGate,omitempty"`
 }
 
 // AutoscalerOptions specifies optional configuration for the Ray autoscaler.

ray-operator/config/crd/bases/ray.io_raycronjobs.yaml

@@ -5457,6 +5457,10 @@ spec:
                               type: object
                             scaleStrategy:
                               properties:
+                                scaleGate:
+                                  items:
+                                    type: string
+                                  type: array
                                 workersToDelete:
                                   items:
                                     type: string

ray-operator/controllers/ray/utils/util.go

@@ -658,6 +658,9 @@ func GenerateHashWithoutReplicasAndWorkersToDelete(rayClusterSpec rayv1.RayClust
 		updatedRayClusterSpec.WorkerGroupSpecs[i].MaxReplicas = nil
 		updatedRayClusterSpec.WorkerGroupSpecs[i].MinReplicas = nil
 		updatedRayClusterSpec.WorkerGroupSpecs[i].ScaleStrategy.WorkersToDelete = nil
+		// External controllers like Kueue may set ScaleGate to signal quota exhaustion,
+		// which should not trigger a new RayCluster preparation.
+		updatedRayClusterSpec.WorkerGroupSpecs[i].ScaleStrategy.ScaleGate = nil
 		updatedRayClusterSpec.WorkerGroupSpecs[i].Template.Spec.Tolerations = nil
 		updatedRayClusterSpec.WorkerGroupSpecs[i].Template.Spec.SchedulingGates = nil
 	}