TensorFusion API 参考

TensorFusion 有三类编程接口：Kubernetes API（即它的 CRD）、Controller 的 HTTP API、每个节点上 Hypervisor 的 HTTP API。本页说明它们各自的用途，并列出 HTTP 接口。TensorFusion Cloud 控制台目前没有公开的 API，见最后一节。

该用哪个接口

你想做的事	使用	稳定性
创建或修改 GPU 池、工作负载、配额、调度策略	Kubernetes API，组 `tensor-fusion.ai/v1`。见 CRD 参考。	有版本的 API
读取指标和日志	用 SQL 查询 GreptimeDB。见监控指标定义。	表结构有文档
查看调度器状态，或者排查“这个 Pod 为什么调度不上”	Controller HTTP API	内部接口，版本之间可能变化
查看某个节点上的设备和 worker	Hypervisor HTTP API	内部接口，版本之间可能变化

集成请基于 Kubernetes API 来做。两个 HTTP API 是给 TensorFusion 自己的组件和排障用的，不承诺版本兼容。

Controller HTTP API

Controller 监听 8080 端口，通过 TensorFusion 命名空间里的 Controller Service 访问。从本机调用：

kubectl -n tensor-fusion-sys get deploy                     # 找到 <release>-controller 这个 Deployment
kubectl -n tensor-fusion-sys port-forward deploy/<release>-controller 8080:8080
curl -s localhost:8080/api/allocation | jq '.gpuToWorkerMap'

TensorFusion 组件使用的接口

这些接口用 Kubernetes TokenReview 校验调用方的 ServiceAccount token。token 放在 Authorization: Bearer <token> 请求头里。

方法与路径	调用方	行为
`GET /api/connection?name=<name>&namespace=<ns>`	业务 Pod 里的客户端库	以纯文本返回某个 `TensorFusionConnection` 对应的 worker 地址。worker 还没运行时，请求最多等待 5 分钟。token 必须属于拥有该连接的 Pod。
`POST /api/assign-host-port?podName=<name>`	Controller 副本	以纯文本返回 `-cluster-host-port-range` 范围内的一个空闲端口。只有 leader 应答。
`GET /api/assign-index?podName=<name>`	Controller 副本	以纯文本返回分配给该 Pod 的设备序号。只有 leader 应答。

GET /api/connection 的状态码：

状态码	含义
`200`	响应体是连接地址。
`401`	没有 token、token 无效，或 token 对应的 Pod 不是该连接的所有者。
`404`	没有这个 `TensorFusionConnection`。
`503`	Controller 对该连接的监听已中断，请重试。
`504`	worker 在 5 分钟内没有就绪。

诊断接口

方法与路径	返回
`GET /api/allocation`	分配器的内存状态，JSON 格式：`gpuStore`（每张 GPU 的容量和可用量）、`nodeWorkerStore`、`allocation`（每个 Pod 一条，含 requests、limits 和所用 GPU）、`gpuToWorkerMap`（每张 GPU 上的 Pod）。
`POST /api/simulate-schedule`	对一个 Pod 执行调度器的过滤和打分步骤，不预留资源也不绑定。请求体是 Pod 清单（YAML 或 JSON）。响应包含 `scheduleResult`、`filterDetail`（每个过滤阶段排除了哪些 GPU、原因是什么），失败时还有带逐节点诊断信息的 `error`。
`GET /api/node-scaler`	节点扩容器的状态，包括正在创建的节点和预计会有的 GPU。Controller 没有带 `-enable-auto-expander` 启动时返回 `503`。
`GET /api/config`	Controller 当前使用的动态配置。

示例：排查 Pod 为什么一直 Pending。

kubectl get pod <pod-name> -n <namespace> -o yaml > pod.yaml
curl -s -X POST --data-binary @pod.yaml localhost:8080/api/simulate-schedule | jq '.error, .filterDetail'

Pod 的 spec.schedulerName 必须是 Controller 提供的调度器 profile 名称，否则返回 500 和 scheduler framework not found。

诊断接口依靠网络隔离来控制访问，不对每个请求做认证，响应里包含 Pod 名称、标签、注解等集群状态。Controller Service 的类型是 ClusterIP，请保持不变：不要通过 Ingress 或 LoadBalancer 暴露 8080 端口；如果租户可以在集群里运行任意 Pod，再用 NetworkPolicy 限制集群内的访问。

Hypervisor HTTP API

每个 Hypervisor 在所在节点的主机网络上监听 8001 端口。端口通过 GPUPool 的 componentConfig.hypervisor.portNumber 修改。响应是 JSON：成功时为 {"data": ...}，失败时为 {"error": "..."}。

curl -s http://<node-ip>:8001/api/v1/devices | jq '.data[] | {UUID, Model, Healthy}'

健康检查

方法与路径	返回
`GET /healthz`	进程存活时返回 `{"status":"ok"}`。
`GET /readyz`	设备控制器和 worker 控制器初始化完成后返回 `{"status":"ready"}`，否则返回 `503`。

设备

方法与路径	返回
`GET /api/v1/devices`	节点上的所有加速卡：UUID、厂商、型号、序号、NUMA 节点、总显存、最大 TFLOPS、健康状态。
`GET /api/v1/devices/:uuid`	单个设备，不存在时返回 `404`。
`POST /api/v1/devices/discover`	立即触发一次设备发现，不必等 `-discovery-interval`。

Worker

方法与路径	返回
`GET /api/v1/workers`	节点上的所有 worker 及其分配信息：设备、注入的环境变量和挂载。
`GET /api/v1/workers/:id`	按 Pod UID 查询单个 worker，含每个设备、每个进程的用量。Pod 在该节点上没有分配时返回 `404`。
`POST /api/v1/workers/:id/snapshot`	尚未实现，返回 `501`。
`POST /api/v1/workers/:id/resume`	尚未实现，返回 `501`。

Limiter 接口

这组接口沿用了早期 Rust 版 Hypervisor 的请求和响应格式，保证已有的 limiter 和 worker 可以继续工作。

方法与路径	调用方	行为
`GET /api/v1/pod?container_name=<name>`	Pod 内的 limiter 或 worker	返回该 Pod 的 GPU UUID、算力和显存上限、QoS 等级和隔离模式。需要以 Bearer token 形式带上 Pod 的 ServiceAccount token；Hypervisor 用 `TokenReview` 校验，并且只使用校验得到的 Pod UID。
`POST /api/v1/process?container_name=<name>&container_pid=<pid>`	Pod 内的 limiter	登记一个 GPU 进程，把容器内 PID 对应到宿主机 PID。token 校验同上。
`GET /api/v1/pod`（不带 token，也不带 `container_name`）	排障	列出该节点上有 GPU 分配的 Pod。
`GET /api/v1/limiter`	排障	列出每个 worker 的 requests 和 limits。
`POST /api/v1/trap`	Limiter	上报显存压力。响应里给出可以做快照的低 QoS worker 数量。

只有上面两个校验 token 的接口会认证调用方，Hypervisor API 的其余部分依靠网络隔离。它监听在节点网络上，所以请在节点防火墙或安全组里只放行节点自身和 Pod 网段对 8001 端口的访问。

TensorFusion Cloud 控制台

app.tensor-fusion.ai 控制台目前没有公开、有文档的 API：不提供 API key，后端路由与浏览器会话绑定，随时可能变化。控制台展示的数据都是通过 cluster agent 从你的集群里取的，所以你可以直接拿到同样的数据：

控制台功能	如何用程序获取
环境、GPU 池、节点、工作负载	Kubernetes API 的 `tensor-fusion.ai/v1` 资源
指标和用量	监控指标定义里列出的 GreptimeDB 表
计费和配额	`tf_worker_resources` 和 `tf_node_metrics` 的 `raw_cost` 字段；`GPUResourceQuota` 资源

下一步

CRD 参考
安全白皮书：这些接口背后的认证设计

该用哪个接口

你想做的事	使用	稳定性
创建或修改 GPU 池、工作负载、配额、调度策略	Kubernetes API，组 `tensor-fusion.ai/v1`。见 CRD 参考。	有版本的 API
读取指标和日志	用 SQL 查询 GreptimeDB。见监控指标定义。	表结构有文档
查看调度器状态，或者排查“这个 Pod 为什么调度不上”	Controller HTTP API	内部接口，版本之间可能变化
查看某个节点上的设备和 worker	Hypervisor HTTP API	内部接口，版本之间可能变化

集成请基于 Kubernetes API 来做。两个 HTTP API 是给 TensorFusion 自己的组件和排障用的，不承诺版本兼容。

Controller HTTP API

Controller 监听 8080 端口，通过 TensorFusion 命名空间里的 Controller Service 访问。从本机调用：

kubectl -n tensor-fusion-sys get deploy                     # 找到 <release>-controller 这个 Deployment
kubectl -n tensor-fusion-sys port-forward deploy/<release>-controller 8080:8080
curl -s localhost:8080/api/allocation | jq '.gpuToWorkerMap'

TensorFusion 组件使用的接口

这些接口用 Kubernetes TokenReview 校验调用方的 ServiceAccount token。token 放在 Authorization: Bearer <token> 请求头里。

方法与路径	调用方	行为
`GET /api/connection?name=<name>&namespace=<ns>`	业务 Pod 里的客户端库	以纯文本返回某个 `TensorFusionConnection` 对应的 worker 地址。worker 还没运行时，请求最多等待 5 分钟。token 必须属于拥有该连接的 Pod。
`POST /api/assign-host-port?podName=<name>`	Controller 副本	以纯文本返回 `-cluster-host-port-range` 范围内的一个空闲端口。只有 leader 应答。
`GET /api/assign-index?podName=<name>`	Controller 副本	以纯文本返回分配给该 Pod 的设备序号。只有 leader 应答。

GET /api/connection 的状态码：

状态码	含义
`200`	响应体是连接地址。
`401`	没有 token、token 无效，或 token 对应的 Pod 不是该连接的所有者。
`404`	没有这个 `TensorFusionConnection`。
`503`	Controller 对该连接的监听已中断，请重试。
`504`	worker 在 5 分钟内没有就绪。

诊断接口

方法与路径	返回
`GET /api/allocation`	分配器的内存状态，JSON 格式：`gpuStore`（每张 GPU 的容量和可用量）、`nodeWorkerStore`、`allocation`（每个 Pod 一条，含 requests、limits 和所用 GPU）、`gpuToWorkerMap`（每张 GPU 上的 Pod）。
`POST /api/simulate-schedule`	对一个 Pod 执行调度器的过滤和打分步骤，不预留资源也不绑定。请求体是 Pod 清单（YAML 或 JSON）。响应包含 `scheduleResult`、`filterDetail`（每个过滤阶段排除了哪些 GPU、原因是什么），失败时还有带逐节点诊断信息的 `error`。
`GET /api/node-scaler`	节点扩容器的状态，包括正在创建的节点和预计会有的 GPU。Controller 没有带 `-enable-auto-expander` 启动时返回 `503`。
`GET /api/config`	Controller 当前使用的动态配置。

示例：排查 Pod 为什么一直 Pending。

kubectl get pod <pod-name> -n <namespace> -o yaml > pod.yaml
curl -s -X POST --data-binary @pod.yaml localhost:8080/api/simulate-schedule | jq '.error, .filterDetail'

Pod 的 spec.schedulerName 必须是 Controller 提供的调度器 profile 名称，否则返回 500 和 scheduler framework not found。

Hypervisor HTTP API

curl -s http://<node-ip>:8001/api/v1/devices | jq '.data[] | {UUID, Model, Healthy}'

健康检查

方法与路径	返回
`GET /healthz`	进程存活时返回 `{"status":"ok"}`。
`GET /readyz`	设备控制器和 worker 控制器初始化完成后返回 `{"status":"ready"}`，否则返回 `503`。

设备

方法与路径	返回
`GET /api/v1/devices`	节点上的所有加速卡：UUID、厂商、型号、序号、NUMA 节点、总显存、最大 TFLOPS、健康状态。
`GET /api/v1/devices/:uuid`	单个设备，不存在时返回 `404`。
`POST /api/v1/devices/discover`	立即触发一次设备发现，不必等 `-discovery-interval`。

Worker

方法与路径	返回
`GET /api/v1/workers`	节点上的所有 worker 及其分配信息：设备、注入的环境变量和挂载。
`GET /api/v1/workers/:id`	按 Pod UID 查询单个 worker，含每个设备、每个进程的用量。Pod 在该节点上没有分配时返回 `404`。
`POST /api/v1/workers/:id/snapshot`	尚未实现，返回 `501`。
`POST /api/v1/workers/:id/resume`	尚未实现，返回 `501`。

Limiter 接口

这组接口沿用了早期 Rust 版 Hypervisor 的请求和响应格式，保证已有的 limiter 和 worker 可以继续工作。

方法与路径	调用方	行为
`GET /api/v1/pod?container_name=<name>`	Pod 内的 limiter 或 worker	返回该 Pod 的 GPU UUID、算力和显存上限、QoS 等级和隔离模式。需要以 Bearer token 形式带上 Pod 的 ServiceAccount token；Hypervisor 用 `TokenReview` 校验，并且只使用校验得到的 Pod UID。
`POST /api/v1/process?container_name=<name>&container_pid=<pid>`	Pod 内的 limiter	登记一个 GPU 进程，把容器内 PID 对应到宿主机 PID。token 校验同上。
`GET /api/v1/pod`（不带 token，也不带 `container_name`）	排障	列出该节点上有 GPU 分配的 Pod。
`GET /api/v1/limiter`	排障	列出每个 worker 的 requests 和 limits。
`POST /api/v1/trap`	Limiter	上报显存压力。响应里给出可以做快照的低 QoS worker 数量。

TensorFusion Cloud 控制台

控制台功能	如何用程序获取
环境、GPU 池、节点、工作负载	Kubernetes API 的 `tensor-fusion.ai/v1` 资源
指标和用量	监控指标定义里列出的 GreptimeDB 表
计费和配额	`tf_worker_resources` 和 `tf_node_metrics` 的 `raw_cost` 字段；`GPUResourceQuota` 资源

下一步

CRD 参考
安全白皮书：这些接口背后的认证设计

该用哪个接口

Controller HTTP API

TensorFusion 组件使用的接口

诊断接口

Hypervisor HTTP API

健康检查

设备

Worker

Limiter 接口

TensorFusion Cloud 控制台

下一步

目录

TensorFusion API 参考

该用哪个接口

Controller HTTP API

TensorFusion 组件使用的接口

诊断接口

Hypervisor HTTP API

健康检查

设备

Worker

Limiter 接口

TensorFusion Cloud 控制台

下一步

目录