RayCluster 快速入门#

本指南将向您展示如何在 Kubernetes 上管理 Ray 集群并与其进行交互。

准备工作#

如果需要，请安装 kubectl (>= 1.23)、Helm (>= v3.4)、Kind 和 Docker。
请确保您的 Kubernetes 集群至少有 4 个 CPU 和 4 GB RAM。

步骤 1：创建 Kubernetes 集群#

此步骤使用 Kind 创建一个本地 Kubernetes 集群。如果您已有一个 Kubernetes 集群，则可以跳过此步骤。

kind create cluster --image=kindest/node:v1.26.0

步骤 2：部署 KubeRay Operator#

请按照本文档从 Helm 仓库安装最新的稳定版 KubeRay Operator。

步骤 3：部署 RayCluster 自定义资源#

KubeRay Operator 运行后，您就可以部署 RayCluster 了。在 default 命名空间中创建一个 RayCluster 自定义资源 (CR)。

# Deploy a sample RayCluster CR from the KubeRay Helm chart repo:
helm install raycluster kuberay/ray-cluster --version 1.5.1

创建 RayCluster CR 后，您可以通过运行以下命令来查看它：

# Once the RayCluster CR has been created, you can view it by running:
kubectl get rayclusters

NAME                 DESIRED WORKERS   AVAILABLE WORKERS   CPUS   MEMORY   GPUS   STATUS   AGE
raycluster-kuberay   1                 1                   2      3G       0      ready    55s

KubeRay Operator 会检测到 RayCluster 对象，并通过创建 head 和 worker Pod 来启动您的 Ray 集群。要查看 Ray 集群的 Pod，请运行以下命令：

# View the pods in the RayCluster named "raycluster-kuberay"
kubectl get pods --selector=ray.io/cluster=raycluster-kuberay

NAME                                          READY   STATUS    RESTARTS   AGE
raycluster-kuberay-head                       1/1     Running   0          XXs
raycluster-kuberay-worker-workergroup-xvfkr   1/1     Running   0          XXs

等待 Pod 进入 Running 状态。这可能需要几分钟时间，大部分时间都用于下载 Ray 镜像。如果您的 Pod 卡在 Pending 状态，您可以使用 kubectl describe pod raycluster-kuberay-xxxx-xxxxx 来检查错误，并确保您的 Docker 资源限制满足要求。

步骤 4：在 RayCluster 上运行应用程序#

现在，与已部署的 RayCluster 进行交互。

方法 1：在 Head Pod 中执行 Ray 作业#

尝试 RayCluster 的最直接方法是直接进入 head pod 执行命令。首先，识别您的 RayCluster 的 head pod：

export HEAD_POD=$(kubectl get pods --selector=ray.io/node-type=head -o custom-columns=POD:metadata.name --no-headers)
echo $HEAD_POD

raycluster-kuberay-head

# Print the cluster resources.
kubectl exec -it $HEAD_POD -- python -c "import ray; ray.init(); print(ray.cluster_resources())"

2023-04-07 10:57:46,472 INFO worker.py:1243 -- Using address 127.0.0.1:6379 set in the environment variable RAY_ADDRESS
2023-04-07 10:57:46,472 INFO worker.py:1364 -- Connecting to existing Ray cluster at address: 10.244.0.6:6379...
2023-04-07 10:57:46,482 INFO worker.py:1550 -- Connected to Ray cluster. View the dashboard at http://10.244.0.6:8265
{'CPU': 2.0,
 'memory': 3000000000.0,
 'node:10.244.0.6': 1.0,
 'node:10.244.0.7': 1.0,
 'node:__internal_head__': 1.0,
 'object_store_memory': 749467238.0}

方法 2：使用 ray 作业提交 SDK 向 RayCluster 提交 Ray 作业#

与方法 1 不同，此方法不需要您在 Ray head pod 中执行命令。相反，您可以使用 Ray 作业提交 SDK 通过 Ray Dashboard 端口（Ray 监听作业请求的端口）向 RayCluster 提交 Ray 作业。KubeRay Operator 配置了一个 Kubernetes service，指向 Ray head Pod。

kubectl get service raycluster-kuberay-head-svc

NAME                          TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                                         AGE
raycluster-kuberay-head-svc   ClusterIP   None          <none>        10001/TCP,8265/TCP,6379/TCP,8080/TCP,8000/TCP   57s

现在服务名称可用，使用端口转发来访问 Ray Dashboard 端口，默认端口是 8265。

# Execute this in a separate shell.
kubectl port-forward service/raycluster-kuberay-head-svc 8265:8265 > /dev/null &

现在 Dashboard 端口可访问，向 RayCluster 提交作业：

# The following job's logs will show the Ray cluster's total resource capacity, including 2 CPUs.
ray job submit --address https://:8265 -- python -c "import ray; ray.init(); print(ray.cluster_resources())"

Job submission server address: https://:8265

-------------------------------------------------------
Job 'raysubmit_8vJ7dKqYrWKbd17i' submitted successfully
-------------------------------------------------------

Next steps
  Query the logs of the job:
    ray job logs raysubmit_8vJ7dKqYrWKbd17i
  Query the status of the job:
    ray job status raysubmit_8vJ7dKqYrWKbd17i
  Request the job to be stopped:
    ray job stop raysubmit_8vJ7dKqYrWKbd17i

Tailing logs until the job exits (disable with --no-wait):
2025-03-18 01:27:51,014	INFO job_manager.py:530 -- Runtime env is setting up.
2025-03-18 01:27:51,744	INFO worker.py:1514 -- Using address 10.244.0.6:6379 set in the environment variable RAY_ADDRESS
2025-03-18 01:27:51,744	INFO worker.py:1654 -- Connecting to existing Ray cluster at address: 10.244.0.6:6379...
2025-03-18 01:27:51,750	INFO worker.py:1832 -- Connected to Ray cluster. View the dashboard at 10.244.0.6:8265 
{'CPU': 2.0,
 'memory': 3000000000.0,
 'node:10.244.0.6': 1.0,
 'node:10.244.0.7': 1.0,
 'node:__internal_head__': 1.0,
 'object_store_memory': 749467238.0}

------------------------------------------
Job 'raysubmit_8vJ7dKqYrWKbd17i' succeeded
------------------------------------------

步骤 5：访问 Ray Dashboard#

在浏览器中访问 `${YOUR_IP}:8265` 以查看 Dashboard。例如，`127.0.0.1:8265`。在 **Recent jobs** 窗格中可以看到您在步骤 4 中提交的作业，如下图所示。

Ray Dashboard

步骤 6：清理#

# Kill the `kubectl port-forward` background job in the earlier step
killall kubectl
kind delete cluster