TensorFusion 文档命令行参考
本页列出 TensorFusion 各个二进制的命令行参数和环境变量：Controller、Hypervisor、Hypervisor TUI，以及注入到 Pod 里的 worker 和客户端部分。定制 Helm chart 或组件的 Pod 模板时用它来查。
所有 Go 二进制的参数用一个或两个短横线都可以（-leader-elect 与 --leader-elect 等价）。布尔参数写成 -flag 或 -flag=false。
Controller
tensor-fusion-operator 镜像里的 /manager。CRD 控制器、Pod mutating webhook、调度器和 HTTP API 都在这一个进程里。
Helm chart 的默认启动命令：
/manager -metrics-bind-address :9000 -leader-elect -enable-auto-scale -enable-alert -enable-auto-expander通过 controller.command 这个 value 修改启动命令。
参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-leader-elect | false | 开启选主，保证只有一个副本在工作。 |
-enable-auto-scale | false | 根据实际用量自动调整 worker 的算力和显存。 |
-enable-alert | false | 评估 dynamicConfig.alertRules 里的告警规则，并把告警发给 Alertmanager。 |
-enable-auto-expander | false | Pod 因 GPU 资源不足而 Pending 时自动添加 GPU 节点。 |
-alert-manager-addr | http://alert-manager.tensor-fusion-sys.svc.cluster.local:9093 | Alertmanager 地址，需要带协议头。 |
-compatible-with-nvidia-container-toolkit | false | 等 NVIDIA Container Toolkit 的 toolkit-ready 校验通过后再开始节点发现。由 chart 的 controller.compatibleWithNvidiaContainerToolkit 设置。 |
-gpu-info-config | /etc/tensor-fusion/gpu-info.yaml | GPU 型号目录文件的路径（各型号的 TFLOPS 和价格）。 |
-dynamic-config | /etc/tensor-fusion/config.yaml | 动态配置文件的路径，由 Helm 的 dynamicConfig 渲染而来。 |
-scheduler-config | /etc/tensor-fusion/scheduler-config.yaml | 调度器配置文件的路径，格式为 KubeSchedulerConfiguration。 |
-metrics-path | /logs/metrics.log | Controller 追加写入指标的文件，Vector 读取这个文件。 |
-host-port-range | 40000-42000 | 给预调度 Pod（如 vGPU worker）分配主机端口的范围。 |
-cluster-host-port-range | 42000-62000 | 给带 tensor-fusion.ai/host-port: auto 注解的 Pod 分配端口的范围。 |
-health-probe-bind-address | :8081 | /healthz 和 /readyz 探针的监听地址。 |
-metrics-bind-address | 0 | controller-runtime 指标端点的监听地址，0 表示关闭。 |
-metrics-secure | false | 指标端点使用 HTTPS。 |
-enable-http2 | false | 指标和 webhook 服务开启 HTTP/2。 |
-v | 0 | 日志详细程度（klog），数字越大日志越多。 |
Controller 用 klog 打日志，其余标准 klog 参数（-logtostderr、-log_file、-vmodule 等）同样可用。早期版本的 -zap-* 参数已经不存在。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
OPERATOR_NAMESPACE | chart 设置为 release 所在命名空间 | Controller 所在的命名空间。 |
TF_ISOLATION_MODE_POLICY | static（chart 设置为 dynamic） | static 或 dynamic。决定一张 GPU 是固定使用一种隔离模式，还是可以切换。Controller 会把同样的值传给 Hypervisor。 |
INITIAL_GPU_NODE_LABEL_SELECTOR | chart 的 initialGpuNodeLabelSelector | 一个 key=value 形式的标签。带这个标签的节点会被登记为 GPU 节点。 |
TSDB_MYSQL_HOST | 127.0.0.1 | GreptimeDB 地址（MySQL 协议），告警和自动伸缩会用到。 |
TSDB_MYSQL_PORT | 4002 | GreptimeDB 的 MySQL 端口。 |
TSDB_MYSQL_USER | root | GreptimeDB 用户名。 |
TSDB_MYSQL_PASSWORD | 空 | GreptimeDB 密码。 |
TSDB_MYSQL_DATABASE | public | GreptimeDB 数据库名。 |
ENABLE_WEBHOOKS | 开启 | 设为 false 时不启动 Pod webhook。 |
ENABLE_SCHEDULER | 开启 | 设为 false 时不启动调度器。 |
ENABLE_CR_CONTROLLER | 开启 | 设为 false 时不启动 CRD 控制器。 |
NVIDIA_OPERATOR_PROGRESSIVE_MIGRATION | 未设置 | 设为 true 时从 NVIDIA Device Plugin 渐进迁移。由 chart 的 controller.nvidiaOperatorProgressiveMigration 设置。 |
ENABLE_POD_RESOURCES_PROXY | 未设置 | 设为 true 时，Hypervisor 会提供一个 kubelet PodResources 代理 socket，让 DCGM exporter 能把 GPU 指标对应到 TensorFusion 的 Pod。 |
KUBECONFIG | 未设置 | kubeconfig 文件路径。只有在集群外运行 Controller 时才需要。 |
Hypervisor
tensor-fusion-hypervisor 镜像里的 hypervisor。Controller 为每个 GPU 节点创建一个 Hypervisor Pod。通过 GPUPool 的 componentConfig.hypervisor.podTemplate 定制它。
参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-vendor | NVIDIA | 加速卡厂商。可被 TF_HARDWARE_VENDOR 覆盖。 |
-accelerator-lib | ./provider/build/libaccelerator_example.so | 厂商 accelerator 库的路径。可被 TF_ACCELERATOR_LIB_PATH 覆盖。 |
-isolation-mode | soft | 节点的默认隔离模式：shared、soft、hard 或 partitioned。可被 TF_ISOLATION_MODE 覆盖。 |
-isolation-policy | static | static 或 dynamic。可被 TF_ISOLATION_MODE_POLICY 覆盖。 |
-backend-type | kubernetes | kubernetes；或 simple，用于没有 Kubernetes 的单机。 |
-discovery-interval | 12h | 重新发现设备的间隔。 |
-metrics-output-path | metrics.log | Hypervisor 追加写入指标的文件。 |
-metrics-interval | 60s | 采集 GPU 和 worker 用量的间隔。 |
-port | 8001 | Hypervisor HTTP API 的端口。可被 HYPERVISOR_PORT 覆盖。 |
-v | 0 | 日志详细程度（klog）。 |
为了兼容 v1 的 Pod 模板，开头的 daemon 参数会被接受并忽略。
子命令 mount-shm
hypervisor mount-shm 挂载一个 tmpfs，用来存放 soft 隔离的共享内存文件。Controller 在每个 Hypervisor Pod 的特权 init 容器 init-shm 里执行它，一般不需要手动调用。
| 参数 | 必填 | 说明 |
|---|---|---|
--mount-point | 是 | tmpfs 的挂载目录。Controller 传入 /run/tensor-fusion/shm。 |
--size | 是 | 大小，单位 MB。Controller 传入 2048。 |
环境变量
标注“自动注入”的变量由 Controller 设置。其余变量按需加到 Hypervisor 的 Pod 模板里。
| 变量 | 来源 | 说明 |
|---|---|---|
GPU_NODE_NAME | 自动注入 | 节点名称，用于上报 GPUNode 和 GPU 资源。 |
TENSOR_FUSION_POOL_NAME | 自动注入 | 节点所属 GPUPool 的名称。 |
HYPERVISOR_PORT | 自动注入 | HTTP API 端口，优先级高于 -port。 |
TF_ISOLATION_MODE_POLICY | 自动注入 | static 或 dynamic，与 Controller 保持一致。 |
TF_HYPERVISOR_METRICS_FORMAT | 自动注入 | 指标行格式，取自 dynamicConfig.metricsFormat。 |
DETECT_IN_USED_GPUS | 自动注入 | 渐进迁移期间为 true，用来识别已被非 TensorFusion Pod 占用的 GPU。 |
TF_HARDWARE_VENDOR | 可选 | 加速卡厂商，例如 NVIDIA、Ascend。 |
TF_ACCELERATOR_LIB_PATH | 可选 | accelerator 库的完整路径。chart 设置为 /run/tensor-fusion/libaccelerator_nvidia.so。 |
TF_ISOLATION_MODE | 可选 | 节点的默认隔离模式。 |
KUBELET_CHECKPOINT_PATH | 可选 | kubelet 设备管理器 checkpoint 文件的路径，不在默认位置时才需要设置。 |
KUBECONFIG | 可选 | kubeconfig 文件路径，在 Pod 外运行时使用。 |
DISABLE_TENSOR_FUSION_TELEMETRY | 可选 | 设为任意值即可关闭匿名使用统计。详见安全白皮书。 |
Hypervisor TUI
hypervisor-tui 是一个终端界面，用来查看单个 Hypervisor 的设备、worker 和实时用量，数据来自 Hypervisor 的 HTTP API。镜像里不带这个工具，需要在 tensor-fusion 仓库里用 make build-hypervisor-tui 构建。
| 参数 | 默认值 | 说明 |
|---|---|---|
-host | localhost | Hypervisor 地址。 |
-port | 8001 | Hypervisor HTTP 端口。 |
make build-hypervisor-tui
./bin/hypervisor-tui -host <node-ip> -port 8001Worker
worker 为远程 vGPU 和 hard 隔离处理 GPU 调用。它的启动命令由 Controller 生成，只有在查看 worker Pod 的 spec 时才会看到。
| 场景 | Controller 设置的命令 |
|---|---|
| 远程 worker，TCP | ./tensor-fusion-worker -p 8000 |
| 同一个 Pod 内的 sidecar worker，共享内存 | ./tensor-fusion-worker -n shmem -m tf_shm -M 2048 |
| 参数 | 说明 |
|---|---|
-p | worker 监听的 TCP 端口。 |
-n | 传输方式，shmem 表示共享内存。 |
-m | 共享内存段的名称。 |
-M | 共享内存段的大小，单位 MB。 |
| 变量 | 说明 |
|---|---|
TF_ENABLE_LOG | 1 表示开启 worker 日志，Controller 默认设置。 |
TF_CUDA_SM_PERCENT_LIMIT | 算力上限（百分比），hard 隔离时设置。工作负载用 TFLOPS 表示上限时，由 Hypervisor 按所分配的 GPU 换算成百分比。 |
TF_GPU_MEMORY_LIMIT | 显存上限，单位 MB，hard 隔离时设置。TF_CUDA_MEMORY_LIMIT 带同样的值，供旧版 worker 读取。 |
客户端与 limiter 注入
Pod webhook 会向申请了 TensorFusion 资源的容器注入 GPU 相关的库。业务容器里不通过 LD_PRELOAD 环境变量预加载；webhook 挂载一个生成好的 /etc/ld.so.preload 文件，容器内的每个进程都会加载对应的库。
| 工作负载 | 注入内容 |
|---|---|
本地 GPU，soft 隔离 | init 容器 init-soft-limiter 把厂商 limiter（NVIDIA 为 libcuda_limiter.so）复制到 /tensor-fusion-limiter，另一个 init 容器把它追加到镜像自带的 /etc/ld.so.preload 里。 |
| 远程 vGPU，或带 worker sidecar 的本地 GPU | init 容器 inject-lib 把客户端库复制到 /tensor-fusion，并生成 /etc/ld.so.preload 和 /etc/ld.so.conf.d/zz_tensor-fusion.conf。 |
shared 和 partitioned 隔离 | 不注入。 |
webhook 给业务容器设置的环境变量：
| 变量 | 值 | 说明 |
|---|---|---|
TF_PREPEND_PATH | /tensor-fusion | 追加到 PATH 最前面的目录。 |
TF_LD_LIBRARY_PATH | /tensor-fusion | 加入库搜索路径的目录。 |
TENSOR_FUSION_OPERATOR_GET_CONNECTION_URL | Controller 的 URL | 客户端向这个地址查询 worker 的地址（远程 vGPU）。 |
TENSOR_FUSION_CONNECTION_NAME、TENSOR_FUSION_CONNECTION_NAMESPACE | 取自 Pod | 把 Pod 和 worker 配对的 TensorFusionConnection（远程 vGPU）。 |
HYPERVISOR_IP、HYPERVISOR_PORT | 节点 IP、8001 | 同节点 Hypervisor 的地址（本地 GPU）。 |
TF_ISOLATION_MODE | soft | 供 soft limiter 读取。 |
TF_SHM_PATH | /run/tensor-fusion/shm/shm | soft limiter 读取限额的共享内存文件。 |
POD_NAME、POD_NAMESPACE、CONTAINER_NAME | 取自 Pod | 向 Hypervisor 标识当前容器。 |
要对单个 Pod 关闭某个内置功能，使用 tensor-fusion.ai/disable-features 注解，值为逗号分隔的列表：
| 值 | 效果 |
|---|---|
gpu-limiter | 不加载 GPU limiter。 |
gpu-opt | 关闭客户端的 CUDA 调用优化。 |
mem-manager | 关闭显存管理器。 |
start-worker | worker 容器以 sleep infinity 启动，不运行 worker 进程，用于调试。 |
已移除的组件
早期版本的文档里有独立的节点发现程序（--hostname、--gpu-info-config、NODE_DISCOVERY_REPORT_GPU_NODE），以及 Hypervisor 的 --sock_path、--gpu_metrics_file、--scheduler 参数。设备发现现在在 Hypervisor 内完成，这些参数已经不存在。