feat: real vLLM data plane with GPU scheduling and readiness-gated warmup

The data plane was previously a pause placeholder so the control plane
could be tested without a GPU. Make it real while keeping CI GPU-free:

- spec: add 'image' (default vllm/vllm-openai:latest), 'gpu' (default 1),
  and 'healthPath' (default /health; empty string disables the probe)
- build_deployment: use the spec image, request nvidia.com/gpu when gpu>0,
  and add a readiness probe on healthPath when it is non-empty
- the readiness probe is what makes 'Ready' mean 'warm': ready_replicas
  reflects serving capacity, so Warming->Ready tracks the real cold start
- examples: qwen-7b.yaml is an honest GPU deployment; ci-placeholder.yaml
  (gpu=0, pause image, empty healthPath) is the control-plane e2e fixture
- ci: run the e2e test against the placeholder fixture

phase_for is unchanged: the abstraction was already correct, the probe
just supplies the real signal underneath it.

Author: MicheleCampi

.github/workflows/ci.yml

@@ -83,12 +83,12 @@ jobs:
           echo "operator started (pid $(cat operator.pid))"
 
       - name: Apply a VllmService
-        run: kubectl apply -f deploy/examples/qwen-7b.yaml
+        run: kubectl apply -f deploy/examples/ci-placeholder.yaml
 
       - name: Wait for Deployment to be created
         run: |
           for i in $(seq 1 30); do
-            if kubectl get deployment qwen-7b >/dev/null 2>&1; then
+            if kubectl get deployment ci-placeholder >/dev/null 2>&1; then
               echo "Deployment created after ${i}s"
               exit 0
             fi
@@ -102,27 +102,27 @@ jobs:
       - name: Wait for status to reach Ready
         run: |
           for i in $(seq 1 60); do
-            phase=$(kubectl get vllmservice qwen-7b -o jsonpath='{.status.phase}' 2>/dev/null || true)
+            phase=$(kubectl get vllmservice ci-placeholder -o jsonpath='{.status.phase}' 2>/dev/null || true)
             echo "[$i] phase=${phase:-<none>}"
             if [ "$phase" = "Ready" ]; then
               echo "VllmService reached Ready after ${i}s"
-              kubectl get vllmservice qwen-7b -o jsonpath='{.status.message}'
+              kubectl get vllmservice ci-placeholder -o jsonpath='{.status.message}'
               exit 0
             fi
             sleep 2
           done
           echo "ERROR: VllmService did not reach Ready within 120s"
-          kubectl get vllmservice qwen-7b -o yaml
+          kubectl get vllmservice ci-placeholder -o yaml
           cat operator.log
           exit 1
 
       - name: Verify owner reference and garbage collection
         run: |
-          owner=$(kubectl get deployment qwen-7b -o jsonpath='{.metadata.ownerReferences[0].kind}')
+          owner=$(kubectl get deployment ci-placeholder -o jsonpath='{.metadata.ownerReferences[0].kind}')
           [ "$owner" = "VllmService" ] || { echo "ERROR: bad owner ref: $owner"; exit 1; }
-          kubectl delete vllmservice qwen-7b
+          kubectl delete vllmservice ci-placeholder
           for i in $(seq 1 30); do
-            if ! kubectl get deployment qwen-7b >/dev/null 2>&1; then
+            if ! kubectl get deployment ci-placeholder >/dev/null 2>&1; then
               echo "Deployment garbage-collected after ${i}s"
               exit 0
             fi

deploy/crd.yaml

@@ -28,6 +28,26 @@ spec:
               treats time-to-first-token as a first-class concern, configuring the
               pod for the cold-start/throughput trade-off the spec asks for.
             properties:
+              gpu:
+                default: 1
+                description: |-
+                  Number of GPUs to request per replica. Set to 0 for CPU-only or
+                  placeholder runs (e.g. CI on a cluster without GPUs).
+                format: int32
+                type: integer
+              healthPath:
+                default: /health
+                description: |-
+                  HTTP path for the readiness probe, e.g. "/health". When non-empty,
+                  the operator gates readiness (and thus the Warming->Ready transition)
+                  on this endpoint, so "Ready" means the server can actually serve.
+                  Set to an empty string to disable the probe entirely, for inert
+                  placeholder images that expose no HTTP health endpoint.
+                type: string
+              image:
+                default: vllm/vllm-openai:latest
+                description: Container image to run. Defaults to the official vLLM OpenAI server.
+                type: string
               model:
                 description: HuggingFace model id to serve, e.g. "Qwen/Qwen2.5-7B-Instruct".
                 type: string

deploy/examples/ci-placeholder.yaml

@@ -0,0 +1,18 @@
+# Control-plane end-to-end test fixture (not a usage example).
+# Uses a placeholder image, gpu=0, and an empty health path so the reconcile
+# loop, status machine, owner references, and garbage collection can be
+# exercised on a GPU-less kind cluster in CI. The pause image exposes no
+# HTTP endpoint, so healthPath is "": readiness is not gated and the pod
+# becomes Ready as soon as it runs. For a real deployment see qwen-7b.yaml.
+apiVersion: inference.michelecampi.dev/v1alpha1
+kind: VllmService
+metadata:
+  name: ci-placeholder
+  namespace: default
+spec:
+  model: "placeholder/ci-test"
+  replicas: 1
+  warmupStrategy: Eager
+  image: "registry.k8s.io/pause:3.10"
+  gpu: 0
+  healthPath: ""

deploy/examples/qwen-7b.yaml

@@ -1,3 +1,5 @@
+# Example: serve Qwen2.5-7B on a GPU node with the official vLLM image.
+# Requires a cluster with an NVIDIA GPU and the device plugin installed.
 apiVersion: inference.michelecampi.dev/v1alpha1
 kind: VllmService
 metadata:
@@ -7,3 +9,5 @@ spec:
   model: "Qwen/Qwen2.5-7B-Instruct"
   replicas: 1
   warmupStrategy: Eager
+  image: "vllm/vllm-openai:latest"
+  gpu: 1

src/lib.rs

@@ -29,6 +29,20 @@ pub struct VllmServiceSpec {
     /// them for faster steady-state inference at a higher cold-start cost.
     #[serde(default)]
     pub warmup_strategy: WarmupStrategy,
+    /// Container image to run. Defaults to the official vLLM OpenAI server.
+    #[serde(default = "default_image")]
+    pub image: String,
+    /// Number of GPUs to request per replica. Set to 0 for CPU-only or
+    /// placeholder runs (e.g. CI on a cluster without GPUs).
+    #[serde(default = "default_gpu")]
+    pub gpu: i32,
+    /// HTTP path for the readiness probe, e.g. "/health". When non-empty,
+    /// the operator gates readiness (and thus the Warming->Ready transition)
+    /// on this endpoint, so "Ready" means the server can actually serve.
+    /// Set to an empty string to disable the probe entirely, for inert
+    /// placeholder images that expose no HTTP health endpoint.
+    #[serde(default = "default_health_path")]
+    pub health_path: String,
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, Default, PartialEq)]
@@ -43,6 +57,15 @@ pub enum WarmupStrategy {
 fn default_replicas() -> i32 {
     1
 }
+fn default_image() -> String {
+    "vllm/vllm-openai:latest".to_string()
+}
+fn default_gpu() -> i32 {
+    1
+}
+fn default_health_path() -> String {
+    "/health".to_string()
+}
 
 /// Observed state, written back by the operator.
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, Default)]

src/main.rs

@@ -4,8 +4,13 @@ use std::time::Duration;
 
 use futures::StreamExt;
 use k8s_openapi::api::apps::v1::{Deployment, DeploymentSpec};
-use k8s_openapi::api::core::v1::{Container, ContainerPort, EnvVar, PodSpec, PodTemplateSpec};
+use k8s_openapi::api::core::v1::{
+    Container, ContainerPort, EnvVar, HTTPGetAction, PodSpec, PodTemplateSpec, Probe,
+    ResourceRequirements,
+};
+use k8s_openapi::apimachinery::pkg::api::resource::Quantity;
 use k8s_openapi::apimachinery::pkg::apis::meta::v1::LabelSelector;
+use k8s_openapi::apimachinery::pkg::util::intstr::IntOrString;
 use kube::{
     api::{Api, ObjectMeta, Patch, PatchParams},
     runtime::{
@@ -47,9 +52,45 @@ fn build_deployment(svc: &VllmService) -> Result<Deployment, Error> {
 
     let enforce_eager = matches!(svc.spec.warmup_strategy, WarmupStrategy::Eager);
 
+    // GPU resource limit, only when requested. With gpu=0 (CI / CPU-only)
+    // the container requests no GPU and schedules on any node.
+    let resources = if svc.spec.gpu > 0 {
+        let mut limits = BTreeMap::new();
+        limits.insert(
+            "nvidia.com/gpu".to_string(),
+            Quantity(svc.spec.gpu.to_string()),
+        );
+        Some(ResourceRequirements {
+            limits: Some(limits),
+            ..Default::default()
+        })
+    } else {
+        None
+    };
+
+    // Readiness probe, built only when health_path is non-empty. This is
+    // what makes "Ready" mean "warm": when set, Kubernetes marks the pod
+    // ready only once the server answers on this endpoint, so the
+    // Warming->Ready transition tracks the real cold start. Inert
+    // placeholder images set health_path to "" to disable the probe.
+    let readiness_probe = if svc.spec.health_path.is_empty() {
+        None
+    } else {
+        Some(Probe {
+            http_get: Some(HTTPGetAction {
+                path: Some(svc.spec.health_path.clone()),
+                port: IntOrString::Int(8000),
+                ..Default::default()
+            }),
+            initial_delay_seconds: Some(5),
+            period_seconds: Some(5),
+            failure_threshold: Some(60),
+            ..Default::default()
+        })
+    };
     let container = Container {
         name: "inference".to_string(),
-        image: Some("registry.k8s.io/pause:3.10".to_string()),
+        image: Some(svc.spec.image.clone()),
         ports: Some(vec![ContainerPort {
             container_port: 8000,
             name: Some("http".to_string()),
@@ -67,6 +108,8 @@ fn build_deployment(svc: &VllmService) -> Result<Deployment, Error> {
                 ..Default::default()
             },
         ]),
+        resources,
+        readiness_probe,
         ..Default::default()
     };