KubeRay 源码阅读：从 RayJob 看组件分工与协作
内容提要
本文沿一次 RayJob 提交过程追踪 KubeRay 源码：RayJob Controller 根据 spec.rayClusterSpec 创建专用 RayCluster，RayCluster Controller 再创建 head 与 worker Pod；集群就绪后以 K8sJobMode 创建 submitter Job，通过 Ray Jobs API 提交入口程序并跟踪状态，结束后按 TTL 清理集群。
延伸解读
三种资源的选择逻辑
文章对比了 RayCluster、RayJob 和 RayService 三种资源。选择哪种取决于希望 KubeRay 管理到哪一步：RayCluster 只管理集群本身，作业提交由使用者自行安排；RayJob 额外负责提交作业、跟踪状态并按策略清理；RayService 则面向持续提供服务的 Serve 应用，关注应用健康和访问入口。理解这一分工，有助于根据实际场景选用合适的资源类型。
状态分散在三个地方
一次 RayJob 提交后，执行状态分散在 RayJob CR、submitter Kubernetes Job 和 Ray 运行时中的 job 三处。RayJob CR 的状态反映 KubeRay 管理流程走到哪一步；submitter Job 的状态反映提交程序对应的 Pod 执行情况；Ray 作业状态则反映用户入口程序是否运行、成功或失败。排查问题时需要分别查看，不能仅凭某一处的状态判断程序已成功。
排查入口：从资源状态定位组件
文章提供了一张排查表，根据观察到的现象定位下一步检查方向。例如，RayJob 已存在但专用 RayCluster 未创建，应检查 RayJob Controller 创建集群的分支；RayCluster 已存在但 Pod 未创建，应检查 RayCluster Controller 的资源创建过程；集群 Ready 但 submitter Job 未创建，则需关注 Dashboard 地址获取和提交用 Job 的创建过程。这些入口帮助缩小问题范围。
收尾策略与保留内容
本例设置 shutdownAfterJobFinishes: true 和 ttlSecondsAfterFinished: 60，作业正常完成后等待 60 秒删除专用 RayCluster，并由 Kubernetes 按资源拥有关系回收下级资源。handleShutdownAfterJobFinishes 会保留 RayJob CR 和 submitter Job，以便查询状态和查看提交日志。但结果文件、日志和程序版本仍需另外归档，保留下来的 RayJob 对象主要记录声明与状态。
Q&A
KubeRay 中 RayJob、RayCluster 和 RayService 三种资源分别适合什么场景？
RayCluster 用于声明一套 Ray 集群配置，由 KubeRay 管理集群所需的 Pod、Service 和集群状态；RayJob 用于提交一次作业，需要指定入口命令、运行环境、集群来源和收尾要求，KubeRay 会准备集群、提交作业、跟踪执行并按策略清理；RayService 面向持续提供服务的 Ray Serve 应用，管理承载应用的集群、Serve 部署、健康检查和访问入口。
提交一个 RayJob 后，RayCluster、head Pod、worker Pod 和 submitter Job 分别由谁创建？
RayJob Controller 根据 spec.rayClusterSpec 创建专用 RayCluster；RayCluster Controller 再创建 head Service、head Pod 和 worker Pod；集群就绪后，RayJob Controller 在 K8sJobMode 下创建 submitter Job，由 Kubernetes Job 控制器创建 submitter Pod 来运行提交程序。
RayJob 的 status 中 jobDeploymentStatus 和 jobStatus 有什么区别？
jobDeploymentStatus 描述 KubeRay 管理流程走到哪一步，例如创建提交用 Job 后会被设为 Running；jobStatus 反映 Ray 作业本身的状态。jobDeploymentStatus 为 Running 不能单独证明用户程序已经进入 Ray 的 RUNNING 状态，判断程序是否成功还要看 Ray 作业结果和 RayJob 后续状态。
RayJob 使用 K8sJobMode 时，submitter Pod 如何提交入口程序？
submitter Pod 运行 Ray CLI，通过 head Service 访问 Dashboard 的 Jobs API。BuildJobSubmitCommand 拼接提交命令，核心形态类似 ray job submit --address=http://<head-service>:8265 --submission-id=<submission-id> --no-wait -- python /app/main.py。命令带 --no-wait，提交返回后 submitter 容器可能继续运行以跟踪日志。
RayJob 设置 shutdownAfterJobFinishes 和 ttlSecondsAfterFinished 后，作业结束会保留和清理哪些资源？
对于正常完成的作业，Controller 按结束时间计算等待期限，到期后删除专用 RayCluster，再由 Kubernetes 按资源拥有关系回收下级资源。handleShutdownAfterJobFinishes 会保留 RayJob CR 和提交用的 Kubernetes Job，以便查询状态和查看提交日志；结果文件、日志和程序版本仍需另外归档。
如果 RayCluster 已经 Ready 但还没有 submitter Job，应该检查什么？
可以检查 RayJob 的准备状态、Dashboard 地址获取和提交用 Job 的创建过程。RayJob Controller 在集群就绪后会获取 Dashboard 地址并推进提交，若这一步未完成，submitter Job 就不会被创建。
