使用 kubectl 插件 (Beta)#

从 KubeRay v1.3.0 开始，您可以使用 kubectl ray 插件来简化在 Kubernetes 上部署 Ray 时的常见工作流程。如果您不熟悉 Kubernetes，此插件可以简化在 Kubernetes 上运行 Ray 的过程。

安装#

请参阅 KubeRay kubectl 插件以安装此插件。

使用以下方法之一安装 KubeRay kubectl 插件

使用 Krew kubectl 插件管理器安装（推荐）
从 GitHub releases 下载

使用 Krew kubectl 插件管理器安装（推荐）#

安装 Krew。
通过运行 kubectl krew update 下载插件列表。
通过运行 kubectl krew install ray 安装插件。

从 GitHub releases 下载#

前往 releases 页面并下载适用于您平台的二进制文件。

例如，要在 Linux amd64 上安装 kubectl 插件版本 1.3.0

curl -LO https://github.com/ray-project/kuberay/releases/download/v1.3.0/kubectl-ray_v1.3.0_linux_amd64.tar.gz
tar -xvf kubectl-ray_v1.3.0_linux_amd64.tar.gz
cp kubectl-ray ~/.local/bin

将 ~/.local/bin 替换为您 PATH 中的目录。

Shell 补全#

遵循安装和启用 kubectl plugin-completion 的说明

用法#

安装插件后，您可以使用 kubectl ray --help 查看可用的命令和选项。

示例#

假设您已经安装了 KubeRay Operator。如果尚未安装，请按照 RayCluster 快速入门，通过 Helm 仓库安装最新的稳定版 KubeRay Operator。

示例 1: RayCluster 管理#

kubectl ray create cluster 命令允许您在没有现有 YAML 文件的情况下创建有效的 RayCluster。默认值如下：

参数	默认值
Ray 版本	2.41.0
Ray 镜像	rayproject/ray:<Ray 版本>
head CPU	2
head 内存	4Gi
worker 副本数	1
worker CPU	2
worker 内存	4Gi
worker GPU	0

$ kubectl ray create cluster raycluster-sample
Created Ray Cluster: raycluster-sample

您可以通过指定标志来覆盖默认值。例如，创建具有 2 个 worker 的 RayCluster：

$ kubectl ray create cluster raycluster-sample-2 --worker-replicas 2
Created Ray Cluster: raycluster-sample-2

默认情况下，它只创建一个 worker group。您可以使用 kubectl ray create workergroup 为现有的 RayCluster 添加额外的 worker group。

$ kubectl ray create workergroup example-group --ray-cluster raycluster-sample --worker-memory 5Gi

您可以使用 kubectl ray get cluster、kubectl ray get workergroup 和 kubectl ray get node 分别获取 RayCluster、worker group 和 Ray node 的状态。

$ kubectl ray get cluster
NAME                  NAMESPACE   DESIRED WORKERS   AVAILABLE WORKERS   CPUS   GPUS   TPUS   MEMORY   AGE
raycluster-sample     default     2                 2                   6      0      0      13Gi     3m56s
raycluster-sample-2   default     2                 2                   6      0      0      12Gi     3m51s

$ kubectl ray get workergroup
NAME            REPLICAS   CPUS   GPUS   TPUS   MEMORY   CLUSTER
default-group   1/1        2      0      0      4Gi      raycluster-sample
example-group   1/1        2      0      0      5Gi      raycluster-sample
default-group   2/2        4      0      0      8Gi      raycluster-sample-2

$ kubectl ray get nodes
NAME                                        CPUS   GPUS   TPUS   MEMORY   CLUSTER               TYPE     WORKER GROUP    AGE
raycluster-sample-default-group-4lb5w       2      0      0      4Gi      raycluster-sample     worker   default-group   3m56s
raycluster-sample-example-group-vnkkc       2      0      0      5Gi      raycluster-sample     worker   example-group   3m56s
raycluster-sample-head-vplcq                2      0      0      4Gi      raycluster-sample     head     headgroup       3m56s
raycluster-sample-2-default-group-74nd4     2      0      0      4Gi      raycluster-sample-2   worker   default-group   3m51s
raycluster-sample-2-default-group-vnkkc     2      0      0      4Gi      raycluster-sample-2   worker   default-group   3m51s
raycluster-sample-2-head-pwsrm              2      0      0      4Gi      raycluster-sample-2   head     headgroup       3m51s

您可以像这样扩缩集群的 worker group。

$ kubectl ray scale cluster raycluster-sample \
  --worker-group default-group \
  --replicas 2
Scaled worker group default-group in Ray cluster raycluster-sample in namespace default from 1 to 2 replicas

# verify the worker group scaled up
$ kubectl ray get workergroup default-group --ray-cluster raycluster-sample
NAME            REPLICAS   CPUS   GPUS   TPUS   MEMORY   CLUSTER
default-group   2/2        4      0      0      8Gi      raycluster-sample

kubectl ray session 命令可以将本地端口转发到 Ray 资源，使用户无需记住 Ray 资源暴露了哪些端口。

$ kubectl ray session raycluster-sample
Forwarding ports to service raycluster-sample-head-svc
Ray Dashboard: http://localhost:8265
Ray Interactive Client: http://localhost:10001

然后您可以在浏览器中打开 http://localhost:8265 访问 dashboard。

kubectl ray log 命令可以将 RayCluster 的日志下载到本地目录。

$ kubectl ray log raycluster-sample
No output directory specified, creating dir under current directory using resource name.
Command set to retrieve both head and worker node logs.
Downloading log for Ray Node raycluster-sample-default-group-worker-b2k7h
Downloading log for Ray Node raycluster-sample-example-group-worker-sfdp7
Downloading log for Ray Node raycluster-sample-head-k5pj8

它在当前目录中创建一个名为 raycluster-sample 的文件夹，其中包含 RayCluster 的日志。

使用 kubectl ray delete 命令清理资源。

$ kubectl ray delete raycluster-sample
$ kubectl ray delete raycluster-sample-2

示例 2: RayJob 提交#

kubectl ray job submit 是 ray job submit 命令的包装器。它可以自动将端口转发到 Ray 集群并提交作业。如果用户未提供 RayJob，此命令还可以临时配置一个集群。

假设在当前目录中，您有一个名为 sample_code.py 的文件。

import ray
ray.init(address="auto")

@ray.remote
def f(x):
    return x * x

futures = [f.remote(i) for i in range(4)]
print(ray.get(futures)) # [0, 1, 4, 9]

在没有 YAML 文件的情况下提交 Ray 作业#

您可以在不指定 YAML 文件的情况下提交 RayJob。此命令会根据以下内容生成一个 RayJob：

参数	默认值
Ray 版本	2.41.0
Ray 镜像	rayproject/ray:<Ray 版本>
head CPU	2
head 内存	4Gi
worker 副本数	1
worker CPU	2
worker 内存	4Gi
worker GPU	0

$ kubectl ray job submit --name rayjob-sample --working-dir . -- python sample_code.py
Submitted RayJob rayjob-sample.
Waiting for RayCluster
...
2025-01-06 11:53:34,806	INFO worker.py:1634 -- Connecting to existing Ray cluster at address: 10.12.0.9:6379...
2025-01-06 11:53:34,814	INFO worker.py:1810 -- Connected to Ray cluster. View the dashboard at 10.12.0.9:8265
[0, 1, 4, 9]
2025-01-06 11:53:38,368	SUCC cli.py:63 -- ------------------------------------------
2025-01-06 11:53:38,368	SUCC cli.py:64 -- Job 'raysubmit_9NfCvwcmcyMNFCvX' succeeded
2025-01-06 11:53:38,368	SUCC cli.py:65 -- ------------------------------------------

您也可以指定一个特定的 RayJob YAML 来提交 Ray 作业。

$ wget https://raw.githubusercontent.com/ray-project/kuberay/refs/heads/master/ray-operator/config/samples/ray-job.interactive-mode.yaml

请注意，在 RayJob spec 中，submissionMode 为 InteractiveMode。

$ kubectl ray job submit -f ray-job.interactive-mode.yaml --working-dir . -- python sample_code.py
Submitted RayJob rayjob-interactive-mode.
Waiting for RayCluster
...
2025-01-06 12:44:43,542	INFO worker.py:1634 -- Connecting to existing Ray cluster at address: 10.12.0.10:6379...
2025-01-06 12:44:43,551	INFO worker.py:1810 -- Connected to Ray cluster. View the dashboard at 10.12.0.10:8265
[0, 1, 4, 9]
2025-01-06 12:44:47,830	SUCC cli.py:63 -- ------------------------------------------
2025-01-06 12:44:47,830	SUCC cli.py:64 -- Job 'raysubmit_fuBdjGnecFggejhR' succeeded
2025-01-06 12:44:47,830	SUCC cli.py:65 -- ------------------------------------------

使用 kubectl ray delete 命令清理资源。

$ kubectl ray delete rayjob/rayjob-sample
$ kubectl ray delete rayjob/rayjob-interactive-mode