为 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:
    rayStartParams: {}
    # Pod template
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.8.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 注入 head 和 worker Pod 的 Ray 容器中，以存储 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
    rayStartParams:
        ...
    #pod template
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.8.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 是 $(用户指定命令) && $(ray start 命令)。

  • 示例

    # 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