为 Ray head/worker Pod 指定容器命令#

KubeRay 为每个 Ray Pod 生成一个 ray start 命令。有时，您可能希望在 ray start 命令之前或之后执行某些命令，或者您可能希望自己定义容器的命令。本文档将向您展示如何做到这一点。

第一部分：指定自定义容器命令，可选地包含生成的 ray start 命令#

从 KubeRay v1.1.0 开始，如果用户向 RayCluster 添加注释 ray.io/overwrite-container-cmd: "true"，KubeRay 将尊重用户提供的容器 command 和 args，而不包含任何生成的命令，包括 ulimit 和 ray start 命令，后者存储在环境变量 KUBERAY_GEN_RAY_START_CMD 中。

apiVersion: ray.io/v1
kind: RayCluster
metadata:
  annotations:
    # If this annotation is set to "true", KubeRay will respect the container `command` and `args`.
    ray.io/overwrite-container-cmd: "true"
  ...
spec:
  headGroupSpec:
    # Pod template
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.46.0
          # Because the annotation "ray.io/overwrite-container-cmd" is set to "true",
          # KubeRay will overwrite the generated container command with `command` and
          # `args` in the following. Hence, you need to specify the `ulimit` command
          # by yourself to avoid Ray scalability issues.
          command: ["/bin/bash", "-lc", "--"]
          # Starting from v1.1.0, KubeRay injects the environment variable `KUBERAY_GEN_RAY_START_CMD`
          # into the Ray container. This variable can be used to retrieve the generated Ray start command.
          # Note that this environment variable does not include the `ulimit` command.
          args: ["ulimit -n 65536; echo head; $KUBERAY_GEN_RAY_START_CMD"]
          ...

前面的示例 YAML 是 ray-cluster.overwrite-command.yaml 的一部分。

  • metadata.annotations.ray.io/overwrite-container-cmd: "true"：此注释告诉 KubeRay 尊重用户提供的容器 command 和 args，而不包含任何生成的命令。如果将注释设置为“false”或根本不设置，请参阅第二部分了解默认行为。

  • ulimit -n 65536：此命令对于避免因文件描述符不足而导致的 Ray 可扩展性问题至关重要。如果您不设置注释，KubeRay 会自动将 ulimit 命令注入容器。

  • $KUBERAY_GEN_RAY_START_CMD：从 KubeRay v1.1.0 开始，KubeRay 将环境变量 KUBERAY_GEN_RAY_START_CMD 注入 Ray 容器（包括 head 和 worker Pod），以存储 KubeRay 生成的 ray start 命令。请注意，此环境变量不包含 ulimit 命令。

    # Example of the environment variable `KUBERAY_GEN_RAY_START_CMD` in the head Pod.
ray start --head  --dashboard-host=0.0.0.0  --num-cpus=1  --block  --metrics-export-port=8080  --memory=2147483648

head Pod 的 command/args 如下所示：

Command:
  /bin/bash
  -lc
  --
Args:
  ulimit -n 65536; echo head; $KUBERAY_GEN_RAY_START_CMD

第二部分：在生成的 ray start 命令之前执行命令#

如果您只想在生成命令之前执行命令，则无需设置注释 ray.io/overwrite-container-cmd: "true"。一些用户使用此方法来设置 ray start 使用的环境变量。

# https://github.com/ray-project/kuberay/ray-operator/config/samples/ray-cluster.head-command.yaml
    #pod template
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.46.0
          resources:
            ...
          ports:
            ...
          # `command` and `args` will become a part of `spec.containers.0.args` in the head Pod.
          command: ["echo 123"]
          args: ["456"]

  • spec.containers.0.command：KubeRay 将 ["/bin/bash", "-lc", "--"] 硬编码为容器的命令。

  • spec.containers.0.args 包含两部分：

    • 用户指定的命令：一个字符串，将 headGroupSpec.template.spec.containers.0.command 和 headGroupSpec.template.spec.containers.0.args 连接在一起。

    • ray start 命令：KubeRay 根据 RayCluster 中指定的 rayStartParams 创建命令。命令格式为 ulimit -n 65536; ray start ...。

    • 总而言之，spec.containers.0.args 是 $(user-specified command) && $(ray start command)。

  • 示例

    # Prerequisite: There is a KubeRay operator in the Kubernetes cluster.

# Create a RayCluster
kubectl apply -f https://raw.githubusercontent.com/ray-project/kuberay/master/ray-operator/config/samples/ray-cluster.head-command.yaml

# Check ${RAYCLUSTER_HEAD_POD}
kubectl get pod -l ray.io/node-type=head

# Check `spec.containers.0.command` and `spec.containers.0.args`.
kubectl describe pod ${RAYCLUSTER_HEAD_POD}

# Command:
#   /bin/bash
#   -lc
#   --
# Args:
#    echo 123  456  && ulimit -n 65536; ray start --head  --dashboard-host=0.0.0.0  --num-cpus=1  --block  --metrics-export-port=8080  --memory=2147483648