执行摘要

• 一句话：修复 Helm 资源引用：统一 selector、Pod 标签与 HPA 目标
• 推荐动作：建议阅读。虽然是个小 bugfix，但展示了 Helm chart 维护的典型最佳实践：用 include helper 收敛资源命名与标签生成，避免同一 chart 内多处硬编码命名漂移；同时用 helm-unittest 锁住渲染输出，防止回归。值得关注的设计决策是新增 chart.deployment-name helper，让 HPA 与 Deployment 共享同一命名来源。

功能与动机

PR body 明确指出：The Service selector used configured labels, while the Deployment selector and Pod labels were hard-coded to test/test. The HPA targeted a non-existent Deployment named vllm。当用户自定义 labels 并启用 autoscaling 时，这些不一致会导致 Service 无法选中 Pod、HPA 无法关联 Deployment，部署资源形同失效。

实现拆解

1. 在 examples/deployment/chart-helm/templates/_helpers.tpl 中新增 chart.deployment-name helper，按 .Release.Name 统一生成 <release>-deployment-vllm 命名；同时把 chart.service-name 的 fallback 分支从引号拼接改为 printf 生成，减少引号干扰。
2. 修改 examples/deployment/chart-helm/templates/deployment.yaml：metadata.name 改用 chart.deployment-name，selector.matchLabels 与 template.metadata.labels 从硬编码 test/test 改为复用 chart.labels helper，与 Service 的 selector 来源保持一致。
3. 修改 examples/deployment/chart-helm/templates/hpa.yaml：scaleTargetRef.name 从固定字符串 vllm 改为 include chart.deployment-name，确保 HPA 指向本 release 实际创建的 Deployment。
4. 修改 examples/deployment/chart-helm/templates/service.yaml：metadata.name 改用 chart.service-name helper，使 service 命名与测试断言有统一来源。
5. 配套调整：Chart.yaml 版本从 0.0.1 升到 0.0.2；values.schema.json 将 serviceName 类型从 null 扩展为 null|string，修复 schema 校验；新增 tests/service_test.yaml 与 tests/hpa_test.yaml 测试套件，并在 tests/deployment_test.yaml 中补充 labels 断言。作者已通过 helm lint、helm unittest 与 helm template 渲染对比验证。

关键文件：

• examples/deployment/chart-helm/templates/_helpers.tpl（模块 部署模板；类别 infra；类型 infrastructure；符号 chart.service-name, chart.deployment-name）: 核心变更文件：新增 chart.deployment-name helper，统一 Deployment 命名来源；同时调整 chart.service-name 的生成方式，是本次修复的命名收敛基石。
• examples/deployment/chart-helm/templates/deployment.yaml（模块 部署模板；类别 infra；类型 infrastructure）: 修复 Deployment 的 selector 与 Pod 标签从硬编码 test/test 改为复用 chart.labels，是本次核心行为修正点。
• examples/deployment/chart-helm/templates/hpa.yaml（模块 部署模板；类别 infra；类型 infrastructure）: 修复 HPA target 从固定 vllm 改为 release 相关的 Deployment 名称，是本次 bug 的直接触发点之一。
• examples/deployment/chart-helm/templates/service.yaml（模块 部署模板；类别 infra；类型 infrastructure）: Service 的 metadata.name 改用 chart.service-name helper，保持命名生成方式与其他资源一致。
• examples/deployment/chart-helm/tests/service_test.yaml（模块 部署模板；类别 test；类型 test-coverage）: 新增测试套件，锁定 Service 名称与 selector 的渲染行为，防止后续回归。
• examples/deployment/chart-helm/tests/hpa_test.yaml（模块 部署模板；类别 test；类型 test-coverage）: 新增测试套件，验证 HPA 的 scaleTargetRef.name 指向本 release 创建的 Deployment。
• examples/deployment/chart-helm/tests/deployment_test.yaml（模块 部署模板；类别 test；类型 test-coverage）: 补充 Deployment selector 与 Pod labels 的自定义标签断言，直接覆盖本次修复的行为。
• examples/deployment/chart-helm/values.schema.json（模块 部署模板；类别 infra；类型 configuration）: 修复 serviceName 的 JSON Schema 类型，从仅 null 扩展为 null|string，保障 helm lint 通过。
• examples/deployment/chart-helm/Chart.yaml（模块 部署模板；类别 infra；类型 configuration）: chart 版本从 0.0.1 升至 0.0.2，标识本次模板行为变更。

关键符号：chart.deployment-name, chart.service-name, chart.labels

关键源码片段

examples/deployment/chart-helm/templates/_helpers.tpl

核心变更文件：新增 chart.deployment-name helper，统一 Deployment 命名来源；同时调整 chart.service-name 的生成方式，是本次修复的命名收敛基石。

{{/*
定义 service 名称：优先使用用户配置的 serviceName，
否则按 release 名生成，统一命名来源。
*/}}
{{- define "chart.service-name" -}}
{{- if .Values.serviceName }}
{{- .Values.serviceName | lower | trim }}
{{- else }}
{{- printf "%s-service" .Release.Name }}
{{- end }}
{{- end }}
​
{{/*
新增 deployment 名称 helper：统一 HPA 与 Deployment 的命名，
修复 HPA 硬编码指向 vllm 导致 target 不存在的问题。
*/}}
{{- define "chart.deployment-name" -}}
{{- printf "%s-deployment-vllm" .Release.Name }}
{{- end }}

examples/deployment/chart-helm/templates/deployment.yaml

修复 Deployment 的 selector 与 Pod 标签从硬编码 test/test 改为复用 chart.labels，是本次核心行为修正点。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "chart.deployment-name" . | quote }}
  namespace: {{ .Release.Namespace }}
  labels:
    {{- include "chart.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  {{- include "chart.strategy" . | nindent 2 }}
  selector:
    matchLabels:
      # 复用 chart.labels，与 Service selector 保持一致，
      # 自定义 labels 下发时 Deployment 才能被 Service 正确选中
      {{- include "chart.labels" . | nindent 6 }}
  template:
    metadata:
      labels:
        # Pod 标签同样复用 chart.labels，确保 selector 能匹配新 Pod
        {{- include "chart.labels" . | nindent 8 }}

examples/deployment/chart-helm/templates/hpa.yaml

修复 HPA target 从固定 vllm 改为 release 相关的 Deployment 名称，是本次 bug 的直接触发点之一。

spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    # 原先硬编码为 vllm，指向不存在的 Deployment；
    # 现在按 release 名生成，确保 HPA 关联到本 release 创建的 Deployment
    name: {{ include "chart.deployment-name" . | quote }}
  minReplicas: {{ .Values.autoscaling.minReplicas }}
  maxReplicas: {{ .Values.autoscaling.maxReplicas }}

评论区精华

该 PR 没有实质性的技术讨论。唯一 review 来自维护者 chaunceyjiang，直接批复 LGTM 并合并。作者在 issue 评论中请求 @russellb 与 @DarkLight1337 审查，随后通过 /ci run 触发 Buildkite CI #83872。Claude bot 因 PR 来自 fork 自动跳过审查。整体过程顺畅，无未解决的疑虑。

• 请求 committers 审查与 CI 触发 (other): 维护者 chaunceyjiang 直接批准（LGTM）并合并，无技术性反对意见。

风险与影响

• 风险：render 行为变化：升级到 0.0.2 后，Deployment selector 与 Pod 标签不再固定为 test/test，HPA target 从 vllm 变为 <release>-deployment-vllm。若用户已按旧硬编码标签维护 NetworkPolicy、PDB 等自定义资源，升级后可能出现不匹配，需同步更新。
  deployment 与 hpa 现在都依赖 chart.labels 与 chart.deployment-name helper；若用户未配置 labels 且 labels helper 缺少默认 fallback，selector 可能渲染为空。本次上下文未完整提供 chart.labels 的实现，存在少量不确定性，建议合并后确认默认值路径。
  values.schema.json 的 serviceName 类型放开为 null|string 属于 schema 修正，对既有配置无破坏。整体风险较低，且已有 helm-unittest 测试锁住关键渲染输出。

• 影响：影响面集中在使用 examples/deployment/chart-helm 自建部署的 Kubernetes 用户，尤其是自定义 labels 与启用 HPA 的场景。修复后 Service、Deployment、HPA 三者引用一致，部署资源可正常工作。对 vLLM 推理路径、模型输出与性能均无影响，属于部署可用性修复，影响程度低到中。对示例 chart 维护者而言，这是一次规范性收口，后续命名与标签都应通过 helper 生成。

• 风险标记：Helm 模板渲染行为变化, 依赖 chart.labels 默认值, 示例 chart 影响范围有限

关联脉络

• 暂无明显关联 PR