KubeRay RayJob 快速上手在 Kubernetes 上按需拉起 Ray 集群并自动提交与回收 Ray 作业【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray本指南以当前 Ray 仓库中 rayjob-quick-start.md 为核心系统讲解 KubeRay 的 RayJob 自定义资源它如何把「RayCluster 集群生命周期」与「Ray 作业提交与执行」两个环节编排到一起在作业就绪时自动提交、在作业完成后按策略自动回收集群资源。读完本文你将掌握 RayJob 全部核心配置字段提交模式、资源清理、删除策略等并能用 10 个命令在 Kind 集群上完整跑通一个 RayJob 从创建、验证到清理的全流程。前置条件与版本兼容性使用 RayJob 需要满足 KubeRay 与 Ray 的版本搭配要求KubeRay 版本最低 Ray 版本说明v0.6.0 / v1.0.0Ray 1.10支持基础 RayJob 能力v1.1.1 及以上强烈推荐Ray 2.8.0推荐使用功能更完整部分高级特性还有额外版本门槛例如SidecarSubmitterRestart特性门控要求KubeRay v1.7、Ray v2.54.0、Kubernetes v1.35详见 RayJob SidecarSubmitterRestart 指南。本文的实操示例基于 KubeRay v1.7.0。什么是 RayJob一次理解三个易混淆的概念KubeRay 的 RayJob 是一个 Kubernetes 自定义资源CRD它同时管理两个方面RayClusterRayCluster 自定义资源管理一个 Ray 集群内的所有 Pod包括一个 head Pod 和若干 worker PodJobsubmitter一个 Kubernetes Job 负责执行ray job submit把 Ray 作业提交到上面创建的 RayCluster 上。理解以下三个概念的差异有助于阅读后文RayJob由 KubeRay 提供的 Kubernetes 自定义资源定义是本文的主角Ray job一个打包好的 Ray 应用程序可以运行在远端 Ray 集群上对应 Ray 的 Jobs 概念Submitter一个 Kubernetes Job其入口即ray job submit命令负责把 Ray job 提交进 RayCluster。RayJob 能带来什么借助 RayJobKubeRay 会自动创建 RayCluster并在集群就绪后自动提交 Ray 作业同时你可以配置 RayJob让它在 Ray 作业结束后自动删除 RayCluster。这带来两个典型价值按需调度提交任务时集群才创建配合 Kueue 等批调度器可实现排队与抢占资源回收作业跑完自动销毁集群避免空闲集群持续占用节点资源。RayJob 配置详解RayJob 的spec可以拆成四类配置RayCluster 配置、Ray job 配置、提交配置、自动资源清理配置外加少量其它字段。RayCluster 配置rayClusterSpec定义用于运行 Ray 作业的RayCluster自定义资源。该字段与独立 RayCluster 资源的spec结构一致包括rayVersion、headGroupSpec、workerGroupSpecs等。当前仓库中的 ray-cluster.complete.yaml 给出了一个字段最完整的 RayCluster 示例head 组通过rayStartParams配置ray start参数port、dashboard-host、block、num-cpus、resources等并通过template.spec.containers定义 head 容器镜像与资源worker 组通过workerGroupSpecs列表定义每组包含replicas、groupName、rayStartParams、Pod 模板等。RayJob 的rayClusterSpec结构与之完全一致。clusterSelector不新建集群而是复用已存在的 RayCluster自定义资源来运行 Ray 作业示例可参考 KubeRay 仓库ray-operator/config/samples/ray-job.use-existing-raycluster.yaml。Ray job 配置entrypointsubmitter 实际执行的命令形如ray job submit --address ... --submission-id ... -- $entrypointentrypoint即你要运行的作业入口例如python /home/ray/samples/sample_code.py。runtimeEnvYAML可选KubeRay v1.0.0 新增描述 Ray 作业运行所需的运行时环境依赖文件、pip 包、环境变量等以多行 YAML 字符串形式提供。示例spec: runtimeEnvYAML: | pip: - requests2.26.0 - pendulum2.1.2 env_vars: KEY: VALUE更完整的 runtimeEnv 字段说明可参考 Ray 的 Runtime Environments 文档。jobId可选指定 Ray 作业的 submission ID未提供时由 KubeRay 自动生成。该 ID 对应ray job submit --submission-id的语义。metadata可选对应ray job submit的--metadata-json选项用于给作业附加元数据。entrypointNumCpus/entrypointNumGpus/entrypointResources可选为作业入口分配 CPU / GPU / 自定义资源配额。backoffLimit可选v1.2.0 新增RayJob 失败前允许重试的次数每次重试都会新建一个 RayCluster默认值为 0。注意它与 submitter 的backoffLimit默认 2含义不同。提交配置submissionMode可选指定 RayJob 向 RayCluster 提交作业的方式默认值为K8sJobMode共四种取值取值机制备注K8sJobMode默认KubeRay operator 创建一个 submitter Kubernetes Job 来提交 Ray 作业与 Ray 镜像隔离作业日志在 submitter 中HTTPModeKubeRay operator 直接向 RayCluster 发 HTTP 请求创建 Ray 作业无需额外提交容器InteractiveModeKubeRay operator 等待用户手动向 RayCluster 提交作业目前为 alphaKubeRay kubectl 插件 依赖此模式SidecarModeKubeRay operator 在 Ray head Pod 内注入一个 sidecar 容器提交作业不支持clusterSelector与submitterPodTemplate要求 head Pod 的restartPolicy为NeverSidecarMode的额外说明启用SidecarSubmitterRestart特性门控需 KubeRay v1.7、Ray v2.54.0、Kubernetes v1.35后可用submitterConfig.backoffLimit限制 submitter sidecar 的重启次数。该模式下的提交容器与 head 容器同 Pod 通信localhost日志可直接输出到 STDOUT/STDERR但副作用是提交者的生命周期与 head Pod 强耦合当SidecarSubmitterRestart启用时提交容器在容器级别使用OnFailure重启策略重启后会先检查 Ray 作业状态作业仍在运行则重新挂接日志流而不是重新提交。完整机制与版本偏差注意点参见 RayJob SidecarSubmitterRestart 指南。submitterPodTemplate可选定义 submitter Kubernetes Job 的 Pod 模板仅在submissionMode为K8sJobMode时生效。KubeRay operator 会向 submitter Pod 注入两个环境变量RAY_DASHBOARD_ADDRESS值为$HEAD_SERVICE:$DASHBOARD_PORT即 head 服务地址与 dashboard 端口RAY_JOB_SUBMISSION_ID值为RayJob.Status.JobId。典型的提交命令示例ray job submit --addresshttp://$RAY_DASHBOARD_ADDRESS --submission-id$RAY_JOB_SUBMISSION_ID ...。更完整的示例可参考 KubeRay 仓库ray-operator/config/samples/ray-job.sample.yaml。submitterConfig可选submitter 的附加配置K8sJobMode下始终生效SidecarMode在启用SidecarSubmitterRestart时内部也会遵守backoffLimit但该字段目前无法通过 RayJob 资源为SidecarMode设置KubeRay 的校验 webhook 会拒绝。backoffLimit可选v1.2.0 新增submitter 失败前的重试次数默认值为 2。SidecarSubmitterRestartv1.7 中为 alpha默认关闭允许 submitter 容器在瞬时故障时就地重启独立于 head Pod 的restartPolicy: Never。要求 Kubernetes v1.35 与 Ray v2.54.0完整的重启/重新挂接行为与版本偏差说明见上文提到的 Sidecar 指南。自动资源清理配置preRunningDeadlineSeconds可选若 RayJob 未能在该秒数内将JobDeploymentStatus转为RunningKubeRay operator 会将其转为Failed原因为PreRunningDeadlineExceeded。默认值 0不强制预运行期限。shutdownAfterJobFinishes可选Ray 作业结束后是否回收 RayCluster默认值为false。ttlSecondsAfterFinished可选仅在shutdownAfterJobFinishes为 true 时生效。Ray 作业结束ttlSecondsAfterFinished秒后operator 删除 RayCluster 与 submitter。默认值 0立即删除。activeDeadlineSeconds可选若 RayJob 未能在该秒数内将JobDeploymentStatus转为Complete或Failedoperator 将其转为Failed原因为DeadlineExceeded。DELETE_RAYJOB_CR_AFTER_JOB_FINISHES可选v1.2.0 新增注意这是设置给 KubeRay operator 的环境变量而非 RayJob 资源字段。若设为 true且同时设置了shutdownAfterJobFinishes: true则 RayJob 自定义资源本身也会被删除KubeRay 会一并删除 RayJob 创建的所有资源包括 Kubernetes Job。其它字段suspend可选若为 trueKubeRay 会同时删除 RayCluster 与 submitter。注意 Kueue 也通过修改该字段实现调度策略如果使用 Kueue 调度 RayJob请避免手动修改此字段。deletionStrategyv1.5.1 为 alphav1.6.0 为 beta配置 RayJob 进入终态后的自动清理需要启用RayJobDeletionPolicy特性门控。支持两种互斥风格规则式Rules-based推荐通过deletionRules定义由特定条件触发的删除动作列表。每条规则包含policy删除动作——DeleteCluster删除整个 RayCluster 及其 Pod、DeleteWorkers只删除 worker Pod、DeleteSelf删除 RayJob 及所有关联资源、DeleteNone不删除condition触发条件——基于jobStatusSUCCEEDED或FAILED与可选的ttlSeconds延迟。这种方式支持灵活的多阶段清理例如「作业成功时立即删除 worker300 秒后再删除整个集群」。规则式与shutdownAfterJobFinishes及全局ttlSecondsAfterFinished不兼容应改用规则内的condition.ttlSeconds。示例见 KubeRay 仓库ray-operator/config/samples/ray-job.deletion-rules.yaml。传统式Legacy已废弃同时定义onSuccess与onFailure策略。该方式将在 v1.6.0 中移除强烈建议迁移到deletionRules。传统式可与shutdownAfterJobFinishes及全局ttlSecondsAfterFinished组合使用。完整的 API 规范请参考 KubeRay CRD API reference。实战10 步在 Kind 上跑通一个 RayJob以下步骤完整复现 RayJob 从创建到清理的全过程。Step 1用 Kind 创建 Kubernetes 集群kind create cluster --imagekindest/node:v1.26.0Step 2安装 KubeRay operator按照 KubeRay Operator Installation 安装最新稳定版 operator。推荐用 Helm 方式v1.7.0helm repo add kuberay https://ray-project.github.io/kuberay-helm/ helm repo update kubectl create namespace ray-system helm install kuberay-operator kuberay/kuberay-operator --version 1.7.0 -n ray-systemKubeRay 也支持 Kustomize 安装kubectl create -k github.com/ray-project/kuberay/ray-operator/config/default?refv1.7.0 -n ray-system。安装后用kubectl get pods -n ray-system确认 operator Pod 处于 Running 状态。Step 3安装 RayJob 示例kubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.sample.yaml该 YAML 位于 KubeRay 仓库ray-operator/config/samples/ray-job.sample.yaml也可先下载到本地再kubectl apply -f。Step 4验证 Kubernetes 集群状态# Step 4.1列出 default 命名空间下所有 RayJob 自定义资源 kubectl get rayjob # [示例输出] # NAME JOB STATUS DEPLOYMENT STATUS RAY CLUSTER NAME START TIME END TIME AGE # rayjob-sample SUCCEEDED Complete rayjob-sample-qnftt 2025-06-25T16:21:21Z 2025-06-25T16:22:35Z 6m53s # Step 4.2列出所有 RayCluster 自定义资源 kubectl get raycluster # [示例输出] # NAME DESIRED WORKERS AVAILABLE WORKERS CPUS MEMORY GPUS STATUS AGE # rayjob-sample-qnftt 1 1 400m 0 0 ready 7m48s # Step 4.3列出 default 命名空间下所有 Pod # 由 Kubernetes Job 创建的 Pod 在 Job 结束后会被终止 kubectl get pods # [示例输出] # kuberay-operator-755f666c4b-wbcm4 1/1 Running 0 8m32s # rayjob-sample-n2vj5 0/1 Completed 0 7m18ss Pod created by a Kubernetes Job # rayjob-sample-qnftt-head 1/1 Running 0 8m14s # rayjob-sample-qnftt-small-group-worker-4f5wz 1/1 Running 0 8m14s # Step 4.4检查 RayJob 状态 # 作业结束后RayJob 的 jobStatus 字段会被更新为 SUCCEEDEDjobDeploymentStatus 应为 Complete kubectl get rayjobs.ray.io rayjob-sample -o jsonpath{.status.jobStatus} # [期望输出]: SUCCEEDED kubectl get rayjobs.ray.io rayjob-sample -o jsonpath{.status.jobDeploymentStatus} # [期望输出]: Complete这里的关键机制是KubeRay operator 依据rayClusterSpec创建 RayCluster 自定义资源同时创建一个 submitter Kubernetes Job 向集群提交 Ray 作业。示例中entrypoint为python /home/ray/samples/sample_code.py该脚本存放在挂载到 head Pod 的 Kubernetes ConfigMap 中。由于shutdownAfterJobFinishes默认值为 false作业结束后 operator不会删除 RayCluster 与 submitter。Step 5查看 Ray 作业输出kubectl logs -ljob-namerayjob-sample # [示例输出] # 2025-06-25 09:22:27,963 INFO worker.py:1654 -- Connecting to existing Ray cluster at address: 10.244.0.6:6379... # 2025-06-25 09:22:27,977 INFO worker.py:1832 -- Connected to Ray cluster. View the dashboard at 10.244.0.6:8265 # test_counter got 1 # test_counter got 2 # test_counter got 3 # test_counter got 4 # test_counter got 5 # 2025-06-25 09:22:31,719 SUCC cli.py:63 -- ----------------------------------- # 2025-06-25 09:22:31,719 SUCC cli.py:64 -- Job rayjob-sample-zdxm6 succeeded # 2025-06-25 09:22:31,719 SUCC cli.py:65 -- -----------------------------------日志显示作业先连接已有 Ray 集群head 地址为10.244.0.6:6379dashboard 为8265随后执行计数器递增函数 5 次最终ray jobCLI 报告作业成功。entrypoint使用的sample_code.py就是一个执行 5 次计数器递增函数的简单 Ray 脚本。Step 6删除 RayJobkubectl delete -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.sample.yamlStep 7创建启用shutdownAfterJobFinishes的 RayJobkubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.shutdown.yamlray-job.shutdown.yaml定义的 RayJob 设置了shutdownAfterJobFinishes: true与ttlSecondsAfterFinished: 10因此 operator 会在作业结束后10 秒删除 RayCluster。注意 submitter Job 不会被删除——它保存着 Ray 作业日志且完成后不占用集群资源RayJob 通过 owner reference 关联 submitter当 RayJob 最终被删除时submitter 会随之清理。Step 8检查 RayJob 状态# 等待 jobStatus 变为 SUCCEEDED、jobDeploymentStatus 变为 Complete kubectl get rayjobs.ray.io rayjob-sample-shutdown -o jsonpath{.status.jobDeploymentStatus} kubectl get rayjobs.ray.io rayjob-sample-shutdown -o jsonpath{.status.jobStatus}Step 9确认 KubeRay operator 已删除 RayCluster# 列出 default 命名空间下的 RayCluster与 RayJob rayjob-sample-shutdown 关联的集群应已被删除 kubectl get rayclusterStep 10清理环境# Step 10.1删除 RayJob kubectl delete -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.shutdown.yaml # Step 10.2卸载 KubeRay operator helm uninstall kuberay-operator # Step 10.3删除 Kubernetes 集群 kind delete cluster状态机与关键实现逻辑小结从上面的验证命令可以看到RayJob 生命周期由两个状态字段共同刻画jobStatus对应 Ray 作业本身的状态如SUCCEEDED/FAILED/RUNNING由提交结果反馈更新jobDeploymentStatus对应 RayJob 资源的部署状态如Running/Complete/Failed由 operator 依据preRunningDeadlineSeconds、activeDeadlineSeconds、作业终态等条件推进。理解这一点有助于正确组合配置例如「作业成功立即删 worker、延迟删集群」的多阶段清理可以通过deletionRules实现「严格按时回收」则依赖shutdownAfterJobFinishesttlSecondsAfterFinished「杜绝作业跑完集群还挂着」则需要显式把shutdownAfterJobFinishes置为 true因为其默认值为 false。下一步学习路径批处理示例RayJob Batch Inference Example文中引用的 Kuberay 批处理推断示例与 Kueue 配合Priority Scheduling with RayJob and Kueue、Gang Scheduling with RayJob and Kueue集群细节阅读 ray-cluster.complete.yaml 了解rayClusterSpec可用的完整字段进阶提交模式RayJob SidecarSubmitterRestart 指南 与 KubeRay kubectl 插件【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 KubeRay RayJob 快速上手：在 Kubernetes 上按需拉起 Ray 集群并自动提交与回收 Ray 作业
KubeRay RayJob 快速上手在 Kubernetes 上按需拉起 Ray 集群并自动提交与回收 Ray 作业【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray本指南以当前 Ray 仓库中 rayjob-quick-start.md 为核心系统讲解 KubeRay 的 RayJob 自定义资源它如何把「RayCluster 集群生命周期」与「Ray 作业提交与执行」两个环节编排到一起在作业就绪时自动提交、在作业完成后按策略自动回收集群资源。读完本文你将掌握 RayJob 全部核心配置字段提交模式、资源清理、删除策略等并能用 10 个命令在 Kind 集群上完整跑通一个 RayJob 从创建、验证到清理的全流程。前置条件与版本兼容性使用 RayJob 需要满足 KubeRay 与 Ray 的版本搭配要求KubeRay 版本最低 Ray 版本说明v0.6.0 / v1.0.0Ray 1.10支持基础 RayJob 能力v1.1.1 及以上强烈推荐Ray 2.8.0推荐使用功能更完整部分高级特性还有额外版本门槛例如SidecarSubmitterRestart特性门控要求KubeRay v1.7、Ray v2.54.0、Kubernetes v1.35详见 RayJob SidecarSubmitterRestart 指南。本文的实操示例基于 KubeRay v1.7.0。什么是 RayJob一次理解三个易混淆的概念KubeRay 的 RayJob 是一个 Kubernetes 自定义资源CRD它同时管理两个方面RayClusterRayCluster 自定义资源管理一个 Ray 集群内的所有 Pod包括一个 head Pod 和若干 worker PodJobsubmitter一个 Kubernetes Job 负责执行ray job submit把 Ray 作业提交到上面创建的 RayCluster 上。理解以下三个概念的差异有助于阅读后文RayJob由 KubeRay 提供的 Kubernetes 自定义资源定义是本文的主角Ray job一个打包好的 Ray 应用程序可以运行在远端 Ray 集群上对应 Ray 的 Jobs 概念Submitter一个 Kubernetes Job其入口即ray job submit命令负责把 Ray job 提交进 RayCluster。RayJob 能带来什么借助 RayJobKubeRay 会自动创建 RayCluster并在集群就绪后自动提交 Ray 作业同时你可以配置 RayJob让它在 Ray 作业结束后自动删除 RayCluster。这带来两个典型价值按需调度提交任务时集群才创建配合 Kueue 等批调度器可实现排队与抢占资源回收作业跑完自动销毁集群避免空闲集群持续占用节点资源。RayJob 配置详解RayJob 的spec可以拆成四类配置RayCluster 配置、Ray job 配置、提交配置、自动资源清理配置外加少量其它字段。RayCluster 配置rayClusterSpec定义用于运行 Ray 作业的RayCluster自定义资源。该字段与独立 RayCluster 资源的spec结构一致包括rayVersion、headGroupSpec、workerGroupSpecs等。当前仓库中的 ray-cluster.complete.yaml 给出了一个字段最完整的 RayCluster 示例head 组通过rayStartParams配置ray start参数port、dashboard-host、block、num-cpus、resources等并通过template.spec.containers定义 head 容器镜像与资源worker 组通过workerGroupSpecs列表定义每组包含replicas、groupName、rayStartParams、Pod 模板等。RayJob 的rayClusterSpec结构与之完全一致。clusterSelector不新建集群而是复用已存在的 RayCluster自定义资源来运行 Ray 作业示例可参考 KubeRay 仓库ray-operator/config/samples/ray-job.use-existing-raycluster.yaml。Ray job 配置entrypointsubmitter 实际执行的命令形如ray job submit --address ... --submission-id ... -- $entrypointentrypoint即你要运行的作业入口例如python /home/ray/samples/sample_code.py。runtimeEnvYAML可选KubeRay v1.0.0 新增描述 Ray 作业运行所需的运行时环境依赖文件、pip 包、环境变量等以多行 YAML 字符串形式提供。示例spec: runtimeEnvYAML: | pip: - requests2.26.0 - pendulum2.1.2 env_vars: KEY: VALUE更完整的 runtimeEnv 字段说明可参考 Ray 的 Runtime Environments 文档。jobId可选指定 Ray 作业的 submission ID未提供时由 KubeRay 自动生成。该 ID 对应ray job submit --submission-id的语义。metadata可选对应ray job submit的--metadata-json选项用于给作业附加元数据。entrypointNumCpus/entrypointNumGpus/entrypointResources可选为作业入口分配 CPU / GPU / 自定义资源配额。backoffLimit可选v1.2.0 新增RayJob 失败前允许重试的次数每次重试都会新建一个 RayCluster默认值为 0。注意它与 submitter 的backoffLimit默认 2含义不同。提交配置submissionMode可选指定 RayJob 向 RayCluster 提交作业的方式默认值为K8sJobMode共四种取值取值机制备注K8sJobMode默认KubeRay operator 创建一个 submitter Kubernetes Job 来提交 Ray 作业与 Ray 镜像隔离作业日志在 submitter 中HTTPModeKubeRay operator 直接向 RayCluster 发 HTTP 请求创建 Ray 作业无需额外提交容器InteractiveModeKubeRay operator 等待用户手动向 RayCluster 提交作业目前为 alphaKubeRay kubectl 插件 依赖此模式SidecarModeKubeRay operator 在 Ray head Pod 内注入一个 sidecar 容器提交作业不支持clusterSelector与submitterPodTemplate要求 head Pod 的restartPolicy为NeverSidecarMode的额外说明启用SidecarSubmitterRestart特性门控需 KubeRay v1.7、Ray v2.54.0、Kubernetes v1.35后可用submitterConfig.backoffLimit限制 submitter sidecar 的重启次数。该模式下的提交容器与 head 容器同 Pod 通信localhost日志可直接输出到 STDOUT/STDERR但副作用是提交者的生命周期与 head Pod 强耦合当SidecarSubmitterRestart启用时提交容器在容器级别使用OnFailure重启策略重启后会先检查 Ray 作业状态作业仍在运行则重新挂接日志流而不是重新提交。完整机制与版本偏差注意点参见 RayJob SidecarSubmitterRestart 指南。submitterPodTemplate可选定义 submitter Kubernetes Job 的 Pod 模板仅在submissionMode为K8sJobMode时生效。KubeRay operator 会向 submitter Pod 注入两个环境变量RAY_DASHBOARD_ADDRESS值为$HEAD_SERVICE:$DASHBOARD_PORT即 head 服务地址与 dashboard 端口RAY_JOB_SUBMISSION_ID值为RayJob.Status.JobId。典型的提交命令示例ray job submit --addresshttp://$RAY_DASHBOARD_ADDRESS --submission-id$RAY_JOB_SUBMISSION_ID ...。更完整的示例可参考 KubeRay 仓库ray-operator/config/samples/ray-job.sample.yaml。submitterConfig可选submitter 的附加配置K8sJobMode下始终生效SidecarMode在启用SidecarSubmitterRestart时内部也会遵守backoffLimit但该字段目前无法通过 RayJob 资源为SidecarMode设置KubeRay 的校验 webhook 会拒绝。backoffLimit可选v1.2.0 新增submitter 失败前的重试次数默认值为 2。SidecarSubmitterRestartv1.7 中为 alpha默认关闭允许 submitter 容器在瞬时故障时就地重启独立于 head Pod 的restartPolicy: Never。要求 Kubernetes v1.35 与 Ray v2.54.0完整的重启/重新挂接行为与版本偏差说明见上文提到的 Sidecar 指南。自动资源清理配置preRunningDeadlineSeconds可选若 RayJob 未能在该秒数内将JobDeploymentStatus转为RunningKubeRay operator 会将其转为Failed原因为PreRunningDeadlineExceeded。默认值 0不强制预运行期限。shutdownAfterJobFinishes可选Ray 作业结束后是否回收 RayCluster默认值为false。ttlSecondsAfterFinished可选仅在shutdownAfterJobFinishes为 true 时生效。Ray 作业结束ttlSecondsAfterFinished秒后operator 删除 RayCluster 与 submitter。默认值 0立即删除。activeDeadlineSeconds可选若 RayJob 未能在该秒数内将JobDeploymentStatus转为Complete或Failedoperator 将其转为Failed原因为DeadlineExceeded。DELETE_RAYJOB_CR_AFTER_JOB_FINISHES可选v1.2.0 新增注意这是设置给 KubeRay operator 的环境变量而非 RayJob 资源字段。若设为 true且同时设置了shutdownAfterJobFinishes: true则 RayJob 自定义资源本身也会被删除KubeRay 会一并删除 RayJob 创建的所有资源包括 Kubernetes Job。其它字段suspend可选若为 trueKubeRay 会同时删除 RayCluster 与 submitter。注意 Kueue 也通过修改该字段实现调度策略如果使用 Kueue 调度 RayJob请避免手动修改此字段。deletionStrategyv1.5.1 为 alphav1.6.0 为 beta配置 RayJob 进入终态后的自动清理需要启用RayJobDeletionPolicy特性门控。支持两种互斥风格规则式Rules-based推荐通过deletionRules定义由特定条件触发的删除动作列表。每条规则包含policy删除动作——DeleteCluster删除整个 RayCluster 及其 Pod、DeleteWorkers只删除 worker Pod、DeleteSelf删除 RayJob 及所有关联资源、DeleteNone不删除condition触发条件——基于jobStatusSUCCEEDED或FAILED与可选的ttlSeconds延迟。这种方式支持灵活的多阶段清理例如「作业成功时立即删除 worker300 秒后再删除整个集群」。规则式与shutdownAfterJobFinishes及全局ttlSecondsAfterFinished不兼容应改用规则内的condition.ttlSeconds。示例见 KubeRay 仓库ray-operator/config/samples/ray-job.deletion-rules.yaml。传统式Legacy已废弃同时定义onSuccess与onFailure策略。该方式将在 v1.6.0 中移除强烈建议迁移到deletionRules。传统式可与shutdownAfterJobFinishes及全局ttlSecondsAfterFinished组合使用。完整的 API 规范请参考 KubeRay CRD API reference。实战10 步在 Kind 上跑通一个 RayJob以下步骤完整复现 RayJob 从创建到清理的全过程。Step 1用 Kind 创建 Kubernetes 集群kind create cluster --imagekindest/node:v1.26.0Step 2安装 KubeRay operator按照 KubeRay Operator Installation 安装最新稳定版 operator。推荐用 Helm 方式v1.7.0helm repo add kuberay https://ray-project.github.io/kuberay-helm/ helm repo update kubectl create namespace ray-system helm install kuberay-operator kuberay/kuberay-operator --version 1.7.0 -n ray-systemKubeRay 也支持 Kustomize 安装kubectl create -k github.com/ray-project/kuberay/ray-operator/config/default?refv1.7.0 -n ray-system。安装后用kubectl get pods -n ray-system确认 operator Pod 处于 Running 状态。Step 3安装 RayJob 示例kubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.sample.yaml该 YAML 位于 KubeRay 仓库ray-operator/config/samples/ray-job.sample.yaml也可先下载到本地再kubectl apply -f。Step 4验证 Kubernetes 集群状态# Step 4.1列出 default 命名空间下所有 RayJob 自定义资源 kubectl get rayjob # [示例输出] # NAME JOB STATUS DEPLOYMENT STATUS RAY CLUSTER NAME START TIME END TIME AGE # rayjob-sample SUCCEEDED Complete rayjob-sample-qnftt 2025-06-25T16:21:21Z 2025-06-25T16:22:35Z 6m53s # Step 4.2列出所有 RayCluster 自定义资源 kubectl get raycluster # [示例输出] # NAME DESIRED WORKERS AVAILABLE WORKERS CPUS MEMORY GPUS STATUS AGE # rayjob-sample-qnftt 1 1 400m 0 0 ready 7m48s # Step 4.3列出 default 命名空间下所有 Pod # 由 Kubernetes Job 创建的 Pod 在 Job 结束后会被终止 kubectl get pods # [示例输出] # kuberay-operator-755f666c4b-wbcm4 1/1 Running 0 8m32s # rayjob-sample-n2vj5 0/1 Completed 0 7m18ss Pod created by a Kubernetes Job # rayjob-sample-qnftt-head 1/1 Running 0 8m14s # rayjob-sample-qnftt-small-group-worker-4f5wz 1/1 Running 0 8m14s # Step 4.4检查 RayJob 状态 # 作业结束后RayJob 的 jobStatus 字段会被更新为 SUCCEEDEDjobDeploymentStatus 应为 Complete kubectl get rayjobs.ray.io rayjob-sample -o jsonpath{.status.jobStatus} # [期望输出]: SUCCEEDED kubectl get rayjobs.ray.io rayjob-sample -o jsonpath{.status.jobDeploymentStatus} # [期望输出]: Complete这里的关键机制是KubeRay operator 依据rayClusterSpec创建 RayCluster 自定义资源同时创建一个 submitter Kubernetes Job 向集群提交 Ray 作业。示例中entrypoint为python /home/ray/samples/sample_code.py该脚本存放在挂载到 head Pod 的 Kubernetes ConfigMap 中。由于shutdownAfterJobFinishes默认值为 false作业结束后 operator不会删除 RayCluster 与 submitter。Step 5查看 Ray 作业输出kubectl logs -ljob-namerayjob-sample # [示例输出] # 2025-06-25 09:22:27,963 INFO worker.py:1654 -- Connecting to existing Ray cluster at address: 10.244.0.6:6379... # 2025-06-25 09:22:27,977 INFO worker.py:1832 -- Connected to Ray cluster. View the dashboard at 10.244.0.6:8265 # test_counter got 1 # test_counter got 2 # test_counter got 3 # test_counter got 4 # test_counter got 5 # 2025-06-25 09:22:31,719 SUCC cli.py:63 -- ----------------------------------- # 2025-06-25 09:22:31,719 SUCC cli.py:64 -- Job rayjob-sample-zdxm6 succeeded # 2025-06-25 09:22:31,719 SUCC cli.py:65 -- -----------------------------------日志显示作业先连接已有 Ray 集群head 地址为10.244.0.6:6379dashboard 为8265随后执行计数器递增函数 5 次最终ray jobCLI 报告作业成功。entrypoint使用的sample_code.py就是一个执行 5 次计数器递增函数的简单 Ray 脚本。Step 6删除 RayJobkubectl delete -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.sample.yamlStep 7创建启用shutdownAfterJobFinishes的 RayJobkubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.shutdown.yamlray-job.shutdown.yaml定义的 RayJob 设置了shutdownAfterJobFinishes: true与ttlSecondsAfterFinished: 10因此 operator 会在作业结束后10 秒删除 RayCluster。注意 submitter Job 不会被删除——它保存着 Ray 作业日志且完成后不占用集群资源RayJob 通过 owner reference 关联 submitter当 RayJob 最终被删除时submitter 会随之清理。Step 8检查 RayJob 状态# 等待 jobStatus 变为 SUCCEEDED、jobDeploymentStatus 变为 Complete kubectl get rayjobs.ray.io rayjob-sample-shutdown -o jsonpath{.status.jobDeploymentStatus} kubectl get rayjobs.ray.io rayjob-sample-shutdown -o jsonpath{.status.jobStatus}Step 9确认 KubeRay operator 已删除 RayCluster# 列出 default 命名空间下的 RayCluster与 RayJob rayjob-sample-shutdown 关联的集群应已被删除 kubectl get rayclusterStep 10清理环境# Step 10.1删除 RayJob kubectl delete -f https://raw.githubusercontent.com/ray-project/kuberay/v1.7.0/ray-operator/config/samples/ray-job.shutdown.yaml # Step 10.2卸载 KubeRay operator helm uninstall kuberay-operator # Step 10.3删除 Kubernetes 集群 kind delete cluster状态机与关键实现逻辑小结从上面的验证命令可以看到RayJob 生命周期由两个状态字段共同刻画jobStatus对应 Ray 作业本身的状态如SUCCEEDED/FAILED/RUNNING由提交结果反馈更新jobDeploymentStatus对应 RayJob 资源的部署状态如Running/Complete/Failed由 operator 依据preRunningDeadlineSeconds、activeDeadlineSeconds、作业终态等条件推进。理解这一点有助于正确组合配置例如「作业成功立即删 worker、延迟删集群」的多阶段清理可以通过deletionRules实现「严格按时回收」则依赖shutdownAfterJobFinishesttlSecondsAfterFinished「杜绝作业跑完集群还挂着」则需要显式把shutdownAfterJobFinishes置为 true因为其默认值为 false。下一步学习路径批处理示例RayJob Batch Inference Example文中引用的 Kuberay 批处理推断示例与 Kueue 配合Priority Scheduling with RayJob and Kueue、Gang Scheduling with RayJob and Kueue集群细节阅读 ray-cluster.complete.yaml 了解rayClusterSpec可用的完整字段进阶提交模式RayJob SidecarSubmitterRestart 指南 与 KubeRay kubectl 插件【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考