3. GPU Operator

重要

在Kubernetes集群上配置 GPU Operator 前，应确认环境满足如下条件：

Kubernetes版本及CRI支持范围：

Kubernetes

CRI

Version

= 1.23

docker

≥ 18.09.3

containerd

≥ 1.5.0

≥ 1.24

containerd

≥ 1.5.0
管理节点以及工作节点应允许创建特权容器 [1] 。
Host应使用如下操作系统或其衍生版本，并选择有MetaX内核驱动支持的内核版本：

Host OS

Ubuntu

18.04 / 20.04 / 22.04

CentOS

8.x / 9.x

OpenEuler

20.03 / 22.03
无需且不推荐在工作节点预安装 MXMACA^® 内核态驱动，若已安装也无需卸载。

3.1. 关于 GPU Operator

GPU Operator 是更加云原生化的方案，除了具备 GPU Extensions 方案的全部功能之外，针对于 MXMACA^® 软件栈在Kubernetes集群上的部署及应用，进行了多处优化：

用户容器镜像优化

在使用 GPU Extensions 方案时，用户的应用容器镜像需要基于 MXMACA^® 基础镜像构建。而使用 GPU Operator 方案后，用户可选择制作不包含 MXMACA^® SDK的应用容器镜像。如此，可带来两项好处：
- 镜像尺寸减小
- MXMACA^® 版本升级时无需重新构建应用镜像
MXMACA^® 由 GPU Operator 统一管理并部署在每个工作节点上，用户的作业运行时将使用节点上已部署的 MXMACA^® SDK。此过程在操作层面对用户透明，尽管用户能够感知到容器在运行时自动安装了 MXMACA^® SDK这一变化，但无需为此做任何额外操作。
驱动自动部署

使用 GPU Extensions 方案时，系统管理员需预先在每个工作节点上安装内核态驱动（包含虚拟化驱动的配置及安装）。

GPU Operator 方案提供了自动部署驱动及配置GPU虚拟化规格的能力。管理员可配置 driver.deployPolicy 选取不同部署策略或关闭内核态驱动的自动部署功能。

GPU Operator 提供名为 driver-config 的 ConfigMap，管理员可通过此文件指定工作节点的GPU虚拟化规格（vfnum），配置文件的更新将在几分钟内在相关节点上生效。
虚拟机方案支持

为满足Kubernetes集群中引入的KubeVirt虚拟化能力，GPU Operator 方案提供了绑定KubeVirt所依赖的底层驱动vfio-pci的能力。用户可在不停机状态下通过配置文件选择要绑定到vfio-pci的GPU设备，从而允许虚拟机直接访问物理GPU设备。

GPU Operator 提供名为 metax-vfio-config 的 ConfigMap，管理员可通过此文件指定要绑定到vfio-pci驱动的沐曦GPU，驱动变更会在几分钟内完成。
内核态驱动灰度发布

GPU Operator 方案提供了内核态驱动灰度发布功能，管理员可配置 driver.enableRollout 开启灰度发布功能。

灰度发布功能支持分批次自动化驱动升级，支持管理员手动确定每批次升级结果。在升级的过程中，管理员可以暂停或者回滚本次升级。
方案自动化部署

GPU Operator 方案提供的云原生能力由多个软件组件协作完成，组件部署时存在参数配合，部署时序也有严格的要求，安装这些组件是一件极其复杂的事情。

因此，正如 GPU Operator 字面所传达出来的信息，此方案基于 Operator Framework [2] 实现，组件部署及同步全部由代码控制、自动化地进行。管理员通过一条 helm install 命令即可完成部署，而无需关注背后的细节。

3.2. 部署参考

3.2.1. 安装 GPU Operator

在Kubernetes管理节点执行如下命令，即可完成 GPU Operator 的安装：

helm install oci://DOMAIN/PROJECT/metax-operator \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set registry=DOMAIN/PROJECT

3.2.2. 设置Chart选项

GPU Operator Chart支持 GPU Extensions Chart全部选项。额外支持的选项，参见下方表格。

表 3.1 Global Options
选项	类型	描述
gpuDevice	struct	gpu-device组件选项，参见表 3.2
gpuLabel	struct	gpu-label组件选项，参见表 3.3
driver	struct	driver-manager组件内核态驱动控制选项，参见表 3.4，灰度升级参见表 3.11
vfio-manager	struct	vfio-manager组件选项，参见表 3.6
maca	struct	driver-manager组件 MXMACA^® 控制选项, 参见表 3.8
runtime	struct	container-runtime组件选项，参见表 3.9
exporter	struct	data-exporter组件选项，参见表 3.13
podTemplateSpec	struct	全局工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。目前仅支持 `NodeSelector`、 `Affinity` 和 `Tolerations`，参见表 3.15

表 3.2 gpu-device Options
选项	类型	描述
healthyInterval	integer	GPU健康检查间隔的秒数，＞0 时启用功能，＝0 时禁用功能，默认值为5
deploy	bool	是否启用组件，默认为 `true`，可选 `true` 和 `false`
log	struct	日志选项，参见表 2.8
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见表 3.15

表 3.3 gpu-label Options
选项	类型	描述
deploy	bool	是否启用组件，默认为 `true`，可选 `true` 和 `false`
log	struct	日志选项，参见表 2.8
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见表 3.15

表 3.4 Kernel Module Control Options
选项	类型	描述
deployPolicy	enum	资源部署策略，默认为 `PreferCloud`，可选 `PreferHost` ， `PreferNewer` 和 `Never`，参见表 3.5
payload	struct	内核驱动控制资源包选项，参见表 3.10
fwUpgradePolicy	enum	固件升级策略，默认为 `Never`，可选 `PreferCloud` 和 `Never`，参见表 3.17
fwEnableVirt	bool	是否使用虚拟化固件，默认为 `false`，可选 `true` 和 `false`, 参见表 3.18
deploy	bool	是否启用组件，默认为 `true`，可选 `true` 和 `false`
log	struct	日志选项，参见表 2.8
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见表 3.15

表 3.5 Driver Deploy Policy Options
选项	描述
PreferCloud	使用payload镜像中的内核驱动
PreferHost	优先使用主机上的内核驱动，如果不存在，则使用payload镜像中的内核驱动
PreferNewer	如果主机上的内核驱动版本高于payload镜像中的驱动版本，使用主机上的内核驱动，否则使用payload镜像中的内核驱动
Never	组件不进行内核驱动的管理

表 3.6 VFIO-PCI Control Options
选项	类型	描述
vfioConfig	struct	选择要绑定到vfio-pci的GPU设备列表，参考表 3.7
deploy	bool	是否启用组件，默认为 `true`，可选 `true` 和 `false`
log	struct	日志选项，参考表 2.8
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见表 3.15

表 3.7 VFIO-PCI Config Options
选项	类型	描述
nodeName	string	目标节点名，支持正则匹配
gpus	string list	绑定到vfio驱动的GPU序号，支持逗号分隔字符串和 `all`， `all` 表示所有GPU

表 3.8 MXMACA Control Options
选项	类型	描述
payload	struct	MXMACA^® 控制资源包选项，参见表 3.12
deploy	bool	是否启用组件，默认为 `true`，可选 `true` 和 `false`
log	struct	日志选项，参见表 2.8
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见表 3.15

表 3.9 Container Runtime Options
选项	类型	描述
deploy	bool	是否启用组件，默认为 `true`，可选 `true` 和 `false`
log	struct	日志选项，参见表 2.8
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见表 3.15

表 3.10 Driver Payload Options
选项	类型	描述
name	string	payload镜像名，默认值为 `driver-image`
version	string	payload镜像版本，若 `driver.deployPolicy` 的值不为 `Never`，需显式指定
registry	string	payload镜像地址，默认使用全局选项 `registry` 的值

表 3.11 Driver Upgrade Options (driver.upgradePolicy)
选项	类型	描述
enableRollout	bool	是否开启内核态驱动灰度发布升级，默认为 `false` ，可选 `true`
upgradeSteps[].replicas	integer or percentage	该升级批次完成后Pod为新版本的副本数量
upgradeSteps[].pauseDuration	time	定义升级完成后暂停阶段的行为。默认为空，系统自动暂停。管理员手动设置 `upgradePolicy.pause` 为 `false` 后，系统会自动进入下一升级阶段。如果设定超时时间，等超时时间达到，系统自动进入下一升级阶段
upgradeSteps[].toleration	integer or percentage	当前升级批次允许失败节点个数，默认为 `0%`
pause	bool	是否暂停灰度发布升级，默认为 `false` ，可选 `true`
maxParallel	integer or percentage	最大并行升级节点数量，默认为 `100%`。 `0` 为不设限制，一次性升级所有可用节点，当使用百分比时，系统会自动向上取整到整数
maxUnavailable	integer or percentage	本次灰度发布结束时允许节点不可用（升级失败）的数量，默认为 `0%`。所有参与升级的节点均需要升级到目标版本
maxFailureThreshold	integer	每批次最大错误重试次数，默认为 `0`
fallback	string	每批次升级遇到操作异常或者升级失败节点超过 `upgradeSteps[].toleration` 时，被视为一次失败，达到最大错误重试次数时，系统会执行相应的降级操作（暂停和回滚），默认为 `pause`，可选为 `rollback`

表 3.12 MXMACA Payload Options
选项	类型	描述
images	string list	payload镜像列表，格式为 `{IMAGE_1, IMAGE2, ...}`, 其中 `IMAGE` 应使用完整格式显式指定tag，如 `maca-c500:2.18.0.3-ubuntu18.04-amd64`
registry	string	payload镜像地址，默认使用全局选项 `registry` 的值

表 3.13 Data Exporter Options
选项	类型	描述
deploy	bool	是否启用exporter组件，默认 `false`，可选 `true` 和 `false`
service	struct	服务启动配置，参见表 3.14
podTemplateSpec	struct	组件级别工作负载的 Pod 模板配置，与 Kubernetes 原生 PodTemplateSpec 规范完全兼容。参见表 3.15

表 3.14 Exporter Service Options
选项	类型	描述
type	enum	服务类型，默认为 `ClusterIP`，可选 `ClusterIP`， `NodePort`， `LoadBalancer` 和 `ExternalName`
port	integer	服务端口号，仅在 `type` 为 `NodePort` 和 `LoadBalancer` 时可用

表 3.15 Custom Pod Template Spec Options
选项	类型	描述
spec.nodeSelector	struct	指定 Pod 调度所需的节点标签匹配规则
spec.affinity	struct	配置 Pod 与节点的亲和性/反亲和性调度策略
spec.tolerations	struct	定义 Pod 对节点污点的容忍规则，允许调度到特定节点

3.2.3. 运行时组件依赖

GPU Operator 各组件具备独立的部署开关，同时系统通过预置逻辑自动管理组件间的运行依赖。部署时需确保开启相关组件的开关，底层依赖关系将自动完成协调。若未正确启用前置组件，可能导致依赖项初始化失败或功能异常。

组件名称

前置组件

gpuLabel

无

runtime

gpuLabel

driver

gpuLabel、runtime

maca

gpuLabel、runtime

gpuDevice

gpuLabel、runtime、maca

data-exporter

gpuLabel、driver

vfio-manager

gpuLabel

3.2.4. （弃用）配置全局toleration

该功能已标记为弃用，并将在 0.11.0 版本中移除。建议迁移至新版方案，详情参见 3.2.5 工作负载 Pod 参数配置规范。

配置全局toleration，使 GPU Operator 能够部署在具有 taint 的节点上。

所有组件的toleration始终和全局toleration保持一致，单独对组件配置的toleration将会失效。

配置全局toleration的方式如下：

在安装时，传入全局toleration配置文件，初始化配置。
在安装后，修改自定义资源clusteroperator的配置信息，更新配置。

3.2.4.1. 安装时，初始化全局toleration配置

安装前创建全局toleration配置文件。

全局toleration配置文件格式与Kubernetes Tolerations配置格式保持一致，示例如下：

tolerations:
  - key: "key1"
    operator: "Equal"
    value: "value1"
    effect: "NoSchedule"
  - key: "key2"
    operator: "Equal"
    value: "value1"
    effect: "NoExecute"

安装 GPU Operator 时，接收全局toleration配置文件，设置全局toleration。

安装时，通过 --set-file tolerations=< 全局toleration配置文件 > ，传入全局toleration配置文件。
检查全局toleration是否配置成功。
```
kubectl get ds -n  metax-operator -o jsonpath='{range .items[*]}{.spec.template.spec.tolerations}{"\n"}'
```
用户可通过上述命令获取所有组件当前的toleration配置。

比较全局toleration配置文件和各个组件当前的toleration配置是否相同，相同代表全局toleration配置初始化成功。

3.2.4.2. 安装后，修改自定义资源，更新全局toleration配置

GPU Operator 部署时，会生成一个名为 cluster-operator 的 clusteroperator。编辑 cluster-operator 中toleration配置，会更新全局toleration。

编辑 cluster-operator，更新全局toleration。

使用 kubectl edit clusteroperator cluster-operator 进入编辑模式，依据以下高亮所示，添加全局tolerations。
1spec: 2 tolerations: 3 - key: "key1" 4 operator: "Equal" 5 value: "value1" 6 effect: "NoSchedule" 7 - key: "key2" 8 operator: "Equal" 9 value: "value1" 10 effect: "NoExecute
全局toleration配置格式与Kubernetes Tolerations配置格式保持一致。用户依照实际情况，更新具体toleration 配置，例如[line 3-10]所示内容。

cluster-operator 中没有 toleration 字段时，用户需要在 spec 下添加 tolerations 字段，再更新toleration配置。
检查全局toleration是否更新成功。
```
kubectl get ds -n  metax-operator -o jsonpath='{range .items[*]}{.spec.template.spec.tolerations}{"\n"}'
```
用户可通过上述命令获取所有组件当前的toleration配置。

比较更新后的toleration配置和各个组件当前的toleration配置是否相同，相同代表全局toleration配置更新成功。

3.2.5. 工作负载 Pod 参数配置规范

注意

当前版本支持 全局级 与 组件级 双维度配置，可管理字段如下：

spec：nodeSelector 、affinity 、tolerations

3.2.5.1. 配置优先级规则

组件级 > 全局级

若组件定义了 podTemplateSpec，则完全忽略全局配置，仅采用组件的 PodTemplateSpec。
字段级覆盖规则

当同时存在 tolerations 与 podTemplateSpec.spec.tolerations 时，后者优先级更高。
配置合并策略
- 基础类型：直接替换原值
- Map类型：合并键值对，存在相同键时覆盖，否则新增
- 数组类型：执行追加操作

3.2.5.2. 配置操作指南（以 tolerations 为例）

默认模板配置（Helm Values）

以下是 maca 和 driver 组件的默认模板配置：

# maca 默认模板
maca-daemonset.yaml
spec:
  tolerations:
    - key: "node-role"
      operator: "Equal"
      value: "maca"
      effect: "NoSchedule"

# driver 默认模板
driver-daemonset.yaml
spec:
   tolerations:
    - key: "node-role"
       operator: "Equal"
      value: "driver"
      effect: "NoExecute"

初始化配置（Helm Values）

定义全局与组件级参数，组件级配置会覆盖全局同名称字段：

# 全局配置
podTemplateSpec:
  spec:
    tolerations:
      - key: "node-type"
        operator: "Equal"
        value: "general"
        effect: "NoSchedule"

# 组件级配置（maca）
maca:
  podTemplateSpec:
    spec:
      tolerations:
        - key: "node-type"
          operator: "Equal"
          value: "gpu"
          effect: "NoSchedule"

运行时动态调整

通过控制台或 API 更新配置（需满足字段约束）：

# 编辑集群 Operator CR
kubectl edit clusteroperators.gpu.metax-tech.com cluster-operator

# 修改后保存生效（需确保yaml格式正确）

配置验证流程

查看 maca 组件 DaemonSet

预期结果：合并默认模板与自定义配置，tolerations 包含 node-role=maca 和 node-type=gpu。

kubectl get ds -n $namespace metax-maca -o jsonpath='{.spec.template.spec.tolerations}'
# 输出示例：
# - key: "node-role"
#   operator: "Equal"
#   value: "maca"
#   effect: "NoSchedule"
# - key: "node-type"
#   operator: "Equal"
#   value: "gpu"       #来自组件配置
#   effect: "NoSchedule"

查看 driver 组件 DaemonSet

预期结果：仅继承全局配置，tolerations 包含 node-role=driver 和 node-type=general。

kubectl get ds -n $namespace metax-driver -o jsonpath='{.spec.template.spec.tolerations}'
# 输出示例：
# - key: "node-role"
#   operator: "Equal"
#   value: "driver"
#   effect: "NoExecute"
# - key: "node-type"
#   operator: "Equal"
#   value: "general"   #来自全局配置
#   effect: "NoSchedule"

3.2.6. 配置虚拟化

GPU Operator 在将所有软件组件部署到集群上后，会生成一个名为 driver-config 的 ConfigMap。

{
  "node-vfnums": "nodes:
    sample-node:
      vfnum: 4
    sample-node2:
      vfnum: 2
    foo:
      vfnum: 2
  "
}

用户可通过修改其内容控制集群上节点的虚拟化设置，如新增 [line 7-8] 所示内容，将foo节点上的每张显卡分为2个VF实例。根据 ConfigMap 传递到工作节点所需的时间不同，管理员可在几分钟内观测到foo节点上 metax-tech.com/gpu 资源总数变为 $N_\mathrm(gpu) \times M_\mathrm(vfnum)$ 。期间，foo节点上以 metax-gpu-device 开头命名的 pod 被自动销毁重建属于预期行为。

3.2.6.1. 配置绑定 vfio-pci 驱动

GPU Operator 部署完成后，集群会生成名为 metax-vfio-config 的 ConfigMap，用于配置 GPU 绑定 vfio-pci 驱动。

配置初始化及更新

用户可通过修改 values.yaml 配置文件或通过 --set 配置 vfioManager.vfioConfig 来选择要绑定到 vfio-pci 驱动的沐曦GPU设备。

values.yaml 示例：

vfioManager:
  vfioConfig:
    - nodeName: worknode1
      gpus: "0,1,2"
    - nodeName: worknode\d+
      gpus: "0,1,2"

--set 示例：

helm install oci://DOMAIN/PROJECT/metax-operator \
  --create-namespace -n metax-operator \
  --generate-name \
  --wait \
  --set vfioManager.vfioConfig[0].nodeName='worknode1' \
  --set vfioManager.vfioConfig[0].gpus='0\,1\,2' \
  --set vfioManager.vfioConfig[1].nodeName='worknode\\d+' \
  --set vfioManager.vfioConfig[1].gpus='0\,1\,2'

该配置会在 metax-vfio-config 中生成对应的参数并生效。

更新配置项

GPU Operator 启动后，可通过以下命令进入对 metax-vfio-config 的编辑模式：
```
kubectl edit configmap metax-vfio-config -n metax-operator
```
在打开的修改框中修改该 ConfigMap ，配置文件修改后，驱动的变更会在几分钟内完成。

配置项说明

nodeName: 集群中安装有沐曦 GPU 的节点名。

支持正则匹配，如以上 values.yaml 示例中 [line 5] worknode\\d+ 匹配所有以 worknode 开头并后面跟数字的节点名。

gpus: 要绑定的沐曦 GPU 序号列表。

支持逗号分隔数组或 all 选项。值为 all 时表示选择所有GPU。系统会扫描所有沐曦 GPU 并排序，沐曦 GPU 序号为排序结果的索引。排序结果不保证稳定。

当开启虚拟化时，则将所有的 VF 进行排序。

检查更新结果

用户可在控制节点通过以下命令查看沐曦 GPU 的 vfio-pci 驱动绑定情况：

kubectl get node <node-name> -o jsonpath='{.metadata.annotations.metax-tech\.com/gpu-vfio}'

其输出为如下所示列表：

{"0":1,"1":1,"3":0}

其中键为目标 GPU 的序号，值为 1 则绑定 vfio-pci 驱动成功，为 0 则失败。失败情况下， vfio-manager 会不断重试对该GPU的绑定。

以上输出示例表示成功绑定了序号为0和1的沐曦GPU到 vfio-pci 驱动。而3号GPU绑定失败。

备注

未被选中绑定到 vfio-pci 驱动的沐曦GPU会被 driver-manager 组件接管，并自动绑定到原生驱动上。

3.2.7. 配置内核驱动参数

GPU Operator 在将所有软件组件部署到集群上后，会生成一个名为 driver-config 的 ConfigMap。

用户可以通过修改其内容控制集群节点上的内核驱动参数。内核驱动参数分为集群级别（ module-params ）和节点级别（ node-module-params ）。

节点级别的配置优先级更高，即同时存在集群级别和节点级别的配置，最终生效的是节点的配置。如果节点配置不存在，会使用集群配置。如果上述配置都不存在，将会使用默认配置。

{
  "module-params": "
    xcore_page_size: 10
  ",
  "node-module-params": "
    sample-node1:
      xcore_page_size: 12
  ",
  "node-vfnums": "nodes:
    sample-node:
      vfnum: 4
    sample-node2:
      vfnum: 2
  "
}

以上示例中 [line 2-4] 所示内容为集群级别配置，将集群上所有节点的 metax 驱动的 xcore_page_size 设置为 10。

以上示例中 [line 5-8] 所示内容为节点级别配置，将集群上 sample-node1 节点的metax驱动的 xcore_page_size 设置为 12。

根据 ConfigMap 传递到工作节点所需的时间不同，管理员可在几分钟内观测到 sample-node1 节点上 /sys/module/metax/parameters/xcore_page_size 参数值为 12。其余节点为上的值 10。

备注

内核的参数实际生效结果以内核的具体行为为准。具体参数配置可以从驱动参数中获取。目前 driver-config 支持 xcore_page_size 、gpu_model 参数的配置。

3.2.8. 配置内核驱动灰度发布

GPU Operator 提供内核驱动灰度发布方案，管理员可按照如下示例学习如何配置驱动灰度发布：

配置灰度发布。

配置 enableRollout 为 true，设置每批次升级参数。

upgradeSteps 用于设置每批次升级参数。 replicas 表示该升级批次完成后Pod为新版本的副本数量，在使用百分号时，系统会确保至少有一个Pod会被升级。

假定集群有10个工作节点，系统按照如下配置驱动灰度发布：
- 第一次升级副本数量为2，最大并行升级参数为50%，实际最大并行升级节点数量为 1=max(1,ROUNDUP(50%*2))，系统将会经历两次循环，每次升级一个节点，升级完成后系统进入暂停状态，管理员需要手动触发下一批次升级。
- 第二次和第三次升级副本数量均为3，最大并行升级参数为50%，实际最大并行升级节点数量为 2=max(1,ROUNDUP(50%*3))，系统将会经历两次循环，第一次会升级两个节点，第二次升级一个节点，升级完成后系统会自动超时等待10s，在此期间管理员可以检查升级情况，可以设置升级暂停，若没有任何操作，系统将会在10s后自行进入下一批次升级。
- 第四次升级 replicas 设置为 100%，确保所有的Pod均升级到新版本，实际升级的副本数量为2，升级完成后系统进入暂停状态，管理员需要手动确认本次升级完成。
```
# 编辑cr
kubectl edit clusteroperators.gpu.metax-tech.com cluster-operator

# 编辑灰度发布策略
driver:
   upgradePolicy:
      enableRollout: true
      upgradeSteps:
      - replicas: 2
        pause:
      - replicas: 5
        pauseDuration: 10000
      - replicas: 8
        pauseDuration: 10000
      - replicas: 100%
        pause:
      pause: false
      maxParallel: 50%
      maxUnavailable: 0
      maxFailureThreshold: 3
      fallback: pause
```

升级过程中调整参数。

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

# 强制回滚
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"}]'

查看执行状态。

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.16 Driver Upgrade Status
选项	类型	描述
lastAppliedSpec	string	升级前 `metax-driver` DaemonSet配置
lastCoDriverSpec	string	升级前 `metax-driver` ClusterOperator中的spec.driver配置
upgrading	bool	标识KMD灰度升级是否运行
condition[].type	enum	升级状况的类型，可选值 `Progressing`， `Succeed`， `Failed`， `Terminating`
condition[].status	string	升级状况是否适用，可选值 `True`， `False`， `Unknown`
condition[].lastTransitionTime	time	灰度发布上次从一种状态切换到另一种状态的时间戳
condition[].reason	string	机器可读的，驼峰编码的（UpperCamelCase）的文字，表述上次状况变化的原因
condition[].message	string	人类可读的消息，给出上次状态（包括灰度发布升级阶段和批次升级）转换的详细信息
phase	enum	灰度发布升级阶段，可选值 `Idling`， `Progressing` ， `Terminating` ， `Disabled`， `Disabling`
message	string	人类可读的消息，给出上次灰度发布升级状态转换的详细信息
status.lastPodSpecRevision	string	升级前Pod的Spec版本号
status.upgradingPodSpecRevision	string	升级后Pod的Spec版本号
status.currentStepIndex	integer	当前批次升级索引，表明当前为第几次升级
status.currentUpgradeReplicas	integer	当前批次升级副本数量
status.currentUpgradeReadyReplicas	integer	当前批次升级成功的副本数量
status.currentFailureRetry	integer	当前批次升级失败次数
status.currentStepState	enum	当前批次状态，，可选值 `StepUpgradeInit`， `StepUpgrade` ， `StepPaused` ， `StepReady`， `Completed`
status.message	string	人类可读的消息，给出升级批次转换的详细信息
status.totalUpgradeReplicas	integer	本次升级总副本数量
status.totalUpgradeReadyReplicas	integer	本次升级成功的副本数量
status.lastUpdateTime	time	状态更新的时间戳
status.recheckTime	time	系统自动进入下一升级阶段的时间戳

升级完成。

提交灰度升级策略并且开启 enableRollout 时，系统会通过 validating-admission-webhook 校验参数，参数异常时会返回失败。

执行灰度升级时，集群必须处于离线状态，无运行中的任务。

3.2.9. 固件升级

用户可以通过配置固件升级参数来升级GPU设备上的固件。

配置固件升级

管理员可配置 driver.fwUpgradePolicy 为 PreferCloud 来使用payload镜像中的固件来升级。

目前支持以下参数配置：

表 3.17 Driver Firmware Upgrade Options

选项

描述

PreferCloud

使用payload镜像中的固件升级

Never

不升级固件

表 3.18 Driver Firmware Virt Options

选项

描述

true

使用虚拟化版本固件进行升级，如果需要使用VF，请使用虚拟化版本固件

false

使用非虚拟化版本固件进行升级

等待固件生效

固件升级成功后，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
如果需要立即生效，可以手动重启服务器，重启服务器前请确认相关的业务已经正常停止。
检查固件版本

主机重启后，可以使用 mx-smi 工具检查当前的固件版本是否符合预期。
关闭固件升级

管理员可配置 driver.fwUpgradePolicy 为 Never 来关闭固件升级功能。

备注

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

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

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

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

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

3.2.10. 配置sGPU

当gpu-device以sGPU模式运行时，会将沐曦GPU注册为 metax-tech.com/sgpu 资源。用户可通过以下步骤使用该资源。

设置gpu-device以sGPU模式运行

通过给指定节点增加特定标签的方式，使节点上的gpu-device组件以sGPU模式运行。

kubectl label node sample-node1 metax-tech.com/gpu-device.mode=sgpu

设置后观察节点的可用资源。

kubectl get node sample-node1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/sgpu")))'

示例输出：

{
  "metax-tech.com/sgpu": "16"
}

如果需要恢复传统的native模式，可以通过以下命令恢复。

kubectl label node sample-node1 metax-tech.com/gpu-device.mode=native --overwrite

设置后观察节点的可用资源。

kubectl get node sample-node1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/gpu")))'

示例输出：

{
  "metax-tech.com/gpu": "1"
}

配置sGPU调度策略（可选）

通过给指定节点增加特定标签的方式，动态设置sGPU的调度策略。

kubectl label node sample-node1 metax-tech.com/gpu-device.qos-policy=best-effort --overwrite

目前支持的调度策略选项如下：

表 3.19 gpu-device QOS Policy Options
选项	描述
best-effort	各个sGPU不限制算力，默认配置
fixed-share	各个sGPU有固定的算力配额，且无法超过固定配额使用
burst-share	各个sGPU有固定的算力配额，若GPU卡还有空闲算力，就可以被sGPU使用

备注

该功能需要依赖container-runtime组件，请确认安装时已部署相应组件。
该功能需要配合HAMi调度器使用，请确认使用前已安装HAMi。

3.2.11. 验证部署

GPU Operator 引入了更多的软件组件，并且具有更为复杂的组件间依赖关系，但验证部署的方式和 GPU Extensions 方案保持一致。无论使用何种部署方案，均需要在所有组件正常工作的前提下，节点上才有可分配的 metax-tech.com/gpu 资源，以此保证用户作业的安全。

详细信息，参见 GPU Extensions 的 2.1.3 验证部署。

3.2.12. 卸载 GPU Operator

若需卸载 GPU Operator，可先通过 helm list -n metax-operator 命令查询已安装的Chart，再执行 helm uninstall <CHART> -n metax-operator --wait 命令进行卸载。

备注

-n 指定的参数为 namespace，应与安装时所指定的值保持一致。

也可直接运行以下脚本自动检查已安装的 GPU Operator 并进行卸载。

chart=$(helm list -q -f "metax" -n metax-operator)
if [[ -n $chart ]]; then
    helm uninstall $chart -n metax-operator --wait
fi

备注

为确保 GPU Operator 部署的资源能够被正确清理， --wait 参数为必选项，不可省略。

3.3. 提交作业

3.3.1. 制作容器镜像

加载基础镜像

首先需准备镜像，加载镜像的操作步骤参见 1.4.3 MXMACA® 容器镜像。
准备Dockerfile

在 GPU Operator 方案部署的集群中，应用容器镜像无需携带 MXMACA^® 软件栈，因此尺寸更加小巧，同时在有必要升级 MXMACA^® 版本时，应用容器镜像也无需重建。尽管应用容器镜像可以不包含 MXMACA^® 的文件，但容器构建过程中仍然需要 MXMACA^® 的基础镜像作为构建环境。推荐在 Dockerfile 使用 multi-stage build 功能。

以下为 Dockerfile 示例：
1FROM cr.metax-tech.com/library/maca-c500:2.18.0.3-ubuntu18.04-amd64 as builder 2 3RUN apt-get update && apt-get install -y \ 4 autoconf \ 5 build-essential \ 6 libtool \ 7 patchelf \ 8 pkg-config \ 9 ... 10 11ENV VAR1=VALUE1 12ENV VAR2=VALUE2 13... 14 15WORKDIR /workspace 16COPY . /workspace 17RUN make OUTPUT=/app 18 19FROM ubuntu:18.04 20 21RUN apt-get update && apt-get install -y \ 22 libelf1 \ 23 libltdl7 \ 24 libnuma1 \ 25 ... \ 26&& rm -rf /var/lib/apt/lists/* 27 28COPY --from=builder /app /app
用户基于此示例编写适用于实际工程的 Dockerfile 时，需注意以下细节：
- [line 1] 使用 MXMACA^® 基础镜像作为 builder 镜像，提供必要的 MXMACA^® 软件栈工具及库文件。
- [line 9] 此处增加构建用户应用所必须的工具和开发依赖库。
- [line 13] 此处设置构建过程所需的环境变量。
- [line 19] 基于 ubuntu:18.04 镜像而非 MXMACA^® 基础镜像。
- [line 25] 修改此处以安装用户应用运行时依赖库， libelf1、 libltdl7 和 libnuma1 为 MXMACA^® SDK运行时依赖。
- [line 28] 从 builder 容器中拷贝构建好的应用至基础容器。
使用此过程构建应用容器可避免因开发工具、开发依赖库以及构建过程临时文件造成的存储浪费。
构建镜像

假设用户工作目录有如下结构， Project 为应用项目根目录， Dockerfile 放置于同级目录。
```
workspace
├── Dockerfile
└── Project
    ├── Makefile
    └── src
```
用户可在 workspace 目录运行如下命令完成镜像的构建：
```
docker build -f Dockerfile -t DOMAIN/PROJECT/application:1.0 ./Project
```

3.3.2. 准备作业yaml文件

用户可参考如下示例编写作业yaml文件：

apiVersion: v1
kind: Pod
metadata:
  name: application
  labels:
    app: application
spec:
  nodeSelector:
    metax-tech.com/gpu.vfnum: "0"
    metax-tech.com/gpu.product: "C500"
  containers:
  - image: DOMAIN/PROJECT/application:1.0
    name: application-container
    command: ["/bin/bash", "-c", "--"]
    args: ["/app/bin/xxx --option=val; sleep infinity"]
    resources:
      limits:
        metax-tech.com/gpu: 2

3.3.3. 加载指定版本 MXMACA^®

在作业yaml的配置中设置环境值 METAX_MACA_VERSION，系统会自动查找该版本 MXMACA^®，如未发现，会返回错误。

用户可参考如下示例编写作业yaml文件：

apiVersion: v1
kind: Pod
...
spec:
  containers:
    env:
    - name: METAX_MACA_VERSION
      value: "maca-2.18.0.3"
    resources:
      limits:
        metax-tech.com/gpu: 2

查找说明：

该功能仅在申请了沐曦GPU的作业上生效。
按照前缀匹配，例如，配置值可设置为 maca-2， maca-2.18， maca-2.18.0 或 maca-2.18.0.3 。
传入 maca 和 maca- 会拒绝匹配，返回错误。
对符合要求的列表按照版本号从新到旧（降序）排序，选择最新版本的 MXMACA^® 资源。

3.3.4. 提交作业

执行 kubectl create -f sample.yaml 命令提交作业。

3.4. KubeVirt添加GPU

KubeVirt旨在将虚拟机作为第一类资源集成到 Kubernetes 中。使用KubeVirt可以在 Kubernetes 集群上以类似于管理容器的方式来管理和编排虚拟机。

KubeVirt提供了一种将主机设备分配给虚拟机的机制。以下示例展示了如何将集群中的沐曦GPU设备分配给KubeVirt虚拟机。

准备PCI设备直通

为了将主机上的PCI设备（沐曦GPU）直通到虚拟机，需要以下准备步骤：

开启IOMMU

主机设备直通要求启用IOMMU扩展。要启用IOMMU，根据CPU类型，主机应通过附加的内核参数启动。 x86平台参见表 3.20；Arm平台参见表 3.21。

表 3.20 x86 Linux内核IOMMU配置参数

参数格式

说明

intel_iommu=on

启用Intel IOMMU

amd_iommu=on

启用AMD IOMMU

iommu=pt 或 iommu.passthrough=1

仅在PCI设备透传时使用IOMMU

表 3.21 Arm Linux内核IOMMU配置参数

参数格式

说明

iommu.passthrough=1

仅在PCI设备透传时使用IOMMU

以下示例为运行在Intel CPU的Ubuntu操作系统中，启动IOMMU扩展：
#使用root用户
$ sudo su

#编辑 GRUB 配置文件
$ vim /etc/default/grub
...
GRUB_CMDLINE_LINUX="... intel_iommu=on"
...

#更新配置文件
$ update-grub

#使用最新的内核参数启动
$ reboot

#检查iommu是否开启
$ dmesg | grep -i iommu

加载vfio-pci驱动模块

通过 modprobe vfio-pci 命令将 vfio-pci 驱动模块加载至主机，并通过 ls /sys/bus/pci/drivers/ | grep vfio-pci 检查是否加载成功。

将沐曦GPU绑定到指定vfio-pci驱动

KubeVirt仅支持透传绑定到 vfio-pci 驱动的主机设备。 GPU Operator 方案提供的 vfio-manager 组件为沐曦GPU提供了单卡粒度的 vfio-pci 驱动绑定功能。可参考 3.2.6.1 配置绑定 vfio-pci 驱动，通过配置 metax-vfio-config 项为沐曦GPU绑定 vfio-pci 驱动。

获取集群中可用的沐曦GPU

在将需要直通给KubeVirt虚拟机的主机设备绑定至 vfio-pci 驱动后， gpu-device 组件会将对应的沐曦GPU上报给Kubernetes集群。可以通过以下命令获取Kubernetes集群中是否存在可用于KubeVirt的沐曦GPU设备：
```
kubectl get node worknode1 -o json | jq '.status.allocatable | with_entries(select(.key | startswith("metax-tech.com/vfio-gpu"))) | with_entries(select(.value != "0"))'
```
输出示例：
```
{
  "metax-tech.com/vfio-gpu": "1"
}
```
以上输出示例表示集群中可被占用的 "metax-tech.com/vfio-gpu" 资源的数量为1。需记录下沐曦GPU资源名称，以便后续在创建KubeVirt资源时将沐曦GPU加入可用设备列表。

查看GPU设备型号

为获取需要透传给KubeVirt虚拟机的GPU设备型号，可在工作节点上通过 lspci -nnk -d 9999: 命令查看沐曦GPU设备信息。

输出示例：

09:00.0 Display controller [0380]: Device [9999:4001]
        Subsystem: Red Hat, Inc. Device [1af4:1100]
        Kernel driver in use: vfio-pci
        Kernel modules: metax
0a:00.0 Display controller [0380]: Device [9999:4001]
        Subsystem: Red Hat, Inc. Device [1af4:1100]
        Kernel driver in use: METAX
        Kernel modules: metax
... ...

以上示例中[line 3]显示该设备为绑定到 vfio-pci 驱动的沐曦GPU设备。[line 1]显示其对应的 [厂商ID:设备ID] ，以上示例中为 [9999:4001]。

安装KubeVirt

用户可通过KubeVirt 快速启动 [3] 安装KubeVirt。安装KubeVirt CR部分可参考 vfio-gpu资源申请。

有关配置选项的更多信息，请参阅KubeVirt [4] 用户指南。部署成功后，用户可观察到集群中 virt-operator、 virt-api、 virt-handler、 virt-controller 等组件正常运行。
准备虚拟机镜像

镜像可以直接下载开源三方镜像。

备注

三方镜像内核版本可能无法直接安装metax-driver驱动，需要升级内核。

也可以通过如下Dockerfile构建，例如准备一个qcow2格式的Ubuntu虚拟机镜像并拷贝到 /disk 目录下：
```
#Dockerfile文件
$ cat ./Dockerfile

FROM scratch

ADD ubuntu-template.qcow2 /disk/

#build镜像
$ docker build -t ubuntu-vm:18.04 .
```
之后可使用构建好的虚拟机镜像创建虚拟机。
创建带GPU的虚拟机

准备好KubeVirt环境和虚拟机镜像后，用户可通过编写虚拟机资源的配置文件来定义虚拟机，例如定义 VirtualMachine 、 VirtualMachineInstance 等虚拟机资源。

其中可通过指定 spec.domain.devices.hostDevices 字段来为虚拟机分配沐曦GPU，示例配置可参考 vfio-gpu资源申请中步骤2 。其中关键字段配置为：
- deviceName : 表示设备的资源名称
- name: 表示虚拟机中设备的名称
- containerDisk.image: 虚拟机镜像
将示例配置保存为 testvm.yaml ，用户可通过命令 kubectl apply -f testvm.yaml 创建名为 testvm 的虚拟机。
启动KubeVirt虚拟机

用户可通过 virtctl 二进制工具管理KubeVirt虚拟机。 virtctl 获取请参阅kubevirt Release [5] 。
1. 启动名为 testvm 的虚拟机：
$ virtctl start testvm
1. 登录名为 testvm 的虚拟机：
#vnc登录 $ virtctl vnc testvm #ssh账号密码登录 $ virtctl ssh testvm --local-ssh
验证GPU设备

登录到虚拟机内部，通过 lspci 命令检查GPU设备是否存在:
```
$ lscpi | grep 9999
```
备注

用户如需MXMACA软件包，可在虚拟机内部自行安装。

Kubernetes	CRI	Version
= 1.23	docker	≥ 18.09.3
= 1.23	containerd	≥ 1.5.0
≥ 1.24	containerd	≥ 1.5.0

Host OS	Ubuntu	18.04 / 20.04 / 22.04
	CentOS	8.x / 9.x
	OpenEuler	20.03 / 22.03