故障排除指南#

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

内容#

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

Ray 为不同的平台构建不同的镜像。在 Ray 转向构建多架构镜像之前，跟踪此 Github 问题，请在 RayCluster 配置 的 head 和 worker 组规格中使用特定平台的 docker 镜像。

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

链接至问题详情和讨论。

升级 KubeRay#

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

Worker 初始容器#

KubeRay 操作符会将一个默认的 init 容器 注入到每个工作 Pod 中。这个 init 容器负责在连接到头部之前，等待头部 Pod 上的全局控制服务（GCS）准备就绪。init 容器将使用 ray health-check 持续检查 GCS 服务器的状态。

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

1. Init container troubleshooting#

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

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

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

  • CLUSTER_DOMAIN 环境变量未正确设置。更多详情请参见 cluster domain 部分。

  • 工作初始容器与工作Pod模板共享相同的 ImagePullPolicy、SecurityContext、Env、VolumeMounts 和 Resources。共享这些设置可能会导致死锁。更多详情请参见 #1130。

如果初始容器在 Init:0/1 状态下卡住超过2分钟，我们将停止将输出消息重定向到 /dev/null，而是将它们打印到工作 Pod 日志中。要进一步排查问题，您可以使用 kubectl logs 检查日志。

2. Disable the init container injection#

如果你想自定义工作节点初始容器，你可以禁用初始容器注入并添加你自己的。要禁用注入，请在 KubeRay 操作符中将 ENABLE_INIT_CONTAINER_INJECTION 环境变量设置为 false（适用于 KubeRay v0.5.2 及以上版本）。请参考 #1069 和 KubeRay Helm 图表 以获取如何设置环境变量的说明。一旦禁用，你可以将自定义初始容器添加到工作节点 Pod 模板中。

集群域#

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

要设置自定义集群域，请调整 KubeRay 操作器中的 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 任务或角色保持挂起状态#

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

其他问题#

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

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