[Bug]: Helm upgrade rolls new proxy pods before the migration Job completes

快速结论：该问题出现在使用 LiteLLM 单体（monolithic）Helm chart 执行 upgrade 且本次升级包含 schema 迁移时：由于 migrationJob.hooks.helm.enabled 默认为 false，迁移 Job 只是普通资源，不具备 pre-upgrade 屏障作用，新 proxy Pod 可能在迁移完成前就被滚动。优先排查迁移 Job 是否带有 pre-upgrade hook 注解，以及 chart 与 values 中该开关的实际取值。

适用环境：LiteLLM 1.106.0；上游 main 版本或 commit 为 d8c0e2c7153d82234ec46f0231bf9b9714e7d52a（2026-10-08 UTC 验证）及 e38187324a（2026-11-14 复核）；部署方式为 Helm chart、monolithic，并配合 schema 迁移；Issue 也列出了 Docker、Terraform 作为相关范围，但实际复现路径是 Helm 渲染与 upgrade。Issue 明确说明审计时未使用 Kubernetes 集群，因此没有实机运行结果。

最快修复方案：暂无确认的一键修复方案。Issue 的最终结论是：旧 litellm-helm chart 已被 #43330 移除，替代 chart 默认启用 migrationJob 与 Helm hooks，并渲染 pre-install,pre-upgrade hook，从而在源码层面消除该问题；此结论基于源码与模板验证，没有新的在线 proxy 结果。

注意事项：Issue 的范围不含 componentized chart，也不涉及显式启用迁移 hook 的配置，这些场景不要直接套用本结论。若仍在使用被移除的旧 chart 或自定义 values 覆盖了 hook 开关，需要以实际渲染出的 Job 注解和 Deployment 顺序为准。另外，源码验证不等于集群实测，升级前建议先在测试环境确认。

问题场景

用户使用 LiteLLM 单体（monolithic）Helm chart 做升级，同时本次升级会修改 proxy 镜像并包含数据库 schema 迁移。按默认 values，migrationJob.enabled: true，但 migrationJob.hooks.helm.enabled: false（ArgoCD hook 为 true，Helm hook 为 false）。此时渲染出的迁移 Job 是普通资源，没有 pre-upgrade hook 注解。Helm 在 upgrade 时可能先创建或滚动新的 Deployment，而 Deployment 以关闭 schema 更新的方式启动新镜像，结果是应用在迁移 Job 完成前就开始运行。

报错原文

[Bug]: Helm upgrade rolls new proxy pods before the migration Job completes

原因分析

最可能的原因是迁移 Job 的 Helm hook 开关为默认关闭状态。Helm 只对带有 pre-upgrade 等 hook 注解的资源施加升级顺序约束；当 migrationJob.hooks.helm.enabled: false 时，迁移 Job 与 Deployment 同属普通资源，Helm 没有把迁移完成作为新应用滚动的前置条件。Issue 明确指出，这一顺序结论来自渲染后的资源类型与条件，而不是集群实测。

环境排查

确认 LiteLLM 版本：Issue 报告为 1.106.0，并核对上游 commit 是否为 d8c0e2c7153d82234ec46f0231bf9b9714e7d52a 或更新的复核 commit e38187324a。
确认所用 chart：是否仍是被 #43330 移除的旧 litellm-helm chart，还是替代 chart。
确认部署模式：monolithic 还是 componentized；本 Issue 只覆盖 monolithic。
检查 values 中 migrationJob.enabled、migrationJob.hooks.helm.enabled、migrationJob.hooks.argocd.enabled 的实际取值，注意默认值可能被本地 values 覆盖。
渲染 chart 后检查迁移 Job 是否带有 pre-install,pre-upgrade hook 注解，以及 Deployment 的启动条件。
确认本次升级是否确实涉及 schema 迁移；无迁移时该顺序问题不一定触发。

解决步骤

先渲染当前 chart（不直接 upgrade），查看迁移 Job 的 metadata 是否有 pre-upgrade hook 注解。若没有，即可确认处于 Issue 描述的状态。
核对当前使用的 chart 是否为已被 #43330 移除的旧 litellm-helm；若是，迁移到替代 chart，替代 chart 默认 migrationJob 和 Helm hook 为 true。
若仍使用支持 monolith 模式的 chart，检查 values 是否把 migrationJob.hooks.helm.enabled 显式设为 false；Issue 未给出具体的覆盖写法，请以所选 chart 版本的 values 定义为准，不要编造键名或参数。
重新渲染并确认迁移模板输出 pre-install,pre-upgrade hook，再执行 upgrade，使 schema 迁移成为新 Pod 滚动前的屏障。
若使用 ArgoCD 编排，注意示例配置中 ArgoCD hook 与 Helm hook 是分开的开关；Issue 未验证两者组合后的行为，必要时分别核实。

验证方法

在渲染结果中确认迁移 Job 带有 pre-install,pre-upgrade hook 注解，并且 upgrade 过程中新 proxy Deployment 不会在迁移 Job 成功前滚动。Issue 的最终结论仅完成源码与模板层面的验证，没有在线 proxy 实测结果，因此在集群中实际观察 upgrade 顺序仍是必要的补充验证。