企业官网建设流程全解析

在 Kubernetes 上使用 kubectl ray 插件：KubeRay 集群管理与 RayJob 提交实战

【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray

导读

kubectl ray是 KubeRay 从 v1.3.0 起提供的 kubectl 插件（目前处于 beta 阶段），它把"部署 Ray 到 Kubernetes"这一高频操作封装成kubectl ray create/get/scale/session/log/delete等一系列直觉化命令，让你无需手写 YAML 即可创建 RayCluster、查询集群状态、转发 Dashboard 端口、下载节点日志，并一键提交 RayJob。本文以仓库中的 kubectl-plugin 指南 为骨架，结合 KubeRay Operator 安装 与 RayJob 快速入门 文档，完整还原插件的安装、默认参数表与全部示例命令，读完即可在真实集群上落地这套工作流。

前置条件：先安装 KubeRay Operator

插件的create cluster、job submit等命令最终都会生成 KubeRay 的 Custom Resource（RayCluster、RayJob）并交给 KubeRay Operator 调谐，因此使用插件前必须保证 Operator 已在集群中运行。参照 KubeRay Operator Installation 的完整步骤：

# Step 1：创建一个本地 Kubernetes 集群（已有集群可跳过） kind create cluster --image=kindest/node:v1.26.0 # Step 2：通过 Helm 安装 KubeRay operator（推荐，安装到独立命名空间 ray-system） helm repo add kuberay https://ray-project.github.io/kuberay-helm/ helm repo update kubectl create namespace ray-system helm install kuberay-operator kuberay/kuberay-operator --version 1.7.0 -n ray-system # Step 3：验证 Operator 运行状态 kubectl get pods -n ray-system # NAME READY STATUS RESTARTS AGE # kuberay-operator-6bc45dd644-gwtqv 1/1 Running 0 24s

除了 Helm，也可以使用 Kustomize 直接kubectl create -k "github.com/ray-project/kuberay/ray-operator/config/default?ref=v1.7.0" -n ray-system安装（详见该文档）。

安装 kubectl ray 插件（beta）

插件本体位于 KubeRay 仓库的kubectl-plugin子目录，支持两种安装方式，官方推荐使用 Krew 插件管理器。

方法一：通过 Krew 安装（推荐）

1. 先安装 Krew（kubectl 插件管理器）；
2. 下载插件列表：kubectl krew update；
3. 安装 ray 插件：kubectl krew install ray。

方法二：从 GitHub releases 下载二进制

前往 KubeRay 的 releases 页面，下载对应平台（linux/darwin/windows、amd64/arm64）的kubectl-ray_<version>_<os>_<arch>.tar.gz压缩包并解压到 PATH 目录。以 Linux amd64 上安装 v1.7.0 为例：

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

将~/.local/bin替换为你自己的 PATH 目录即可。安装完成后建议同时配置 kubectl 插件的 Shell Completion（bash/zsh/fish），按第三方kubectl plugin-completion项目的 TL;DR 说明启用即可，可在输入子命令时获得补全提示。

版本兼容性警告（重要）

插件版本自1.4.0 起可能与 1.4.0 之前的 KubeRay 不兼容（插件生成的 CR 字段依赖较新的 CRD 定义）。因此请尽量让插件版本与 KubeRay Operator 版本保持一致，例如本文示例均以 KubeRay v1.7.0 为准。

快速上手：查看命令总览

安装完成后，直接运行kubectl ray --help即可查看所有可用命令与参数。整体命令设计围绕两类工作流展开：

• RayCluster 管理：create cluster、create workergroup、get cluster/workergroup/node、scale cluster、session、log、delete；
• RayJob 提交：job submit（自动端口转发 + 提交作业，可临时拉起集群）。

示例一：RayCluster 管理

1. 不写 YAML 直接创建 RayCluster

kubectl ray create cluster <name>不需要任何现有 YAML 文件，即可生成一个合法的 RayCluster。命令内置的默认值如下（空值表示不设置）：

最简创建命令：

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

通过命令行 flag 覆盖默认值。例如创建带 2 个 worker 的集群：

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

通过配置文件覆盖默认值。插件支持--file传入一个 YAML 配置文件（如create-cluster.sample.yaml，可在 KubeRay 仓库kubectl-plugin/config/samples/目录找到示例），配置文件里的字段会覆盖对应默认值。例如下面的配置把 worker CPU 设为 3：

$ curl -LO https://raw.githubusercontent.com/ray-project/kuberay/refs/tags/v1.7.0/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

配置文件中可设置的全部参数清单，可参考 KubeRay 仓库kubectl-plugin/config/samples/create-cluster.complete.yaml（该文件展示了 label/annotation、镜像、head/worker 资源、ray start参数、节点选择器、TPU、autoscaler 版本等完整字段）。

2. 为已有集群追加 worker group

默认情况下create cluster只创建一个 worker group。若需为已存在的 RayCluster追加额外的 worker group，使用create workergroup：

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

3. 查看集群 / worker group / 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

可以看到get cluster汇总了每个集群的期望/可用 worker 数与 CPU/GPU/TPU/内存总量，get nodes则按 Pod 粒度列出 head 与 worker 节点及其所属的 worker group，TYPE列区分head与worker。get workergroup同样支持按名称与--ray-cluster过滤，例如kubectl ray get workergroup default-group --ray-cluster raycluster-sample。

4. 扩缩容 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 # 验证扩容结果 $ 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

从输出可以看到 REPLICAS 列变为2/2，即期望副本数与可用副本数均为 2。扩容是声明式的，底层对应修改 RayCluster CR 中该 worker group 的replicas字段，由 KubeRay Operator 负责拉起新 Pod（若配置了 Autoscaler v2，也可交给自动扩缩容接管）。

5. 用 session 一键端口转发，免记端口

kubectl ray session <cluster>会把本地端口转发到 Ray 集群的 Service，避免手动记忆 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即可访问 Ray Dashboard，10001端口则用于 Ray Interactive Client（如ray.init("ray://localhost:10001")）。它底层等价于对 head Service 执行kubectl port-forward，但省去了手工拼 Service 名与端口映射的步骤——KubeRay Operator 默认会为 RayCluster 创建指向 head Pod 的-head-svcService（包含 10001/8265/6379/8080/8000 等端口，参见 RayCluster Quickstart）。

6. 用 log 命令批量下载集群日志

$ 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 所有 Ray 节点（head + 所有 worker）的日志，非常适合排查任务失败或节点异常时离线分析。

7. 清理集群

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

delete会删除对应的 RayCluster CR，KubeRay Operator 随之回收其下的 head/worker Pod 及相关资源。

示例二：RayJob 提交

kubectl ray job submit本质上是ray job submit命令的封装：它会自动完成到 Ray 集群的端口转发、然后提交作业并流式输出日志；如果用户没有提供 RayJob 资源，它还可以临时创建一个一次性（ephemeral）RayCluster来承载作业。

假设当前目录下有一个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]

场景 A：不带 YAML，让插件生成 RayJob

不指定 YAML 时，插件会基于以下默认值生成一个 RayJob：

提交命令（--之后是作业入口命令）：

$ 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 CR → 等待 RayCluster 就绪 → 自动转发端口并执行ray job submit→ 流式回传作业日志直到成功/失败。

场景 B：指定 RayJob YAML 提交

也可以先准备一个 RayJob YAML 再提交。KubeRay 仓库的ray-operator/config/samples/ray-job.interactive-mode.yaml就是官方示例。注意该 RayJob 的submissionMode必须是InteractiveMode（见 RayJob Quickstart 中的说明：InteractiveMode 下 KubeRay Operator 等待用户向集群提交作业，KubeRay kubectl 插件正依赖此模式）：

$ wget https://raw.githubusercontent.com/ray-project/kuberay/refs/heads/master/ray-operator/config/samples/ray-job.interactive-mode.yaml $ 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 -- ------------------------------------------

清理 RayJob 资源（按资源类型加前缀）：

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

理解背后的 RayJob 机制

要真正用好kubectl ray job submit，建议理解 KubeRay 的 RayJob 设计（详见 RayJob Quickstart）：

• RayJob同时管理两部分：rayClusterSpec定义的RayCluster（head Pod + 多个 worker Pod），以及负责执行ray job submit的submitter；
• submissionMode有K8sJobMode（Operator 创建 submitter Kubernetes Job）、HTTPMode（Operator 直接向集群发请求建作业）、InteractiveMode（Operator 等用户提交，kubectl 插件依赖它）与SidecarMode四种取值；
• 资源清理由shutdownAfterJobFinishes、ttlSecondsAfterFinished、preRunningDeadlineSeconds、activeDeadlineSeconds等字段控制——这正好对应插件在无 YAML 模式下生成的 "TTL to clean up RayCluster after job finished" 与 "Deadline before RayJob reaches Running" 两个默认参数（默认均为 0，即不设限）。

小结：推荐的日常操作组合

结合 KubeRay Operator Installation、RayCluster Quickstart 与本文插件用法，一套无需手写 YAML 的完整工作流如下：

1. 安装 KubeRay Operator（Helm，版本与插件保持一致）；
2. kubectl ray create cluster my-cluster拉起集群，必要时用--file指定资源规格；
3. kubectl ray session my-cluster打开 Dashboard（8265）与 Interactive Client（10001）；
4. kubectl ray job submit --working-dir . -- python app.py提交作业（可无 YAML 或指定 InteractiveMode 的 RayJob YAML）；
5. 需要时kubectl ray scale cluster my-cluster --worker-group default-group --replicas N扩容、kubectl ray log my-cluster拉取日志；
6. 用kubectl ray delete清理集群与 RayJob。

插件仍处于 beta 阶段，遇到与 KubeRay 版本相关的行为差异时，优先检查插件与 Operator 的版本是否一致；更细粒度的集群配置（如 autoscaler v2、TPU、节点亲和、自定义ray start参数）均可通过 配置文件 或 KubeRay CRD 的完整 API 字段覆盖实现。

【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray