Runner 部署指南

📘 概述

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

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

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

⚙️ 环境要求

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

📦 安装步骤

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

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

获取 CSGHub 对应的URL。

hubAPIToken

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

region

这是一个自定义的参数，用来标识集群的区域，例如cn-north。
registry.*
```
helm get notes csghub -n csghub | grep -A 8 'Minio Console'
```
分别获取字段<domain>, username, password。insecure 根据 externalUrl 是否启用 HTTPS加密访问决定。
objectStore
```
helm get notes csghub -n csghub | grep -A 8 'Distribution Registry'
```
上面命令中提供了endpoint, accessKey, secretKey。
- bucket, region,pathStyle是固定值
- secure 根据 externalUrl 是否启用 HTTPS 加密访问决定。

执行部署操作

💡 提示：

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

国内部署添加：

--set global.image.registry="opencsg-registry.cn-beijing.cr.aliyuncs.com"

--set global.imageRegistry="opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq"

注意：建议将自定义配置写入 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 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-string registry.insecure="<if csghub registry secure>" \
  --set objectStore.endpoint="<csghub minio>" \
  --set objectStore.accessKey="<csghub minio username>" \  
  --set objectStore.secretKey="<csghub minio password>" \  
  --set objectStore.bucket="csghub-registry" \  
  --set objectStore.region="cn-north-1" \  
  --set-string objectStore.secure="false" \  
  --set-string objectStore.pathStyle="true"

🧾 配置说明（基于 values.yaml）

全局配置（global）

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

Runner 主配置

参数	默认值	说明
name	runner	用于标识 runner 相关资源的命名（包含对外暴露的域名）
region	region-0	Runner 所属区域标识
interval	60	Runner 与 Server 通信间隔（秒）
namespace	spaces	用户工作负载的默认命名空间
autoConfigure（已弃用）	true	是否自动安装 knative、argo、lws 等依赖组件
kymlMode（已弃用）	create	autoConfigure 更新初始化集群资源的模式（create/update/replace）
mergingNamespace	disable	命名空间合并模式（multi/single/disable）
usePublicDomain	true	是否使用公网域名访问应用（false 会导致多项功能访问受限）

包与镜像管理

参数	默认值	说明
pipIndexUrl	https://pypi.tuna.tsinghua.edu.cn/simple/	自定义 pip 源
extraBuildArgs	[]	Kaniko 额外构建参数
model.registry	opencsg-registry.cn-beijing.cr.aliyuncs.com	模型镜像仓库地址

GPU 配置

参数	默认值	说明
gpuModelLabel.typeLabel	nvidia.com/gpu.product	GPU 型号标签
gpuModelLabel.capacityLabel	nvidia.com/gpu	GPU 容量标签

Knative Serving 配置

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

参数	默认值	说明
knative.serving.domain	example.com	Knative 服务域名后缀
knative.serving.services	[]	兼容旧版本配置（已废弃）
knative.serving.autoscaler.enableScaleToZero	true	启用 KSVC 实例自动关闭
knative.serving.autoscaler.scaleToZeroGracePeriod	60m	KSVC实例关闭的容忍时间

RBAC 配置

参数	默认值	说明
rbac.create	true	是否自动创建 SA、Role、RoleBinding
rbac.serviceAccountName	csghub-runner	SA 名称，【暂时不可修改】

日志与监控

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

loki 服务默认在 CSGHub 侧未向外暴露，需要调整 CSGHub 配置loki.gateway.enabled=true暴露服务后才可使用。
tempo 服务暂时不支持对外暴露，会在后面支持。

外部资源配置

🔹 镜像仓库

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-registry"
  region: "us-east-1"
  secure: true
  pathStyle: true

资源与调度配置

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

🔍 验证部署

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

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

查看 Runner 日志：

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

🔄 升级与卸载

升级 Chart

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

卸载 Chart

helm uninstall runner -n csghub

🧠 常见问题

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

📘 概述​

⚙️ 环境要求​

📦 安装步骤​

1️⃣ 添加 Helm 仓库​

2️⃣ 创建命名空间（可选）​

3️⃣ 部署 Runner​

🧾 配置说明（基于 values.yaml）​

全局配置（global）​

Runner 主配置​

包与镜像管理​

GPU 配置​

Knative Serving 配置​

RBAC 配置​

日志与监控​

外部资源配置​

🔹 镜像仓库​

🔹 对象存储​

资源与调度配置​

🔍 验证部署​

🔄 升级与卸载​

升级 Chart​

卸载 Chart​

🧠 常见问题​