Add maxInstances alongside maxSleepingInstances in LauncherConfig v1alpha1 (llm-d-incubation#487)

Stage A of the staged rename of MaxSleepingInstances -> MaxInstances
(see llm-d-incubation#471). Purely additive within v1alpha1: existing clients that set
maxSleepingInstances (including zero) continue to work unchanged.

- LauncherConfigSpec: add MaxInstances (optional, min 0). Relax
  MaxSleepingInstances to optional with min 0 and rewrite its doc to
  state the observable +1 semantics without naming an enforcing
  component. Deprecate MaxSleepingInstances in favor of MaxInstances.
- Add a CRD-level CEL rule forbidding only the ambiguous case where
  both fields are positive.
- dual-pods controller: add effectiveMaxInstances(lc) returning
  MaxInstances when positive, else MaxSleepingInstances+1. Both
  callsites in inference-server.go now pass effectiveMaxInstances(lc)-1.
  Numeric behavior is unchanged when only maxSleepingInstances is set.
- Regenerate CRD manifest and applyconfiguration.

Resolves llm-d-incubation#482.

Signed-off-by: Mike Spreitzer <mspreitz@us.ibm.com>

Author: MikeSpreitzer

api/fma/v1alpha1/launcherconfig_types.go

@@ -45,14 +45,28 @@ type EmbeddedPodTemplateSpec struct {
 }
 
 // LauncherConfigSpec defines the configuration to manage the nominal server-providing pod definition.
+// At most one of `maxSleepingInstances` and `maxInstances` may be positive; setting both to positive
+// values is rejected. Either may be zero or omitted.
+// +kubebuilder:validation:XValidation:rule="!(has(self.maxInstances) && has(self.maxSleepingInstances) && self.maxInstances > 0 && self.maxSleepingInstances > 0)",message="maxInstances and maxSleepingInstances must not both be positive"
 type LauncherConfigSpec struct {
 	// PodTemplate defines the pod specification for the server-providing pod.
 	// +optional
 	PodTemplate EmbeddedPodTemplateSpec `json:"podTemplate,omitempty"`
 
-	// MaxSleepingInstances is the maximum number of sleeping inference engine instances allowed per launcher pod.
-	// +kubebuilder:validation:Required
+	// MaxSleepingInstances caps the number of sleeping inference-engine instances per launcher pod
+	// when an awake instance is also present. When no instance is awake, one additional sleeping
+	// instance is permitted — i.e., a launcher pod can hold up to `MaxSleepingInstances + 1`
+	// instances in total.
+	// Deprecated: use MaxInstances, which simply caps the total number of instances per launcher pod.
+	// +optional
+	// +kubebuilder:validation:Minimum=0
 	MaxSleepingInstances int32 `json:"maxSleepingInstances,omitempty"`
+
+	// MaxInstances caps the total number of inference-engine instances per launcher pod.
+	// A value of zero means unset.
+	// +optional
+	// +kubebuilder:validation:Minimum=0
+	MaxInstances int32 `json:"maxInstances,omitempty"`
 }
 
 // LauncherConfigStatus represents the current status

config/crd/fma.llm-d.ai_launcherconfigs.yaml

@@ -43,10 +43,22 @@ spec:
           spec:
             description: Spec defines the desired state of the LauncherConfig.
             properties:
+              maxInstances:
+                description: |-
+                  MaxInstances caps the total number of inference-engine instances per launcher pod.
+                  A value of zero means unset.
+                format: int32
+                minimum: 0
+                type: integer
               maxSleepingInstances:
-                description: MaxSleepingInstances is the maximum number of sleeping
-                  inference engine instances allowed per launcher pod.
+                description: |-
+                  MaxSleepingInstances caps the number of sleeping inference-engine instances per launcher pod
+                  when an awake instance is also present. When no instance is awake, one additional sleeping
+                  instance is permitted — i.e., a launcher pod can hold up to `MaxSleepingInstances + 1`
+                  instances in total.
+                  Deprecated: use MaxInstances, which simply caps the total number of instances per launcher pod.
                 format: int32
+                minimum: 0
                 type: integer
               podTemplate:
                 description: PodTemplate defines the pod specification for the server-providing
@@ -8473,9 +8485,11 @@ spec:
                     - containers
                     type: object
                 type: object
-            required:
-            - maxSleepingInstances
             type: object
+            x-kubernetes-validations:
+            - message: maxInstances and maxSleepingInstances must not both be positive
+              rule: '!(has(self.maxInstances) && has(self.maxSleepingInstances) &&
+                self.maxInstances > 0 && self.maxSleepingInstances > 0)'
           status:
             description: Status represents the observed status of the LauncherConfig.
             properties:

pkg/controller/dual-pods/inference-server.go

@@ -626,7 +626,7 @@ func (item infSvrItem) process(urCtx context.Context, ctl *controller, nodeDat *
 		// then those with capacity for new instances.
 		// Note that multiple vLLM instances could exist in one launcher Pod, but at most one instance could be awake at a time.
 
-		launcherPod, hasSleepingInstance, someNotReady, err := ctl.selectBestLauncherPod(ctx, launcherPodAnys, iscHash, desiredPort, int(lc.Spec.MaxSleepingInstances), nodeDat)
+		launcherPod, hasSleepingInstance, someNotReady, err := ctl.selectBestLauncherPod(ctx, launcherPodAnys, iscHash, desiredPort, effectiveMaxInstances(lc)-1, nodeDat)
 		if err != nil {
 			return err, true
 		}
@@ -648,7 +648,7 @@ func (item infSvrItem) process(urCtx context.Context, ctl *controller, nodeDat *
 	// Remains: Zero matching launcher Pods, or the matching launcher Pod cannot host more instances to fulfill the request.
 
 	// TODO(waltforme): enforceSleeperBudget should be revised for launcher-based server-providing Pods
-	err, retry := ctl.enforceSleeperBudget(ctx, serverDat, requestingPod, int(lc.Spec.MaxSleepingInstances))
+	err, retry := ctl.enforceSleeperBudget(ctx, serverDat, requestingPod, effectiveMaxInstances(lc)-1)
 	if err != nil || retry {
 		return err, retry
 	}
@@ -796,6 +796,16 @@ func (ctl *controller) selectBestLauncherPod(
 	return nil, false, false, nil
 }
 
+// effectiveMaxInstances returns the cap on the total number of inference-engine instances
+// per launcher pod. If MaxInstances is positive, it is used directly; otherwise the legacy
+// MaxSleepingInstances semantics apply and the cap is MaxSleepingInstances + 1.
+func effectiveMaxInstances(lc *fmav1alpha1.LauncherConfig) int {
+	if lc.Spec.MaxInstances > 0 {
+		return int(lc.Spec.MaxInstances)
+	}
+	return int(lc.Spec.MaxSleepingInstances) + 1
+}
+
 // configInferenceServer computes the VllmConfig.
 // `isc` and `gpuUUIDs` are deeply immutable.
 // The result is deeply immutable.