故障排除指南#

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

目录#

使用正确版本的 Ray#

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

请勿使用 2.11.0 和 2.37.0 之间的 Ray 版本。

该提交在 Ray 2.11.0 中引入了一个 bug。当创建 Ray 作业时，head 节点上的 Ray dashboard agent 进程会卡住，导致用于向 dashboard agent 发送 health check 请求的 Raylet 的就绪性和存活探针失败。

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

Ray 为不同的平台构建不同的镜像。在 Ray 迁移到构建多架构镜像（在此 GitHub issue 中跟踪）之前，请在RayCluster 配置的 head 和 worker 组规范中使用特定于平台的 Docker 镜像。

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

链接到 issue 详情和讨论.

升级 KubeRay#

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

Worker 初始化容器#

KubeRay operator 会将一个默认的初始化容器注入到每个 worker Pod 中。此初始化容器负责在与 head 建立连接之前等待 head Pod 上的全局控制服务 (GCS) 就绪。初始化容器将使用 ray health-check 来持续检查 GCS 服务器状态。

默认的 worker 初始化容器可能不适用于所有用例，或者用户可能希望自定义初始化容器。

1. 初始化容器故障排除#

worker 初始化容器卡在 Init:0/1 状态的一些常见原因是

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

  • ray 可执行文件未包含在镜像的 $PATH 中，因此初始化容器将无法运行 ray health-check。

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

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

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

2. 禁用初始化容器注入#

如果您想自定义 worker 初始化容器，可以禁用初始化容器注入并添加自己的。要禁用注入，请将 KubeRay operator 中的 ENABLE_INIT_CONTAINER_INJECTION 环境变量设置为 false（适用于 KubeRay v0.5.2）。有关如何设置环境变量的说明，请参考#1069和KubeRay Helm chart。禁用后，您可以将自定义初始化容器添加到 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-troubleshooting。

Ray 自动扩展程序#

Ray 自动扩展程序未扩展，导致新的 Ray 任务或 actor 处于待处理状态#

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

多节点 GPU 部署#

有关多节点 GPU 服务问题的全面故障排除，请参阅KubeRay 上多节点 GPU 服务的故障排除。

其他问题#

为什么对 RayCluster 或 RayJob CR 的更改不起作用？#

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

当 CRs 数量很多时，如何配置协调并发？#

在此示例kuberay#3909中，用户在处理 RayCluster CRs 时遇到了高延迟，并发现 ReconcileConcurrency 值设置为 1。

KubeRay operator 支持配置 ReconcileConcurrency 设置，该设置控制处理 Ray 自定义资源 (CRs) 的并发工作线程的数量。

要配置 ReconcileConcurrency 数量，您可以编辑部署的容器参数

kubectl edit deployment kuberay-operator

在容器参数中指定 ReconcileConcurrency 数量

spec:
  containers:
  - args:
    - --reconcile-concurrency
    - "10"

对于 kuberay 版本 >= 1.5.1，您也可以使用以下命令

helm install kuberay-operator kuberay/kuberay-operator --version 1.5.1 --set reconcileConcurrency=10