KubeRay 部署与使用指南在 Kubernetes 上跑通你的 Ray 集群【免费下载链接】kuberayA toolkit to run Ray applications on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ku/kuberayKubeRay 是一个 Kubernetes Operator用于自动化地创建、扩缩容和管理 Ray 集群。它适合两类人想在 Kubernetes 上运行训练、批处理和在线推理任务的数据工程师以及希望为团队提供统一 Ray 管理入口的平台工程师。下面按“准备 → 部署 → 验证 → 日常使用”的顺序走一遍 KubeRay 部署的完整流程。KubeRay 适合哪些场景KubeRay 的核心是三个自定义资源按任务性质选一个即可RayCluster直接声明一个 Ray 集群。KubeRay 负责创建 Pod、处理扩缩容和容错。适合长驻的计算集群或开发调试环境。RayJob集群就绪后自动提交一个 Ray 任务任务结束后可自动删除集群。适合离线训练和批处理推理。RayService由 RayCluster 加 Ray Serve 部署图组成支持零停机升级和高可用。适合线上推理服务。如果任务只是单机能跑完的脚本不需要引入 KubeRay它解决的核心问题是“集群生命周期交给 Kubernetes而不是交给运维脚本”。部署前需要准备环境和资源检查集群版本和工具链KubeRay 要求 Kubernetes 集群和 kubectl 版本不低于 1.23。用 Helm 安装时还需要 Helm 3 及以上版本。可以先确认一下当前环境kubectl version --outputjson | head -5 helm version估算 Ray 集群的资源需求Ray Pod 是长驻进程资源需求要提前算好。以 示例目录 中的基础样例为参考head Pod 通常配置 1 CPU / 5Gi 内存worker Pod 每个 1 CPU / 1Gi 起步。样例文件里的注释特别提醒生产环境建议使用整数 CPU并把 requests 和 limits 设成相等单个 Ray Pod 最好能占满它所在的节点。集群里没有足够的可调度资源时Ray Pod 会一直停在 Pending这是部署后最常见的“看似失败”现象。用最小步骤部署 KubeRay operatorKubeRay operator 是常驻组件负责监听 RayCluster / RayJob / RayService 资源并驱动它们达到期望状态。官方提供两种安装方式推荐 Helm。方式一Helm 安装推荐先添加 KubeRay 的 Helm 仓库再安装 operator 和 CRDhelm repo add kuberay https://ray-project.github.io/kuberay-helm/ helm install kuberay-operator kuberay/kuberay-operator这条命令会同时安装 CRDRayCluster、RayJob、RayService 等资源定义和 operator 的 Deployment都落在default命名空间。详细参数见 Helm 安装文档 和 helm-chart/kuberay-operator 下的 values 说明。方式二Kustomize 或本地 chart不想依赖远端仓库时可以克隆仓库后从本地安装git clone https://gitcode.com/GitHub_Trending/ku/kuberay cd kuberay/helm-chart/kuberay-operator helm install kuberay-operator .权限分离CRD 和 operator 分开安装CRD 只能安装到集群级别通常需要管理员权限operator 本身可以由普通开发角色安装。遇到权限受限时可以分两步走# 管理员执行只装 CRD kubectl create -k github.com/ray-project/kuberay/ray-operator/config/crd?refv1.1.0timeout90s # 开发者执行只装 operator helm install kuberay-operator kuberay/kuberay-operator --version 1.1.0 --skip-crds创建第一个 RayCluster 并验证部署提交一个最小 RayCluster 定义新建raycluster-minimal.yaml内容只保留必需字段apiVersion: ray.io/v1 kind: RayCluster metadata: name: raycluster-minimal spec: rayVersion: 2.52.0 headGroupSpec: rayStartParams: {} template: spec: containers: - name: ray-head image: rayproject/ray:2.52.0 resources: limits: cpu: 1 memory: 5Gi requests: cpu: 1 memory: 5Gi workerGroupSpecs: - replicas: 1 groupName: workergroup rayStartParams: {} template: spec: containers: - name: ray-worker image: rayproject/ray:2.52.0 resources: limits: cpu: 1 memory: 1Gi requests: cpu: 1 memory: 1Gi注意rayVersion要与容器镜像内的 Ray 版本一致。然后应用kubectl apply -f raycluster-minimal.yaml确认 operator 和 Ray Pod 都正常分两层检查。先看 operator 自己是否 Runningkubectl get pods | grep kuberay-operator再看 Ray 集群的 Pod 和状态。head 与 worker 都 Ready且 RayCluster 资源进入可用状态说明 KubeRay 部署成功kubectl get pods kubectl get rayclusters✅ 全部就绪后Ray 集群已经在运行了。打开 Ray Dashboard 直观确认head Pod 默认开放 8265 端口的 Dashboard。本地调试时用端口转发即可访问看到节点列表说明集群通信正常kubectl port-forward svc/raycluster-minimal-head-svc 8265:8265首次使用的常用配置选择把默认镜像改成私有镜像示例默认使用rayproject/ray:2.52.0。内网环境没有外网出口时把镜像同步到私有仓库然后替换image字段即可私有仓库需要认证时在 Pod 模板里添加imagePullSecrets。operator 自身的镜像拉取则在 Helm values 的image.repository/imagePullSecrets中配置。开启自动扩缩容在 RayCluster 的 spec 中打开 in-tree 自动扩缩容并给 worker group 设置副本上下限spec: enableInTreeAutoscaling: true workerGroupSpecs: - replicas: 1 minReplicas: 1 maxReplicas: 10KubeRay 会向 head Pod 注入 autoscaler sidecar按负载在上下限之间调整 worker 数量完整字段可参考 ray-cluster.autoscaler.yaml。让 RayJob 在任务结束后自动清理离线任务建议用 RayJob 而不是手动建 RayCluster。两个字段控制清理行为shutdownAfterJobFinishes: true表示任务结束立即删集群ttlSecondsAfterFinished表示延迟若干秒后删除方便排查问题。样例在 ray-job.sample.yaml。常见问题排查与进一步阅读排障思路⚠️ 出问题先看三层operator Pod → Ray Pod → Ray 日志。operator Pod CrashLoopBackOffkubectl logs查看报错常见原因是 RBAC 权限不足或 CRD 未安装。Ray Pod 一直 Pending资源不足。kubectl describe pod看调度失败原因通常是 requests 超过了节点可分配量。worker 起不来确认 head 的 6379GCS端口没有被安全策略拦截。改了镜像不生效KubeRay 1.6.0 起支持upgradeStrategy默认不重建已有 Pod新配置只影响新 Pod。关于rayStartParams的默认值GCS 端口、Dashboard 监听地址、监控端口等见 rayStartParams 说明。接下来该看什么KubeRay 自带控制面指标接入 Prometheus / Grafana 后可以观察 operator 的调谐情况与内存占用config/grafana 目录下有现成的 Dashboard 配置。后续可以按需了解kubectl ray 插件用kubectl ray create cluster等子命令简化日常操作KubeRay APIServer为内部平台提供 HTTP API适合做 Web 管理界面historyserver 文档把历史集群的日志和事件采集到对象存储事后可查。走通“Helm 安装 operator → 提交 RayCluster → Dashboard 验证”这条最短路径后再按业务形态选 RayJob 或 RayService就是完成 KubeRay 部署与上生产的典型路线。【免费下载链接】kuberayA toolkit to run Ray applications on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ku/kuberay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/21 2:15:22 · 阅读 1.2k KubeRay 部署与使用指南：在 Kubernetes 上跑通你的 Ray 集群
KubeRay 部署与使用指南在 Kubernetes 上跑通你的 Ray 集群【免费下载链接】kuberayA toolkit to run Ray applications on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ku/kuberayKubeRay 是一个 Kubernetes Operator用于自动化地创建、扩缩容和管理 Ray 集群。它适合两类人想在 Kubernetes 上运行训练、批处理和在线推理任务的数据工程师以及希望为团队提供统一 Ray 管理入口的平台工程师。下面按“准备 → 部署 → 验证 → 日常使用”的顺序走一遍 KubeRay 部署的完整流程。KubeRay 适合哪些场景KubeRay 的核心是三个自定义资源按任务性质选一个即可RayCluster直接声明一个 Ray 集群。KubeRay 负责创建 Pod、处理扩缩容和容错。适合长驻的计算集群或开发调试环境。RayJob集群就绪后自动提交一个 Ray 任务任务结束后可自动删除集群。适合离线训练和批处理推理。RayService由 RayCluster 加 Ray Serve 部署图组成支持零停机升级和高可用。适合线上推理服务。如果任务只是单机能跑完的脚本不需要引入 KubeRay它解决的核心问题是“集群生命周期交给 Kubernetes而不是交给运维脚本”。部署前需要准备环境和资源检查集群版本和工具链KubeRay 要求 Kubernetes 集群和 kubectl 版本不低于 1.23。用 Helm 安装时还需要 Helm 3 及以上版本。可以先确认一下当前环境kubectl version --outputjson | head -5 helm version估算 Ray 集群的资源需求Ray Pod 是长驻进程资源需求要提前算好。以 示例目录 中的基础样例为参考head Pod 通常配置 1 CPU / 5Gi 内存worker Pod 每个 1 CPU / 1Gi 起步。样例文件里的注释特别提醒生产环境建议使用整数 CPU并把 requests 和 limits 设成相等单个 Ray Pod 最好能占满它所在的节点。集群里没有足够的可调度资源时Ray Pod 会一直停在 Pending这是部署后最常见的“看似失败”现象。用最小步骤部署 KubeRay operatorKubeRay operator 是常驻组件负责监听 RayCluster / RayJob / RayService 资源并驱动它们达到期望状态。官方提供两种安装方式推荐 Helm。方式一Helm 安装推荐先添加 KubeRay 的 Helm 仓库再安装 operator 和 CRDhelm repo add kuberay https://ray-project.github.io/kuberay-helm/ helm install kuberay-operator kuberay/kuberay-operator这条命令会同时安装 CRDRayCluster、RayJob、RayService 等资源定义和 operator 的 Deployment都落在default命名空间。详细参数见 Helm 安装文档 和 helm-chart/kuberay-operator 下的 values 说明。方式二Kustomize 或本地 chart不想依赖远端仓库时可以克隆仓库后从本地安装git clone https://gitcode.com/GitHub_Trending/ku/kuberay cd kuberay/helm-chart/kuberay-operator helm install kuberay-operator .权限分离CRD 和 operator 分开安装CRD 只能安装到集群级别通常需要管理员权限operator 本身可以由普通开发角色安装。遇到权限受限时可以分两步走# 管理员执行只装 CRD kubectl create -k github.com/ray-project/kuberay/ray-operator/config/crd?refv1.1.0timeout90s # 开发者执行只装 operator helm install kuberay-operator kuberay/kuberay-operator --version 1.1.0 --skip-crds创建第一个 RayCluster 并验证部署提交一个最小 RayCluster 定义新建raycluster-minimal.yaml内容只保留必需字段apiVersion: ray.io/v1 kind: RayCluster metadata: name: raycluster-minimal spec: rayVersion: 2.52.0 headGroupSpec: rayStartParams: {} template: spec: containers: - name: ray-head image: rayproject/ray:2.52.0 resources: limits: cpu: 1 memory: 5Gi requests: cpu: 1 memory: 5Gi workerGroupSpecs: - replicas: 1 groupName: workergroup rayStartParams: {} template: spec: containers: - name: ray-worker image: rayproject/ray:2.52.0 resources: limits: cpu: 1 memory: 1Gi requests: cpu: 1 memory: 1Gi注意rayVersion要与容器镜像内的 Ray 版本一致。然后应用kubectl apply -f raycluster-minimal.yaml确认 operator 和 Ray Pod 都正常分两层检查。先看 operator 自己是否 Runningkubectl get pods | grep kuberay-operator再看 Ray 集群的 Pod 和状态。head 与 worker 都 Ready且 RayCluster 资源进入可用状态说明 KubeRay 部署成功kubectl get pods kubectl get rayclusters✅ 全部就绪后Ray 集群已经在运行了。打开 Ray Dashboard 直观确认head Pod 默认开放 8265 端口的 Dashboard。本地调试时用端口转发即可访问看到节点列表说明集群通信正常kubectl port-forward svc/raycluster-minimal-head-svc 8265:8265首次使用的常用配置选择把默认镜像改成私有镜像示例默认使用rayproject/ray:2.52.0。内网环境没有外网出口时把镜像同步到私有仓库然后替换image字段即可私有仓库需要认证时在 Pod 模板里添加imagePullSecrets。operator 自身的镜像拉取则在 Helm values 的image.repository/imagePullSecrets中配置。开启自动扩缩容在 RayCluster 的 spec 中打开 in-tree 自动扩缩容并给 worker group 设置副本上下限spec: enableInTreeAutoscaling: true workerGroupSpecs: - replicas: 1 minReplicas: 1 maxReplicas: 10KubeRay 会向 head Pod 注入 autoscaler sidecar按负载在上下限之间调整 worker 数量完整字段可参考 ray-cluster.autoscaler.yaml。让 RayJob 在任务结束后自动清理离线任务建议用 RayJob 而不是手动建 RayCluster。两个字段控制清理行为shutdownAfterJobFinishes: true表示任务结束立即删集群ttlSecondsAfterFinished表示延迟若干秒后删除方便排查问题。样例在 ray-job.sample.yaml。常见问题排查与进一步阅读排障思路⚠️ 出问题先看三层operator Pod → Ray Pod → Ray 日志。operator Pod CrashLoopBackOffkubectl logs查看报错常见原因是 RBAC 权限不足或 CRD 未安装。Ray Pod 一直 Pending资源不足。kubectl describe pod看调度失败原因通常是 requests 超过了节点可分配量。worker 起不来确认 head 的 6379GCS端口没有被安全策略拦截。改了镜像不生效KubeRay 1.6.0 起支持upgradeStrategy默认不重建已有 Pod新配置只影响新 Pod。关于rayStartParams的默认值GCS 端口、Dashboard 监听地址、监控端口等见 rayStartParams 说明。接下来该看什么KubeRay 自带控制面指标接入 Prometheus / Grafana 后可以观察 operator 的调谐情况与内存占用config/grafana 目录下有现成的 Dashboard 配置。后续可以按需了解kubectl ray 插件用kubectl ray create cluster等子命令简化日常操作KubeRay APIServer为内部平台提供 HTTP API适合做 Web 管理界面historyserver 文档把历史集群的日志和事件采集到对象存储事后可查。走通“Helm 安装 operator → 提交 RayCluster → Dashboard 验证”这条最短路径后再按业务形态选 RayJob 或 RayService就是完成 KubeRay 部署与上生产的典型路线。【免费下载链接】kuberayA toolkit to run Ray applications on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ku/kuberay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考