From 114c45878749f48a04de798e573d8f9f91b646b6 Mon Sep 17 00:00:00 2001
From: Anai-Guo <antai12232931@outlook.com>
Date: Wed, 1 Jul 2026 09:30:09 -0700
Subject: [PATCH] feat(helm/raySpec): allow customizing the Ray head node
 readiness probe

The multi-node Ray head pod hard-codes its readiness probe to
failureThreshold: 1 / periodSeconds: 10. On slow, large multi-node
deployments the head serving process can take longer than a single 10s
period to start answering /health, so the pod is marked unready after the
first failed probe and never receives traffic. Users had no way to relax
it -- setting readinessProbe under servingEngineSpec, modelSpec, or
raySpec.headNode had no effect on the head node.

Honor raySpec.headNode.readinessProbe when set (rendered verbatim via
toYaml), falling back to the existing default otherwise, so behavior is
unchanged unless the field is provided. Document the new field in
values.yaml. headNode is an open object in values.schema.json, so no
schema change is needed (and the schema is CI-generated from values.yaml).

Fixes #742.

Signed-off-by: Anai-Guo <antai12232931@outlook.com>
---
 helm/templates/ray-cluster.yaml |  4 ++++
 helm/values.yaml                | 12 ++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/helm/templates/ray-cluster.yaml b/helm/templates/ray-cluster.yaml
index 54810fd8e..995bef82e 100644
--- a/helm/templates/ray-cluster.yaml
+++ b/helm/templates/ray-cluster.yaml
@@ -167,11 +167,15 @@ spec:
               - name: {{ include "chart.container-port-name" . }}
                 containerPort: {{ include "chart.container-port" . }}
             readinessProbe:
+              {{- if $modelSpec.raySpec.headNode.readinessProbe }}
+              {{- toYaml $modelSpec.raySpec.headNode.readinessProbe | nindent 14 }}
+              {{- else }}
               httpGet:
                 path: /health
                 port: {{ include "chart.container-port" . }}
               failureThreshold: 1
               periodSeconds: 10
+              {{- end }}
             livenessProbe:
               exec:
                 command: ["/bin/bash", "-c", "echo TBD"]
diff --git a/helm/values.yaml b/helm/values.yaml
index 3cc8a3125..028c4e45c 100644
--- a/helm/values.yaml
+++ b/helm/values.yaml
@@ -275,6 +275,18 @@ servingEngineSpec:
         requestMemory: "1Gi"
         # -- GPU request for the head node
         requestGPU: 1
+        # Readiness probe for the Ray head node (raySpec.headNode.readinessProbe).
+        # If unset, defaults to an httpGet /health probe with failureThreshold 1
+        # and periodSeconds 10. Override it to relax the probe when the model
+        # takes a long time to come up on a multi-node setup, otherwise the head
+        # pod may be marked unready and never receive traffic. Accepts a standard
+        # Kubernetes probe spec, e.g.:
+        # readinessProbe:
+        #   httpGet:
+        #     path: /health
+        #     port: 8000
+        #   failureThreshold: 10
+        #   periodSeconds: 30
 
   # -- Container port
   containerPort: 8000