使用 kubectl 插件 (Beta)#

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

安装#

请参阅 KubeRay kubectl 插件来安装该插件。

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

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

1.4.0 及之后的插件版本可能与 1.4.0 之前的 KubeRay 不兼容

1.4.0 及之后的插件版本可能与 1.4.0 之前的 KubeRay 版本不兼容。请尝试使用相同的插件和 KubeRay 版本。

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

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

从 GitHub releases 下载#

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

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

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

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

Shell 自动补全#

请按照 kubectl 插件自动补全的说明进行安装和启用。

用法#

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

示例#

假设您已安装 KubeRay operator。如果尚未安装，请按照 KubeRay Operator 安装说明，使用 Helm 仓库安装最新稳定的 KubeRay operator。

示例 1：RayCluster 管理#

kubectl ray create cluster 命令允许您在没有现有 YAML 文件的情况下创建有效的 RayCluster。默认值为（空值表示未设置）：

参数	默认
K8s 标签
K8s 注解
Ray 版本	2.46.0
Ray 镜像	rayproject/ray:<Ray 版本>
Head CPU	2
Head 内存	4Gi
Head GPU	0
Head 临时存储
Head `ray start` 参数
Head 节点选择器
Worker 副本数	1
Worker CPU	2
Worker 内存	4Gi
Worker GPU	0
Worker TPU	0
Worker 临时存储
Worker `ray start` 参数
Worker 节点选择器
每个副本的默认 Worker 组中的主机数量	1
自动扩缩器版本 (v1 或 v2)

$ 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 CPU 设置为 3。

$ curl -LO https://raw.githubusercontent.com/ray-project/kuberay/refs/tags/v1.5.1/kubectl-plugin/config/samples/create-cluster.sample.yaml
$ kubectl ray create cluster raycluster-sample-3 --file create-cluster.sample.yaml
Created Ray Cluster: raycluster-sample-3

请参阅 https://github.com/ray-project/kuberay/blob/v1.5.1/kubectl-plugin/config/samples/create-cluster.complete.yaml 获取您可以在配置文件中设置的参数的完整列表。

默认情况下，它只创建一个 Worker 组。您可以使用 kubectl ray create workergroup 命令向现有的 RayCluster 添加额外的 Worker 组。

$ 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 组和 Ray 节点的状。

$ 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 组。

$ 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: https://:8265
Ray Interactive Client: https://:10001

然后，您可以在浏览器中打开 https://:8265 来访问仪表板。

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 作业#

您可以提交一个 RayJob 而无需指定 YAML 文件。该命令根据以下内容生成 RayJob

参数	默认
Ray 版本	2.46.0
Ray 镜像	rayproject/ray:<Ray 版本>
Head CPU	2
Head 内存	4Gi
Head GPU	0
Worker 副本数	1
Worker CPU	2
Worker 内存	4Gi
Worker GPU	0
作业完成后清理 RayCluster 的 TTL	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 规范中，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