故障排除指南#

本文档解答了常见问题。如果您在此处找不到问题的答案，请随时通过我们的社区渠道与我们联系。

目录#

使用正确版本的 Ray#

请参阅升级指南，了解 KubeRay 版本与 Ray 版本之间的兼容性矩阵。

请勿使用 Ray 版本 2.11.0 到 2.37.0。

此提交在 Ray 2.11.0 中引入了一个 bug。创建 Ray 作业时，头节点上的 Ray Dashboard Agent 进程会卡住，导致 readiness 和 liveness 探测（向 Dashboard Agent 发送 Raylet 健康检查请求）失败。

为 Apple M1 或 M2 MacBook 使用基于 ARM 的 Docker 镜像#

Ray 为不同平台构建不同的镜像。在 Ray 开始构建多架构镜像之前（此 Github issue 跟踪了该进展），请在 RayCluster config 的 head 和 worker 组规范中使用特定于平台的 Docker 镜像。

如果您在 MacBook M1 或 M2 上运行 KubeRay，请使用带有 aarch64 标签的镜像，例如 image: rayproject/ray:2.41.0-aarch64)。

链接到问题详情和讨论.

升级 KubeRay#

如果您在升级 KubeRay 时遇到问题，请参阅升级指南。大多数问题与 CRD 版本有关。

Worker Init 容器#

KubeRay Operator 会为每个 Worker Pod 注入一个默认的 init 容器。该 init 容器负责等待头 Pod 上的全局控制服务 (GCS) 准备就绪，然后再建立与头的连接。init 容器将使用 ray health-check 持续检查 GCS 服务器状态。

默认的 Worker Init 容器可能不适用于所有用例，或者用户可能希望自定义 init 容器。

1. Init 容器故障排除#

Worker Init 容器卡在 Init:0/1 状态的一些常见原因包括：

  • 头 Pod 中的 GCS 服务器进程失败。请检查头 Pod 中的日志目录 /tmp/ray/session_latest/logs/，查找与 GCS 服务器相关的错误。

  • 镜像的 $PATH 中不包含 ray 可执行文件，导致 init 容器无法运行 ray health-check。

  • 环境变量 CLUSTER_DOMAIN 设置不正确。有关详细信息，请参阅集群域部分。

  • Worker init 容器与 worker Pod 模板共享相同的 ImagePullPolicy、SecurityContext、Env、VolumeMounts 和 Resources。共享这些设置可能会导致死锁。有关详细信息，请参阅 #1130。

如果 init 容器卡在 Init:0/1 状态超过 2 分钟，Ray 将停止将输出消息重定向到 /dev/null，而是将它们打印到 worker Pod 日志中。要进一步排除故障，您可以使用 kubectl logs 检查日志。

2. 禁用 init 容器注入#

如果您想自定义 Worker Init 容器，可以禁用 init 容器注入并添加您自己的容器。要禁用注入，请将 KubeRay Operator 中的环境变量 ENABLE_INIT_CONTAINER_INJECTION 设置为 false（适用于 KubeRay v0.5.2 及更高版本）。请参阅 #1069 和 KubeRay Helm chart，了解如何设置此环境变量。禁用后，您可以将自定义 init 容器添加到 worker Pod 模板中。

集群域#

在 KubeRay 中，我们使用完全限定域名 (FQDN) 在 Worker 和 Head 之间建立连接。Head 服务的 FQDN 是 ${HEAD_SVC}.${NAMESPACE}.svc.${CLUSTER_DOMAIN}。默认的集群域是 cluster.local，适用于大多数 Kubernetes 集群。但是，需要注意的是，某些集群可能有不同的集群域。您可以通过检查 Pod 中的 /etc/resolv.conf 来查看 Kubernetes 集群的集群域。

要设置自定义集群域，请调整 KubeRay Operator 中的 CLUSTER_DOMAIN 环境变量。Helm Chart 用户可以在此处进行修改。有关更多信息，请参阅 #951 和 #938。

RayService#

RayService 是专为 Ray Serve 设计的自定义资源定义 (CRD)。在 KubeRay 中，创建 RayService 将首先创建一个 RayCluster，然后在 RayCluster 准备就绪后创建 Ray Serve 应用。如果问题与数据平面有关，特别是您的 Ray Serve 脚本或 Ray Serve 配置 (serveConfigV2)，故障排除可能会比较困难。有关详细信息，请参阅RayService 故障排除。

Ray 自动伸缩器#

Ray 自动伸缩器未扩容，导致新的 Ray 任务或 Actor 一直挂起#

一个常见原因是 Ray 任务或 Actor 需要的资源量超出了任何单个 Ray 节点所能提供的。请注意，Ray 任务和 Actor 是 Ray 中最小的调度单元，并且一个任务或 Actor 应该位于单个 Ray 节点上。以 kuberay#846 为例。用户尝试调度一个需要 2 个 CPU 的 Ray 任务，但可用于这些任务的 Ray Pod 每个只有 1 个 CPU。因此，Ray 自动伸缩器决定不扩容 RayCluster。

其他问题#

为什么对 RayCluster 或 RayJob CR 的更改不生效？#

目前，仅支持修改 RayCluster/RayJob CR 中的 replicas 字段。对其他字段的更改可能不生效或导致意外结果。