📚 课程目录第1章 KubeRay平台工程导论

1. KubeRay平台工程导论

在分布式AI平台工程中，KubeRay 是一个把 Ray 集群“Kubernetes 原生地”管理起来的关键组件。要理解它的价值，先要理解一个现实矛盾：Ray 本身擅长把 Python 任务拆成大量并行任务，并在集群中调度 Actor 与 Task；但 Ray 集群的部署、扩缩容、故障恢复、资源隔离，如果完全靠手工维护节点和进程，很快就会变成运维负担。Kubernetes 擅长声明式编排、容器调度、健康检查与弹性伸缩，却并不理解 Ray 的 Head、Worker、GCS、Raylet 等内部角色。KubeRay 正是这两者之间的“翻译层”和“控制器”。

从定位上看，KubeRay 是 Kubernetes 上的一个 Operator。它通过自定义资源定义（CRD）把 Ray 集群抽象成 Kubernetes 对象，最核心的是 RayCluster、RayJob 和 RayService。用户不再手工登录节点执行 ray start，而是提交一份 YAML，声明“我要一个 1 个 Head、4 个 Worker、每个 Worker 4 CPU 的 Ray 集群”。KubeRay 控制器持续观察这些对象，并调用 Kubernetes API 创建 Pod、Service、ConfigMap 等底层资源，使实际状态逼近期望状态。这就是声明式管理的核心：用户描述目标，控制器负责收敛。

KubeRay 与 Kubernetes、Ray 的关系可以概括为三层：Ray 提供分布式计算运行时与编程模型；Kubernetes 提供容器编排、调度、网络与存储基础设施；KubeRay 位于两者之间，把 Ray 集群的生命周期映射为 Kubernetes 资源生命周期。没有 KubeRay，Ray 仍可运行，但难以获得 Kubernetes 原生的弹性、可观测性和多租户隔离；没有 Kubernetes，KubeRay 也失去其调度与编排底座。因此，KubeRay 不是 Ray 的替代品，也不是 Kubernetes 的插件装饰，而是分布式 AI 平台中“算力抽象层”的控制器。

从核心价值看，KubeRay 主要解决四类问题。第一，集群生命周期自动化：创建、删除、重启、升级 Ray 版本都可以通过修改 CR 完成。第二，弹性与资源管理：Worker Group 可以声明副本数、CPU/内存/GPU 资源，Kubernetes 调度器负责把 Pod 放到合适节点，KubeRay 负责维持副本数量。第三，任务与服务编排：RayJob 支持提交一次性作业并在完成后清理集群；RayService 支持在线推理服务，配合 Ingress 或 Gateway 暴露端点，并在健康检查失败时进行零停机升级。第四，可观测与故障恢复：KubeRay 暴露集群状态、Pod 状态和事件，结合 Kubernetes 的探针与重启策略，可以定位 Head 不可用、Worker 启动失败、GPU 资源不足等常见问题。

下面这张图给出分布式AI平台中 KubeRay 的整体架构视图。它不展开具体 YAML 字段，而是强调控制面、数据面与用户入口之间的层次关系：用户通过 kubectl 或平台 API 提交 RayCluster/RayJob/RayService；KubeRay Operator 监听这些 CR，并创建 Head Pod、Worker Pod 与 Service；Ray 客户端或作业进程通过 Head Service 接入 Ray 集群；底层由 Kubernetes 调度到 CPU/GPU 节点池。

理解这张图后，再来看一个最小可用的 RayCluster 示例。下面的 YAML 声明了一个 Head 节点和两个 Worker 节点，每个 Worker 请求 2 个 CPU、4Gi 内存。注意 rayStartParams 中的 num-cpus 是 Ray 逻辑资源，而 resources.requests 是 Kubernetes 调度资源，两者需要匹配，否则会出现“Pod 已调度但 Ray 认为没有 CPU”的错配。

apiVersion: ray.io/v1
kind: RayCluster
metadata:
  name: demo-raycluster
spec:
  rayVersion: "2.9.0"
  headGroupSpec:
    rayStartParams:
      dashboard-host: "0.0.0.0"
      num-cpus: "0"
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.9.0
          resources:
            requests:
              cpu: "1"
              memory: "2Gi"
            limits:
              cpu: "1"
              memory: "2Gi"
  workerGroupSpecs:
  - groupName: small-wg
    replicas: 2
    minReplicas: 1
    maxReplicas: 4
    rayStartParams:
      num-cpus: "2"
    template:
      spec:
        containers:
        - name: ray-worker
          image: rayproject/ray:2.9.0
          resources:
            requests:
              cpu: "2"
              memory: "4Gi"
            limits:
              cpu: "2"
              memory: "4Gi"

提交后，可以用以下命令观察收敛过程。判断是否成功，关键看三件事：RayCluster 的 state 是否变为 ready；Head Pod 与 Worker Pod 是否全部 Running；Ray Dashboard 或 ray status 是否显示预期数量的 CPU 与节点。如果 Worker 一直 Pending，通常不是 KubeRay 的问题，而是 Kubernetes 调度资源不足或 GPU 节点标签不匹配。

kubectl apply -f demo-raycluster.yaml
kubectl get raycluster demo-raycluster -o wide
kubectl get pods -l ray.io/cluster=demo-raycluster
kubectl exec -it demo-raycluster-head -- ray status

KubeRay 的排障顺序建议从下往上：先看 Pod 是否 Running，再看 Ray 进程是否加入集群，最后看业务代码是否提交成功。不要一上来就改 Ray 代码，多数问题出在资源声明与调度层。

最后需要强调，KubeRay 平台工程不是“装一个 Operator”就结束。它涉及镜像版本管理、Ray 与 Python 依赖一致性、Head 单点风险、Worker Group 弹性策略、GPU 资源切分、日志与指标采集、多租户命名空间隔离等工程问题。本章建立的整体架构视图，是后续所有章节的坐标系：无论讨论 RayJob 提交、RayService 升级、自动扩缩容还是可观测性，都可以回到“用户声明 → KubeRay 调和 → Kubernetes 调度 → Ray 执行”这条主链路上定位问题。