feat(helm/raycluster): pass through annotations and podAnnotations (#962)

[Anai-Guo]

Summary

modelSpec.annotations and modelSpec.podAnnotations already exist and are honored for the standard (non-Ray) vLLM Deployment (deployment-vllm-multi.yaml), but the RayCluster template never consumed them. Users running engines through KubeRay (raySpec.enabled: true) therefore had no way to attach pod-level annotations — e.g. Multus k8s.v1.cni.cncf.io/networks — or object-level annotations to their head/worker pods. As #962 notes, the values appear to exist but were simply never wired into the kuberay path.

Changes

helm/templates/ray-cluster.yaml, mirroring the existing Deployment pattern:

• modelSpec.annotations → RayCluster object metadata.annotations
• modelSpec.podAnnotations → head pod template metadata.annotations
• modelSpec.podAnnotations → worker pod template metadata.annotations

No new values are introduced — this only completes the existing passthrough for the KubeRay path. Both blocks are guarded with {{- with ... }}, so output is unchanged when the values are empty (the default).

Test

Adds a helm-unittest case to helm/tests/ray-cluster_test.yaml asserting that both annotations (object) and podAnnotations (head + worker) render on the RayCluster.

Closes #962

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request adds support for custom annotations and podAnnotations in the RayCluster Helm template, along with corresponding unit tests. The review feedback suggests correcting the JSONPath syntax in the new unit tests to avoid parsing failures. Additionally, it recommends extending the metadata passthrough by supporting custom labels and podLabels on the RayCluster and its pod templates to ensure feature parity with standard Deployment templates.

[gemini-code-assist]

In helm-unittest (and standard JSONPath), the dot before the bracket notation (e.g., .["..."]) is syntactically incorrect and can cause path parsing failures. It should be written as ["..."] directly appended to the parent field.

      equal:
        path: metadata.annotations["example.com/owner"]
        value: team-a
    - documentIndex: 0
      equal:
        path: spec.headGroupSpec.template.metadata.annotations["k8s.v1.cni.cncf.io/networks"]
        value: macvlan-conf
    - documentIndex: 0
      equal:
        path: spec.workerGroupSpecs[0].template.metadata.annotations["k8s.v1.cni.cncf.io/networks"]
        value: macvlan-conf

[gemini-code-assist]

To ensure feature parity with the standard Deployment template and complete the metadata passthrough for KubeRay, we should also pass through modelSpec.labels to the RayCluster metadata.

  labels:
    model: {{ $modelSpec.name }}
    helm-release-name: {{ .Release.Name }}
    {{- include "chart.engineLabels" . | nindent 4 }}
    {{- with $modelSpec.labels }}
    {{- toYaml . | nindent 4 }}
    {{- end }}

[gemini-code-assist]

To ensure feature parity with the standard Deployment template and complete the metadata passthrough for KubeRay, we should also pass through modelSpec.podLabels to the head pod template metadata.

        labels:
          model: {{ $modelSpec.name }}
          helm-release-name: {{ .Release.Name }}
          {{- include "chart.engineLabels" . | nindent 10 }}
          {{- with $modelSpec.podLabels }}
          {{- toYaml . | nindent 10 }}
          {{- end }}

[gemini-code-assist]

To ensure feature parity with the standard Deployment template and complete the metadata passthrough for KubeRay, we should also pass through modelSpec.podLabels to the worker pod template metadata.

          labels:
            model: {{ $modelSpec.name }}
            helm-release-name: {{ .Release.Name }}
            {{- include "chart.engineLabels" . | nindent 12 }}
            {{- with $modelSpec.podLabels }}
            {{- toYaml . | nindent 12 }}
            {{- end }}

[ruizhang0101]

LGTM