KubeRay 源码阅读：Operator 重启后如何继续工作
内容提要
KubeRay Operator 重启后不依赖内存状态，而是通过 Kubernetes 中持久化的 spec、status 及已有资源恢复协调。RayJob 使用 jobDeploymentStatus 记录管理阶段，jobStatus 记录 Ray 作业状态。重启不会被记为失败或开启新执行轮次；若资源已创建但状态未写回，新 Operator 会根据 status 中的集群名和 submission ID 查找并复用已有资源。Ray 服务端以 submission ID 防止重复提交，但无法保证业务层面的 exactly-once。
延伸解读
恢复依赖持久化状态，而非内存
Operator 重启后，进程内的缓存、队列和局部变量全部丢失，但 Kubernetes 中的 spec、status 以及已创建的资源对象仍然存在。新 Operator 通过监听和同步这些对象，重新构建协调请求，从而继续工作。这意味着恢复能力取决于外部持久化的信息是否完整，尤其是 status 中保存的集群名和 submission ID 等身份字段，它们决定了后续查找和复用哪套资源。
重试与重启是两回事
Operator 重启本身不会被记为执行失败，也不会自动开启新的执行轮次。只有 RayJob 级重试（由 spec.backoffLimit 控制）才会触发新轮次，此时会删除旧 RayCluster 和 submitter Job，清空身份并重新初始化。而 submitterConfig.backoffLimit 只控制提交程序自身的重试，不改变 Ray 作业身份。排查时需区分当前处于哪个阶段，避免将重启误判为失败重试。
资源复用不等于业务 exactly-once
当资源已创建但状态未写回时，新 Operator 会根据 status 中的名称查找并复用已有资源，避免重复创建。然而，Kubernetes 写入、Ray 提交与用户程序向外部写结果之间没有事务保证。Ray 服务端通过 submission ID 防止重复提交，但该检查仅在记录存在时有效，且无法覆盖外部系统的写入。若业务要求 exactly-once，仍需依赖数据库唯一键、事务或应用层去重。
删除与计算恢复的边界
删除 RayJob 时，finalizer 确保 Controller 有机会调用 StopJob，但代码并不等待 Ray 确认停止，因此不能保证优雅停止。owner reference 负责级联回收资源，但 Operator 重启不会触发删除。此外，RayJob 状态不保存进程内存和计算中间结果，若 head、driver 或 worker 故障，需依赖 Ray 自身的恢复机制或用户检查点。GCS 元数据也可能因配置而丢失，不能视为永久保存。
Q&A
KubeRay Operator 重启后，如何恢复对 RayJob 的协调？
Operator 重启后不依赖内存状态，而是通过 Kubernetes 中持久化的 spec、status 以及已有资源（如 RayCluster、Job、Pod）重新建立协调。新进程启动监听并同步已有对象，初始同步会将符合监听条件的对象交给事件处理器，形成待协调请求，从而继续工作。
RayJob 的 jobDeploymentStatus 和 jobStatus 分别代表什么？
jobDeploymentStatus 表示 KubeRay 管理流程的阶段（如 Initializing、Running、Retrying 等），而 jobStatus 表示 Ray 入口程序的状态（如 RUNNING、SUCCEEDED 等）。两者可能不同步，例如创建 submitter Job 后 jobDeploymentStatus 进入 Running，但 jobStatus 可能还未变为 RUNNING。
如果 Operator 在创建 submitter Job 后、更新 RayJob 状态前退出，重启后会重复创建 Job 吗？
不会。新 Operator 会再次处理 Initializing 分支，调用 createK8sJobIfNeed 查询同名 Job，发现已存在则直接复用并继续推进状态。如果创建响应丢失，Operator 可能再次发出创建请求，但同名对象不能重复创建，服务端会拒绝冲突，后续协调再读取已有对象。
Ray 服务端如何防止同一个作业被重复提交？
Ray Jobs 服务在启动作业前，会尝试将 submission ID 写入 GCS 的内部键值存储，且不覆盖已有键。如果记录已存在，重复提交会被拒绝并抛出错误。但该检查仅在记录仍存在时有效，且不能保证业务层面的 exactly-once。
RayJob 重试时，哪些状态会被重置？
进入 Retrying 后，Controller 会删除旧 RayCluster 和 submitter Job，待确认删除完成后，清空本轮集群名、submission ID 等状态，回到 New 阶段。自动生成的集群名和 submission ID 会重新生成，但显式设置的 spec.jobId 仍会被采用。
Operator 重启后，如何排查 RayJob 的恢复情况？
应先核对当前执行轮次的集群名和 submission ID，再检查 Kubernetes 对象是否存在、Ray 是否仍保存对应作业记录。若已进入新的执行轮次，还需核对前一次执行留下的外部结果。恢复动作由当前阶段决定，需同时查看保存的阶段和实际对象。
