3. GPU驱动与固件升级介绍

3.1. 内核驱动灰度发布方案

3.1.1. 简介

在GPU集群中，为了实现高效的GPU资源管理，确保系统稳定性与性能优化，我们使用 GPU Operator 管理和协调GPU资源。 由于生产环境中GPU集群规模常达数千甚至上万节点，人工升级KMD（内核态驱动）不仅耗时费力，还可能因操作失误或驱动兼容性问题导致业务中断、集群故障。 因此，在 GPU Operator 中采用 灰度发布方案 控制内核驱动升级过程，通过分批次、可暂停、可回滚的自动化机制，降低升级风险，减少业务影响范围，同时简化运维流程。

备注

重要提示：执行灰度升级时，集群必须处于离线状态（无运行中的GPU任务），避免驱动升级对在途任务造成不可逆影响。

3.1.2. 术语描述

表 3.1 核心术语说明表

术语

介绍

KMD

Kernel Mode Driver（内核态驱动），运行于操作系统内核空间的GPU驱动核心组件，直接与硬件交互，是GPU正常工作的基础。

payload

带有KMD资源的镜像，包含驱动安装包、依赖库等关键文件，是驱动升级的“物料载体”。

灰度发布

基于 GPU-Operator 实现的 KMD 驱动升级机制，适用于大规模 GPU 集群（数千甚至上万节点），支持在离线环境下自动化分批次升级，可通过配置控制升级节奏（如每批次节点数、最大并行升级数），具备暂停、回滚能力，能降低升级失败风险、减少业务中断时间。

CR

Custom Resource（自定义资源），用户通过编辑CR的 driver.upgradePolicy 字段定义灰度升级策略，是与灰度发布功能交互的核心入口。

GPU-Operator

管理GPU资源的Kubernetes操作器，负责协调集群中GPU相关组件（如驱动、容器运行时）的生命周期。

Daemonset RollingUpdate.OnDelete

强制依赖的Daemonset升级策略，仅当用户或组件手动删除旧Pod时，才创建新Pod（新驱动版本），确保升级节奏可控。

maxParallel

最大并行升级数量（支持数值或百分比），控制每批次同时升级的节点数，避免并发过高导致集群不稳定。

fallback

升级失败后的降级策略，可选 rollback （自动回滚到旧版本）或 pause （暂停升级，等待人工介入）。

3.1.3. 操作步骤

备注

关于 GPU Operator 所依赖的前置资源，参见《曦云系列通用GPU云原生参考手册》中“安装与维护”章节。

假定用户有10个工作节点，且使用 GPU Operator 安装内核驱动镜像版本为2.32.0.6，期望升级内核驱动镜像版本为2.33.0.9。

  1. 获取安装包

    以 0.13.0 版本为例，从 沐曦软件中心 下载离线安装包 metax-gpu-k8s-package.0.13.0.tar.gz，解压后获取以下文件：

    • metax-k8s-images.0.13.0.run：镜像资源包

    • metax-operator-0.13.0.tgz：Operator Helm Chart

    • metax-gpu-extensions-0.13.0.tgz：Extensions Helm Chart

  2. 准备内核驱动和 MXMACA® SDK 镜像

    GPU Operator 会自动管理节点上的内核驱动及 MXMACA® SDK 的部署与更新，需确保所有工作节点均可正常拉取相关镜像资源。

    内核驱动与 MXMACA® SDK 可从 沐曦软件中心 下载。

    结合本次升级需求，需额外下载 2.33.0.9 版本的内核驱动资源。

    资源包格式：

    • 内核驱动镜像包

      metax-k8s-driver-image.<VERSION>-<ARCH>.run：包含内核态驱动和配套 mx-smi 工具的资源包

    • MXMACA® SDK 镜像包

      随 MXMACA® 的发布包发布，例如 maca-native:<VERSION>-<DISTRO>-<ARCH>.container.xz 或者 maca-c500-container-*.xz

  3. 推送镜像

    # 假设容器仓库服务器域名为 DOMAIN ，用于存放沐曦Kubernetes组件镜像的项目名为 PROJECT。
# 默认使用docker进行镜像推送
metax-k8s-images.0.13.0.run push DOMAIN/PROJECT
# 使用nerdctl进行镜像推送
metax-k8s-images.0.13.0.run nerdctl push DOMAIN/PROJECT

    备注

    • 自 0.13.0 起，该工具支持多种运行时：docker、nerdctl、ctr。

    • 若未显式指定，默认使用docker。若主机未安装docker，系统将自动检测可用运行时并执行镜像推送。

    • 若远程registry为http协议registry，push方式参见《曦云系列通用GPU云原生参考手册》“支持”章节。

  4. 推送 Helm Charts

    helm push ./k8s/metax-operator-0.13.0.tgz oci://DOMAIN/PROJECT

  5. 安装 GPU Operator

    # 离线安装（基于本地Helm Charts）
helm install ./k8s/metax-operator-0.13.0.tgz \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=DOMAIN/PROJECT \
--set driver.payload.version=2.32.0.6

  6. 验证安装状态

    在 Kubernetes 管理节点执行以下命令检查 Pod 是否处于 Running 状态。

    kubectl get pod -n metax-operator
NAME                                           READY   STATUS      RESTARTS   AGE
metax-container-runtime-4lsd7                  1/1     Running     0          31s
metax-gpu-device-7774b                         1/1     Running     0          31s
metax-gpu-label-l5tkf                          1/1     Running     0          31s
metax-operator-1755847288-77bfc94568-7wqlh     1/1     Running     0          31s
...

  7. 配置灰度发布策略

    以下提供两类场景的推荐YAML配置，用户可根据集群规模调整参数。

    • 场景1：10节点

      普通灰度升级（分4批次，含人工确认环节）

      # 编辑CR命令：kubectl edit clusteroperators.gpu.metax-tech.com cluster-operator
driver:
  upgradePolicy:
    enableRollout: true  # 开启灰度发布
    upgradeSteps:
      # 第1批次：升级2个节点，需人工触发下一批
      - replicas: 2
        pauseDuration: {}
      # 第2批次：升级至5个节点（新增3个），10秒后自动进入下一批
      - replicas: 5
        pauseDuration: 10000
      # 第3批次：升级至8个节点（新增3个），10秒后自动进入下一批
      - replicas: 8
        pauseDuration: 10000
      # 第4批次：升级所有节点（100%），完成后10秒后自动进入下一批
      - replicas: 100%
        pauseDuration: 10000
    pause: false  # 初始状态：不暂停
    maxParallel: 100%  # 最大并行升级数=当前批次replicas的100%（向上取整，且至少1个）
    maxUnavailable: 0  # 升级中不可用节点数=0，确保集群可用性
    maxFailureThreshold: 3  # 每批次最大失败次数，超过则触发fallback
    fallback: pause  # 失败后暂停升级，等待人工排查

    • 场景2：100节点

      适用于大规模集群，需在关键批次（首/尾批次）人工确认升级效果，避免风险扩散。

      # 编辑CR命令：kubectl edit clusteroperators.gpu.metax-tech.com cluster-operator
driver:
  upgradePolicy:
    enableRollout: true  # 开启灰度发布
    upgradeSteps:
      # 第1批次：升级5%(5)个节点，完成后暂停（需人工触发下一批）
      - replicas: 5%
        pauseDuration: {}  # 空配置=人工确认
      # 第2批次：升级至30个节点（新增25个），完成后自动等待5分钟
      - replicas: 30
        pauseDuration: 300000
      # 第3批次：升级至60个节点（新增30个），完成后自动等待5分钟
      - replicas: 60
        pauseDuration: 300000
      # 第4批次：升级所有节点（100%），完成后暂停（需人工确认升级结束）
      - replicas: 100%
        pauseDuration: {}
    pause: false  # 初始状态：不暂停
    maxParallel: 50%  # 最大并行升级数=当前批次replicas的50%（向上取整，且至少1个）
    maxUnavailable: 10%  # 升级中不可用节点数=总升级节点数的10%，确保集群可用性
    maxFailureThreshold: 5  # 每批次最大失败次数，超过则触发fallback
    fallback: pause  # 失败后暂停升级，等待人工排查

  8. 开启灰度发布升级

    修改内核驱动的版本号，当 enableRollout 开启时，系统会自动进入灰度发布。

    kubectl patch ClusterOperator/cluster-operator --type json --patch='[{"op":"replace","path":"/spec/driver/payload/version","value": "2.33.0.9-amd64"}]'

  9. 动态调整策略

    仅支持修改“灰度发布策略开关”和“暂停状态”：

    # 强制回滚
kubectl patch clusteroperators.gpu.metax-tech.com clusteroperator type=json -p '[{"op": "replace","path":"/driver/upgradePolicy/enableRollout","value": "false"}]'
# 暂停升级
kubectl patch clusteroperators.gpu.metax-tech.com clusteroperator type=json -p '[{"op": "replace", "path": "/driver/upgradePolicy/pause","value": "false"}]'
# 恢复升级
kubectl patch clusteroperators.gpu.metax-tech.com clusteroperator type=json -p '[{"op": "replace","path": "/driver/upgradePolicy/pause","value": "true"}]'

  10. 查看升级状态 字段详情参见《曦云系列通用GPU云原生参考手册》中“表 Driver Upgrade Status”。 以下是常见字段说明：

    • status.upgradeStatus.upgrading: 标识KMD灰度升级是否运行，为 true 表示灰度发布进行中

    • status.upgradeStatus.phase: 灰度发布升级阶段，可选 Idling， Progressing， Terminating， Disabled， Disabling

    • status.currentStepIndex: 当前批次升级索引，表明当前为第几次升级

    • status.currentUpgradeReplicas: 当前批次升级副本数量

    • status.currentUpgradeReadyReplicas: 当前批次升级成功的副本数量

    • status.currentFailureRetry: 当前批次升级失败次数

    • status.currentStepState: 当前批次状态，可选 StepUpgradeInit， StepUpgrade， StepPaused， StepReady， Completed

    kubectl get clusteroperators.gpu.metax-tech.com cluster-operator -o jsonpath={.status.upgradeStatus}

    status:
   upgradeStatus:
      lastAppliedSpec:
      lastCoDriverSpec:
      upgrading:
      condition:
      - type:
        status:
        lastTransitionTime:
        reason:
        message:
      phase:
      message:
      status:
         lastPodSpecRevision:
         upgradingPodSpecRevision:
         currentStepIndex:
         currentUpgradeReplicas:
         currentUpgradeReadyReplicas:
         currentFailureRetry:
         currentStepState:
         totalUpgradeReplicas:
         totalUpgradeReadyReplicas:
         lastUpdateTime:
         message:
         recheckTime:

3.1.4. 问题排查

灰度升级过程中，可通过“查看状态→分析日志→定位问题”三步排查，常见问题及解决方法如下：

  1. 查看升级状态

    通过以下命令获取实时升级状态，字段详情参见《曦云系列通用GPU云原生参考手册》中“表 Driver Upgrade Status”。

    # 查看完整升级状态（JSON格式）
kubectl get clusteroperators.gpu.metax-tech.com cluster-operator -o jsonpath={.status.upgradeStatus} | jq

  2. 常见问题及排查步骤

    • 问题1：提交CR后，升级无响应（ status.upgradeStatus.upgrading 始终为 false ）

      可能原因：

      参数校验失败（ validating-admission-webhook 拦截）；

      排查步骤：

      查看Operator-controller关于webhook的日志：

      kubectl logs -n metax-operator <metax-operator-pod-name> # 查看启动日志

    • 问题2：某批次升级失败（ currentFailureRetry 达到 maxFailureThreshold ）

      可能原因：

      • 驱动镜像拉取失败（仓库权限、镜像不存在）；

      • 驱动与节点内核不兼容（启动新Pod后 CrashLoopBackOff）；

      • 节点资源不足（如内存、磁盘空间不够）。

      排查步骤：

      1. 查看失败节点的Pod日志：

        # 查看Pod状态
kubectl describe pod -n metax-operator <failed-pod-name> # 查看启动日志
# 查看Pod日志，定位具体错误
kubectl logs -n metax-operator <failed-pod-name> # 查看启动日志

      2. 若日志提示“image pull backoff”：检查镜像地址是否正确。

      3. 处理后恢复升级：

        # 若fallback为pause，恢复升级（需先修复失败节点）
kubectl patch clusteroperators.gpu.metax-tech.com cluster-operator --type=json -p '[{"op": "replace", "path": "/driver/upgradePolicy/pause", "value": "false"}]'

3.2. 固件升级

3.2.1. 适用场景

在安装 GPU Operator 后，需要升级GPU卡上固件的场景。

3.2.2. 使用限制

  • 目前固件升级功能不支持升级绑定了 vfio-pci 驱动的GPU卡。

  • 固件升级功能只支持在物理机环境上运行，且只支持PF的固件升级。

  • 使用固件升级功能要求当前服务器上所有GPU设备的VBIOS版本不跨1.12.0.0版本，即都小于1.12.0.0版本或者都大于等于1.12.0.0版本。建议当前所有GPU设备版本不小于1.12.0.0版本。

  • 不支持在固件升级过程中修改固件升级参数。

  • 目前固件升级不支持多机互联场景。

  • 目前不支持从非虚拟化版本固件升级到虚拟化版本固件，原因是虚拟化版本固件对服务器有较高要求，需要用户手动确认当前服务器型号能否支持虚拟化固件。

3.2.3. 升级固件

以下步骤适用于将GPU的固件升级为 payload 镜像中的固件版本。

备注

升级前需确保当前集群没有业务运行。

  1. 隔离所有GPU节点

    通过以下命令隔离集群中所有的GPU节点。

    kubectl get nodes -l metax-tech.com/gpu.installed=true -o name | xargs -I {} kubectl cordon {}

  2. 启用固件升级策略

    可以先通过 mx-smi 工具确认当前的GPU卡上的固件是否为虚拟化版本，如下显示 SRIOV 为 Support 表示为虚拟化版本固件，否则为非虚拟化版本固件。

    $ mx-smi --show-vbios
mx-smi  version: 2.2.8

=================== MetaX System Management Interface Log ===================
Timestamp                                         : Wed Aug 20 17:39:23 2025

Attached GPUs                                     : 6
GPU#0  MXC500  0000:36:00.0
   Vbios info
      SRIOV                                     : Support

    如果是非虚拟化固件，通过设置 cluster-operator 中的 spec.driver.fwUpgradePolicy 为 PreferCloud 来启用固件升级功能。

    kubectl patch ClusterOperator/cluster-operator --type json --patch='[{"op": "replace", "path": "/spec/driver/fwUpgradePolicy", "value": "PreferCloud"}]'

    如果是虚拟化固件，需要额外设置 cluster-operator 中的 spec.driver.fwEnableVirt 为 true 。

    kubectl patch ClusterOperator/cluster-operator --type json --patch='[{"op": "replace", "path": "/spec/driver/fwUpgradePolicy", "value": "PreferCloud"}, {"op": "replace", "path": "/spec/driver/fwEnableVirt", "value": true}]'

  3. 等待固件升级生效

    配置生效后，driver-manager 组件会自动执行固件升级，此时需要等待固件升级完成后节点上报了 NodeNeedReboot 事件，然后再通过重启服务器使固件生效。

    $ kubectl get event
   LAST SEEN   TYPE    reason          OBJECT              message
   9s          Normal  NodeNeedReboot  node/sample-node1   firmware upgrade done, need reboot machine to take effect

  4. 检查固件版本

    服务器重启后，可以在节点上通过 mx-smi 工具查看固件的版本是否升级成功。

  5. 关闭固件升级策略

    确认集群内所有节点固件升级都成功后，通过设置 cluster-operator 中的 spec.driver.fwUpgradePolicy 为 Never 来关闭固件升级功能。

    kubectl patch ClusterOperator/cluster-operator --type json --patch='[{"op": "replace", "path": "/spec/driver/fwUpgradePolicy", "value": "Never"}]'

  6. 解除所有GPU节点隔离

    通过以下命令解除集群中所有的GPU节点的隔离后，可以正常下发业务。

    kubectl get nodes -l metax-tech.com/gpu.installed=true -o name | xargs -I {} kubectl uncordon {}