跳到主要内容

Runner

1. 概述​

Runner 是 CSGHub 平台中负责执行模型训练、推理、任务调度等计算任务的核心组件。

通过 Runner，可以实现与主控制端（CSGHUB Server）的通信，并在 Kubernetes 集群中动态创建与销毁用户工作负载。

本 Chart 通过 Helm 提供标准化部署方式，支持灵活配置、外部依赖集成以及自动化资源管理。

2. 环境要求​

项目说明
Kubernetes 版本v1.33+
Helm 版本v3.12+
网络要求集群节点需能访问 CSGHub Server 与外部镜像仓库（如果内部镜像仓库被禁用）
权限要求具备 cluster-admin 或能创建命名空间与 RBAC 资源的权限（部署过程中会自动创建）

3. 开始部署​

  1. 添加 Helm 仓库

    helm repo add csghub https://charts.opencsg.com/csghub
    helm repo update

  2. 创建命名空间（可选）

    kubectl create namespace csghub

  3. 部署 Runner

    以下信息从 CSGHub 主服务处获取：

    • domain

      这里需要提供一个二级域名用于暴露 runner 服务。

      如果提供的域名是example.com，服务将暴露在runner.example.com下。

    • externalUrl ⚠️ 必填（standalone 模式）

      helm get notes csghub -n csghub | grep -A 6 'Access your CSGHub'

      获取 CSGHub 对应的URL。

    • hubAPIToken ⚠️ 必填（standalone 模式）

      kubectl get cm csghub-core -o yaml -n csghub | grep 'API_TOKEN' | awk '{print $NF}'

    • originClusterID

      runner 集群的唯一标识符，会作为 STARHUB_SERVER_CLUSTER_ID 写入 ConfigMap。

    • region

      这是一个自定义的参数，用来标识集群的区域，例如cn-north。

    • registry

      helm get notes csghub -n csghub | grep -A 8 'Distribution Registry'

      分别获取字段<domain>, username, password。insecure 根据 externalUrl 是否启用 HTTPS加密访问决定。

    • objectStore

      helm get notes csghub -n csghub | grep -A 9 'Minio'

      上面命令中提供了endpoint, accessKey, secretKey。

      • bucket, region,pathStyle是固定值
      • secure 根据 externalUrl 是否启用 HTTPS 加密访问决定。

  4. 执行部署操作

💡 提示：

  • 对象存储和容器镜像仓库可以直接对接外部的其他基础设施。

注意：建议将自定义配置写入 custom-values.yaml，方便后续升级与版本管理。

helm install runner csghub/runner \
  --namespace csghub \
  --create-namespace \
  --set global.gateway.external.domain="example.com" \
  --set externalUrl="<csghub external_url>" \
  --set hubAPIToken="<csghub hub_api_token>" \
  --set runner.region="<region name>" \
  --set registry.registry="<csghub registry>" \
  --set registry.repository="csghub" \
  --set registry.username="<csghub registry username>" \
  --set registry.password="<csghub registry password>" \
  --set registry.insecure=<true|false> \
  --set objectStore.endpoint="<csghub minio>" \
  --set objectStore.accessKey="<csghub minio username>" \
  --set objectStore.secretKey="<csghub minio password>" \
  --set objectStore.bucket="csghub-runner" \
  --set objectStore.region="cn-north-1" \
  --set objectStore.secure=false \
  --set objectStore.pathStyle=true

国内部署（使用国内镜像仓库加速拉取镜像）：

helm install runner csghub/runner \
  --namespace csghub \
  --create-namespace \
  --set global.gateway.external.domain="example.com" \
  --set externalUrl="<csghub external_url>" \
  --set hubAPIToken="<csghub hub_api_token>" \
  --set runner.region="<region name>" \
  --set registry.registry="<csghub registry>" \
  --set registry.repository="csghub" \
  --set registry.username="<csghub registry username>" \
  --set registry.password="<csghub registry password>" \
  --set registry.insecure=<true|false> \
  --set objectStore.endpoint="<csghub minio>" \
  --set objectStore.accessKey="<csghub minio username>" \
  --set objectStore.secretKey="<csghub minio password>" \
  --set objectStore.bucket="csghub-runner" \
  --set objectStore.region="cn-north-1" \
  --set objectStore.secure=false \
  --set objectStore.pathStyle=true \
  --set global.image.registry="registry.opencsg.com" \
  --set global.imageRegistry="registry.opencsg.com/opencsghq"

4. 配置说明​

v2.3.0 字段结构调整： 部分字段路径发生变更，参见下方变更说明。

4.1 全局配置​

参数默认值说明
global.gateway.external.domaincsghub.example.com平台基础访问域名
global.gateway.tls.enabledfalse是否启用 TLS
global.image.tag-镜像版本号

4.2 服务配置​

参数默认值说明
namerunner用于标识 runner 相关资源的命名（包含对外暴露的域名）
runner.regionregion-0Runner 所属区域标识
runner.interval60Runner 与 Server 通信间隔（秒）
runner.namespacespaces用户工作负载的默认命名空间
externalUrl-⚠️ 必填（standalone）。CSGHub 主站访问地址
hubAPIToken-⚠️ 必填（standalone）。CSGHub API 认证 Token
originClusterID""runner 集群唯一标识符，写入 STARHUB_SERVER_CLUSTER_ID（非必填）
runner.mergingNamespacedisable命名空间合并模式（multi/single/disable）
space.usePublicDomaintrue是否使用公网域名访问应用（v2.3.0 起路径由 runner.usePublicDomain 变更为 space.usePublicDomain）
runner.allowCpuOnGpuNodesfalse🆕 v2.3.0 新增。控制纯 CPU 工作负载是否能调度到 GPU 节点

4.3 包与镜像管理​

参数默认值说明
space.pipIndexUrlhttps://pypi.tuna.tsinghua.edu.cn/simple/自定义 pip 源（v2.3.0 起路径从 runner.pipIndexUrl 变更）
model.dockerRegBasenil模型镜像仓库地址（v2.3.0 起字段名从 model.registry 变更）
model.deployTimeoutInMin60推理实例部署超时时间（v2.3.0 起字段名从 model.deployTimeout 变更，单位从秒改为分钟）

4.4 GPU配置​

参数默认值说明
runner.gpuModelLabel.typeLabelnvidia.com/gpu.productGPU 型号标签
runner.gpuModelLabel.capacityLabelnvidia.com/gpuGPU 容量标签
runner.gpuModelLabel.memLabelnvidia.com/gpu.memoryGPU 显存标签
runner.gpuModelLabel.xpuTypeGPUXPU 类型标识

4.5 KnativeServing配置​

💡 提示：自 v1.12.0 开始，以下参数弃用，仅用作向前兼容。

参数默认值说明
knative.serving.domainexample.comKnative 服务域名后缀
knative.serving.services[]兼容旧版本配置（已废弃）
knative.serving.autoscaler.enableScaleToZerotrue启用 KSVC 实例自动关闭
knative.serving.autoscaler.scaleToZeroPodRetentionPeriod60mKSVC实例关闭的容忍时间

4.6 RBAC配置​

参数默认值说明
rbac.createtrue是否自动创建 SA、Role、RoleBinding
rbac.serviceAccountName""自定义 SA 名称；留空时默认派生为 <release>-<name>（例如 helm install runner 时为 runner-runner）

4.7 日志与监控​

参数默认值说明
logging.levelinfo日志等级（info/debug/error）
logcollector.enabledfalse是否启用日志收集器
logcollector.loki.address""Loki 服务地址
tempo.address""Tempo 链路追踪地址

  • loki 服务默认在 CSGHub 侧未向外暴露，需要调整 CSGHub 配置loki.gateway.enabled=true暴露服务后才可使用。

  • tempo 服务暂时不支持对外暴露，会在后面支持。

4.8 持久化存储​

参数默认值说明
runner.storageClassNamenil指定 Kubernetes StorageClass 用于 Space 等申请持久化存储，例如 local-path、nfs-client

4.9 外部资源配置​

  • 镜像仓库
registry:
  registry: "registry.example.com"
  repository: "csghub"
  username: "user"
  password: "pass"
  insecure: false
  • 对象存储
objectStore:
  endpoint: "https://minio.example.com"
  accessKey: "admin"
  secretKey: "password"
  bucket: "csghub-runner"
  region: "us-east-1"
  secure: true
  pathStyle: true

💡 也可以通过 existingSecret 引用已存在的 Secret 来提供外部镜像仓库 / 对象存储的连接信息（无需把账号密码写进 values.yaml）。该 Secret 必须提前在 release 命名空间内创建。

  • 镜像仓库：global.registry.existingSecret（在 global.registry.enabled=false 时生效），或服务级 registry.existingSecret（优先级高于全局）。Secret 键名（需 base64 编码）：REGISTRY_HOST（必填）、REGISTRY_REPOSITORY、REGISTRY_USERNAME、REGISTRY_PASSWORD
  • 对象存储：global.objectStore.existingSecret（在 global.objectStore.enabled=false 时生效），或服务级 objectStore.existingSecret（优先级高于全局）。Secret 键名：OBJECT_STORE_ENDPOINT（必填）、OBJECT_STORE_ACCESS_KEY、OBJECT_STORE_SECRET_KEY、OBJECT_STORE_REGION、OBJECT_STORE_BUCKET

4.10 资源与调度配置​

参数默认值说明
resourcesPod 的 requests/limits 配置
nodeSelector节点选择器
tolerations[]容忍度配置
affinity亲和性配置

5. 验证部署​

部署完成后，可通过以下命令验证运行状态：

kubectl get pods -n csghub
kubectl get svc -n csghub

查看 Runner 日志：

kubectl logs -f deploy/runner-runner -n csghub

6. 升级与卸载​

6.1 升级 Chart​

前置操作​

升级目标版本为 v2.4.2 或更高版本 时，需先更新 agent-sandbox 相关 CRDs。

由于 Helm 升级时不会自动更新依赖组件所需的 CRDs（CustomResourceDefinitions），因此升级前需要先手动更新相关 CRDs。

执行以下脚本：

curl -sSL https://charts.opencsg.com/repository/scripts/crds_install.sh | bash

默认执行该脚本会更新全部组件的 CRDs。如果仅需更新某个组件的 CRDs，可通过 CRD_SERVICES 变量指定，例如：

curl -sSL https://charts.opencsg.com/repository/scripts/crds_install.sh | CRD_SERVICES=agent-sandbox bash

目前 CRD_SERVICES 可选值：agent-sandbox、gateway-helm。

该脚本用于：

  • 更新 agent-sandbox 相关 CRDs
  • 确保升级到 v2.4.2 后相关组件能够正常运行

执行升级​

helm upgrade runner csghub/runner -n csghub -f custom-values.yaml

6.2 卸载 Chart​

helm uninstall runner -n csghub

7. 常见问题​

问题解决方案
Runner 无法连接 Server检查 externalUrl 与 hubAPIToken 是否配置正确
Knative 服务未自动安装确认 autoConfigure: true 且集群具备相应权限
GPU 任务未调度成功检查节点标签与 GPU 驱动是否安装正确
镜像拉取失败确认镜像仓库访问权限与 image.pullSecrets 配置