TensorFusion 文档组件更新
用 Helm 升级 TensorFusion 控制面，分批滚动更新 hypervisor、worker 和 client，并轮换凭据
升级 TensorFusion 分两部分：helm upgrade 替换控制面；之后 controller 按资源池的滚动更新策略，分批更新池内的组件（hypervisor、worker、client）。本页讲这两部分怎么做、怎么验证和回滚，以及怎么轮换安装时用到的凭据。
从 1.x 升级到 2.x 走的是另一套更严格的流程，请按 v1 到 v2 升级指南操作，不要用本页的步骤。
升级涉及哪些组件
| 组件 | 版本在哪里设置 | 怎么更新 | 对运行中工作负载的影响 |
|---|---|---|---|
| controller（CRD 控制器、Pod webhook、调度器） | Helm value controller.image.tag，默认取 chart 的 appVersion | helm upgrade 更新 Deployment | 无影响。没有可用的 controller 副本期间，带 tensor-fusion.ai/enabled: "true" 标签的 Pod 无法创建和调度 |
| CRD | chart 的 crds/ 目录 | helm upgrade 不会更新，需要手动 apply | 无影响 |
| hypervisor | Helm value cluster.hypervisorImage，对应资源池的 componentConfig.hypervisor.image | controller 按节点分批替换 hypervisor-<node> Pod | 运行中的 Pod 不会重启。新的 hypervisor 就绪之前，该节点不接收新的 GPU 工作负载 |
| worker | providerConfigs.nvidia.images.remoteWorker 和资源池的 componentConfig.worker | controller 分批重建各个 TensorFusionWorkload 的 worker Pod | 连着被重建 worker 的应用会丢失 GPU 会话 |
| client | providerConfigs.nvidia.images.remoteClient 和资源池的 componentConfig.client | controller 分批删除注入内容已过期的应用 Pod，由它们的属主重新创建 | 受影响的应用 Pod 会重启 |
chart 里 hypervisor 镜像由 cluster.hypervisorImage 单独指定，不跟随 controller 版本。每次升级前都要核对这个值，并显式设置。
前置条件
- Helm 3，以及有集群管理员权限的
kubectl。 - 知道安装时用的 release 名称和命名空间。本页两者都用
tensor-fusion-sys，与在 Kubernetes 安装一致。 - 确定目标 chart 版本，并读过对应的发布说明。
- 生产环境建议至少两个 controller 副本（
controller.replicaCount: 2），这样 Deployment 滚动期间 webhook 和调度器不中断。
步骤 1：备份 values 和资源
mkdir -p tf-backup
helm -n tensor-fusion-sys get values tensor-fusion-sys -o yaml > tf-backup/values.yaml
kubectl get tensorfusioncluster,gpupool,gpunode,gpu,workloadprofile,tensorfusionworkload,tensorfusionconnection -A -o yaml \
> tf-backup/tf-state.yamltf-backup/values.yaml 里是安装时设置过的全部 value，步骤 3 要原样传回去。
步骤 2：更新 CRD
chart 的 crds/ 目录只在首次安装时生效，Helm 之后不会再升级它。先拉取目标版本的 chart，把其中的 CRD apply 到集群，再升级 release：
helm pull tensor-fusion --repo https://download.tensor-fusion.ai \
--version <chart-version> --untar --untardir tf-chart
kubectl apply --server-side --force-conflicts -f tf-chart/tensor-fusion/crds/每个 CRD 都应输出 serverside-applied。
步骤 3：升级 Helm release
helm upgrade tensor-fusion-sys tensor-fusion \
--repo https://download.tensor-fusion.ai \
--namespace tensor-fusion-sys \
--version <chart-version> \
-f tf-backup/values.yaml
kubectl -n tensor-fusion-sys rollout status deploy/tensor-fusion-sys-controller --timeout=180s一定要带上 values 文件。不带的话，Helm 会把所有 value 重置为 chart 默认值，控制台 agent 的配置也会丢。
这一步还会更新 chart 管理的 TensorFusionCluster 和 SchedulingConfigTemplate、Alertmanager StatefulSet 和单机版 GreptimeDB。如果 TensorFusionCluster 是你自己创建的（cluster.enabled: false），步骤 4 的修改请直接改它。
步骤 4：滚动更新 hypervisor、worker 和 client
controller 会按资源池为每个组件的配置算一个哈希。哈希变了，并且资源池的 nodeManagerConfig.nodePoolRollingUpdatePolicy 打开了对应的自动更新开关，controller 就开始滚动更新这个组件：
nodeManagerConfig:
nodePoolRollingUpdatePolicy:
autoUpdateHypervisor: true
autoUpdateWorker: false
autoUpdateClient: false
batchPercentage: 20
batchInterval: 1s| 字段 | CRD 默认值 | chart 创建的集群 | 含义 |
|---|---|---|---|
autoUpdateHypervisor | false | true | hypervisor 镜像、Pod 模板或对应厂商的 ProviderConfig 变化时，替换 hypervisor Pod |
autoUpdateWorker | false | 未设置 | worker 模板变化时，重建 worker Pod |
autoUpdateClient | false | 未设置 | client 注入内容变化时，删除应用 Pod |
batchPercentage | 100 | 20 | 每批更新的节点、工作负载或 Pod 占比，向上取整 |
batchInterval | 1s | 1s | 两批之间的间隔 |
这个策略要写在 TensorFusionCluster 的 spec.gpuPools[].specTemplate 下面。controller 会用这份模板覆盖派生出的 GPUPool 的 spec，直接改 GPUPool 的内容会被冲掉。
开关为 false 时，controller 只记录新的哈希，然后等待：组件继续跑旧版本，资源池状态里的 ...ConfigSynced 保持 false。把开关改成 true 后，积压的更新会自动开始。
autoUpdateClient: true 会删除应用 Pod。只有应用能接受重启，并且由 Deployment 等控制器管理、删除后会自动重建时才打开。否则保持关闭，自己安排时间重启应用。
观察更新进度：
kubectl get gpupool -o custom-columns='POOL:.metadata.name,HYPERVISOR:.status.componentStatus.hypervisorUpdateProgress,HV_SYNCED:.status.componentStatus.hypervisorConfigSynced,WORKER:.status.componentStatus.workerUpdateProgress,CLIENT:.status.componentStatus.clientUpdateProgress'
kubectl get pods -n tensor-fusion-sys -l tensor-fusion.ai/component=hypervisor -o wide进度从 0 走到 100。进度为 100 且 ...ConfigSynced: true 表示这个组件已全部更新。没有 GPU 节点的资源池不会执行更新，进度可能一直为空。
验证
kubectl get tensorfusioncluster # PHASE 为 Running
kubectl get gpupool # PHASE 为 Running
kubectl get gpunode # 所有节点为 Running
kubectl -n tensor-fusion-sys get pods -l tensor-fusion.ai/component=hypervisor \
-o custom-columns='POD:.metadata.name,NODE:.spec.nodeName,STATUS:.status.phase,IMAGE:.spec.containers[0].image'每个 GPU 节点上应该有且只有一个 hypervisor Pod，状态为 Running，镜像是新版本。然后按创建 AI 应用建一个测试工作负载，在里面真正调用一次 CUDA。Pod 处于 Running 并不能说明 GPU 链路是通的。
回滚
helm -n tensor-fusion-sys history tensor-fusion-sys
helm -n tensor-fusion-sys rollback tensor-fusion-sys <revision>回滚会恢复之前的 controller 镜像和 TensorFusionCluster，随后 controller 用同样的分批流程把 hypervisor 换回旧版本。CRD 保持新版本不动：Helm 不会降级 CRD，而从 CRD 里删字段可能让已有资源丢数据。
轮换凭据
| 凭据 | 存放位置 | 什么情况下会用到 |
|---|---|---|
| 控制台 agent token | Helm value agent.enrollToken 和 agent.agentId，以环境变量形式传给 controller Pod 里的 cluster-agent 容器 | 集群接入了 TensorFusion 控制台 |
| 云厂商凭据 | Secret tf-cloud-vendor-credentials，键为 ak 和 sk | 资源池通过云厂商 API 创建节点，且该云不支持 IRSA 这类免密钥认证 |
| GreptimeDB Cloud 密码 | Helm value greptime.password，保存在 Secret <release>-greptimedb-secret 和 vector 的 ConfigMap 里 | greptime.isCloud: true |
控制台 agent token。 控制台在集群的接入命令里展示 token，目前没有重新生成的入口。token 泄露时，请联系 TensorFusion 支持团队获取新的 token，然后更新并确认 agent 重新连上：
helm upgrade tensor-fusion-sys tensor-fusion \
--repo https://download.tensor-fusion.ai \
--namespace tensor-fusion-sys \
--version <chart-version> \
-f tf-backup/values.yaml \
--set agent.enrollToken=<new-token>
kubectl -n tensor-fusion-sys logs deploy/tensor-fusion-sys-controller -c cluster-agent --tail=20token 是 Deployment 里的明文环境变量，能读取该命名空间 Deployment 的人都能看到，请收紧这项权限。
云厂商凭据。 chart 只在这个 Secret 不存在时创建它，之后再改 Helm values 不起作用。直接替换 Secret，然后重启 controller：
kubectl create secret generic tf-cloud-vendor-credentials -n tensor-fusion-sys \
--from-literal=ak=<access-key> --from-literal=sk=<secret-key> \
--dry-run=client -o yaml | kubectl apply -f -
kubectl -n tensor-fusion-sys rollout restart deploy/tensor-fusion-sys-controllerGreptimeDB Cloud 密码。 先在 GreptimeDB Cloud 修改密码，再带上新的 greptime.password 执行 helm upgrade，最后重启还持有旧密码的组件：
kubectl -n tensor-fusion-sys rollout restart deploy/tensor-fusion-sys-controller
# 仅在打开了 hypervisor 的 vector sidecar 时需要。Pod 删除后 controller 会重建。
kubectl -n tensor-fusion-sys delete pod -l tensor-fusion.ai/component=hypervisor限制
- 滚动更新策略里有
maxDuration和maintenanceWindow两个字段，但 controller 目前不处理它们：检测到变化就立即开始更新，直到全部完成。 - 不支持按节点灰度或暂停。想放慢更新，调小
batchPercentage、调大batchInterval；想停下来，把对应的autoUpdate*开关改回false。 - 不要在升级时顺手改
componentConfig.hypervisor.portNumber。运行中的 Pod 仍使用创建时的端口，改了之后会连不上 hypervisor。需要改端口时单独操作，并重建该资源池的工作负载。 - 只改了
dynamicConfig或schedulerConfig时，helm upgrade不会重启 controller。执行kubectl -n tensor-fusion-sys rollout restart deploy/tensor-fusion-sys-controller让新配置生效。
下一步
- 配置告警：升级后分配失败时能收到通知。
- 问题处理手册：hypervisor 更新后迟迟不就绪时查看。
- Helm values 参考：chart 的全部配置项。