企业官网建设流程全解析

KubeRay 部署与使用指南：在 Kubernetes 上跑通你的 Ray 集群

【免费下载链接】kuberayA toolkit to run Ray applications on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ku/kuberay

KubeRay 是一个 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 --output=json | 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 operator

KubeRay operator 是常驻组件，负责监听 RayCluster / RayJob / RayService 资源并驱动它们达到期望状态。官方提供两种安装方式，推荐 Helm。

方式一：Helm 安装（推荐）

先添加 KubeRay 的 Helm 仓库，再安装 operator 和 CRD：

helm repo add kuberay https://ray-project.github.io/kuberay-helm/ helm install kuberay-operator kuberay/kuberay-operator

这条命令会同时安装 CRD（RayCluster、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?ref=v1.1.0&timeout=90s" # 开发者执行：只装 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 自己是否 Running：

kubectl 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: 10

KubeRay 会向 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 CrashLoopBackOff：kubectl logs查看报错，常见原因是 RBAC 权限不足或 CRD 未安装。
• Ray Pod 一直 Pending：资源不足。kubectl describe pod看调度失败原因，通常是 requests 超过了节点可分配量。
• worker 起不来：确认 head 的 6379（GCS）端口没有被安全策略拦截。
• 改了镜像不生效：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