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配置

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

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

    1tolerations:
    2  - key: "key1"
    3    operator: "Equal"
    4    value: "value1"
    5    effect: "NoSchedule"
    6  - key: "key2"
    7    operator: "Equal"
    8    value: "value1"
    9    effect: "NoExecute"
    
  2. 安装 GPU Operator 时,接收全局toleration配置文件,设置全局toleration。

    安装时,通过 --set-file tolerations=< 全局toleration配置文件 > ,传入全局toleration配置文件。

  3. 检查全局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。

  1. 编辑 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配置。

  2. 检查全局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. 配置优先级规则

  1. 组件级 > 全局级

    若组件定义了 podTemplateSpec,则完全忽略全局配置,仅采用组件的 PodTemplateSpec。

  2. 字段级覆盖规则

    当同时存在 tolerations 与 podTemplateSpec.spec.tolerations 时,后者优先级更高。

  3. 配置合并策略

    • 基础类型:直接替换原值

    • Map类型:合并键值对,存在相同键时覆盖,否则新增

    • 数组类型:执行追加操作

3.2.5.2. 配置操作指南(以 tolerations 为例)

默认模板配置(Helm Values)

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

 1# maca 默认模板
 2maca-daemonset.yaml
 3spec:
 4  tolerations:
 5    - key: "node-role"
 6      operator: "Equal"
 7      value: "maca"
 8      effect: "NoSchedule"
 9
10# driver 默认模板
11driver-daemonset.yaml
12spec:
13   tolerations:
14    - key: "node-role"
15       operator: "Equal"
16      value: "driver"
17      effect: "NoExecute"

初始化配置(Helm Values)

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

 1# 全局配置
 2podTemplateSpec:
 3  spec:
 4    tolerations:
 5      - key: "node-type"
 6        operator: "Equal"
 7        value: "general"
 8        effect: "NoSchedule"
 9
10# 组件级配置(maca)
11maca:
12  podTemplateSpec:
13    spec:
14      tolerations:
15        - key: "node-type"
16          operator: "Equal"
17          value: "gpu"
18          effect: "NoSchedule"

运行时动态调整

通过控制台或 API 更新配置(需满足字段约束):

1# 编辑集群 Operator CR
2kubectl edit clusteroperators.gpu.metax-tech.com cluster-operator
3
4# 修改后保存生效(需确保yaml格式正确)

配置验证流程

  • 查看 maca 组件 DaemonSet

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

     1kubectl get ds -n $namespace metax-maca -o jsonpath='{.spec.template.spec.tolerations}'
     2# 输出示例:
     3# - key: "node-role"
     4#   operator: "Equal"
     5#   value: "maca"
     6#   effect: "NoSchedule"
     7# - key: "node-type"
     8#   operator: "Equal"
     9#   value: "gpu"       #来自组件配置
    10#   effect: "NoSchedule"
    
  • 查看 driver 组件 DaemonSet

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

     1kubectl get ds -n $namespace metax-driver -o jsonpath='{.spec.template.spec.tolerations}'
     2# 输出示例:
     3# - key: "node-role"
     4#   operator: "Equal"
     5#   value: "driver"
     6#   effect: "NoExecute"
     7# - key: "node-type"
     8#   operator: "Equal"
     9#   value: "general"   #来自全局配置
    10#   effect: "NoSchedule"
    

3.2.6. 配置虚拟化

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

 1{
 2  "node-vfnums": "nodes:
 3    sample-node:
 4      vfnum: 4
 5    sample-node2:
 6      vfnum: 2
 7    foo:
 8      vfnum: 2
 9  "
10}

用户可通过修改其内容控制集群上节点的虚拟化设置,如新增 [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 示例:

    1vfioManager:
    2  vfioConfig:
    3    - nodeName: worknode1
    4      gpus: "0,1,2"
    5    - nodeName: worknode\d+
    6      gpus: "0,1,2"
    
  • --set 示例:

    1helm install oci://DOMAIN/PROJECT/metax-operator \
    2  --create-namespace -n metax-operator \
    3  --generate-name \
    4  --wait \
    5  --set vfioManager.vfioConfig[0].nodeName='worknode1' \
    6  --set vfioManager.vfioConfig[0].gpus='0\,1\,2' \
    7  --set vfioManager.vfioConfig[1].nodeName='worknode\\d+' \
    8  --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 )。

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

 1{
 2  "module-params": "
 3    xcore_page_size: 10
 4  ",
 5  "node-module-params": "
 6    sample-node1:
 7      xcore_page_size: 12
 8  ",
 9  "node-vfnums": "nodes:
10    sample-node:
11      vfnum: 4
12    sample-node2:
13      vfnum: 2
14  "
15}

以上示例中 [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 提供内核驱动灰度发布方案,管理员可按照如下示例学习如何配置驱动灰度发布:

  1. 配置灰度发布。

    配置 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
    
  2. 升级过程中调整参数。

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

    # 强制回滚
    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"}]'
    
  3. 查看执行状态。

    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

    系统自动进入下一升级阶段的时间戳

  4. 升级完成。

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

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

3.2.9. 固件升级

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

  1. 配置固件升级

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

    目前支持以下参数配置:

    表 3.17 Driver Firmware Upgrade Options

    选项

    描述

    PreferCloud

    使用payload镜像中的固件升级

    Never

    不升级固件

    表 3.18 Driver Firmware Virt Options

    选项

    描述

    true

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

    false

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

  2. 等待固件生效

    固件升级成功后,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
    

    如果需要立即生效,可以手动重启服务器,重启服务器前请确认相关的业务已经正常停止。

  3. 检查固件版本

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

  4. 关闭固件升级

    管理员可配置 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 资源。用户可通过以下步骤使用该资源。

  1. 设置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"
      }
      
  2. 配置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. 加载基础镜像

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

  2. 准备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 容器中拷贝构建好的应用至基础容器。

    使用此过程构建应用容器可避免因开发工具、开发依赖库以及构建过程临时文件造成的存储浪费。

  3. 构建镜像

    假设用户工作目录有如下结构, Project 为应用项目根目录, Dockerfile 放置于同级目录。

    workspace
    ├── Dockerfile
    └── Project
        ├── Makefile
        └── src
    

    用户可在 workspace 目录运行如下命令完成镜像的构建:

    docker build -f Dockerfile -t DOMAIN/PROJECT/application:1.0 ./Project
    

3.3.2. 准备作业yaml文件

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

 1apiVersion: v1
 2kind: Pod
 3metadata:
 4  name: application
 5  labels:
 6    app: application
 7spec:
 8  nodeSelector:
 9    metax-tech.com/gpu.vfnum: "0"
10    metax-tech.com/gpu.product: "C500"
11  containers:
12  - image: DOMAIN/PROJECT/application:1.0
13    name: application-container
14    command: ["/bin/bash", "-c", "--"]
15    args: ["/app/bin/xxx --option=val; sleep infinity"]
16    resources:
17      limits:
18        metax-tech.com/gpu: 2

3.3.3. 加载指定版本 MXMACA®

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

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

 1apiVersion: v1
 2kind: Pod
 3...
 4spec:
 5  containers:
 6    env:
 7    - name: METAX_MACA_VERSION
 8      value: "maca-2.18.0.3"
 9    resources:
10      limits:
11        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虚拟机。

  1. 准备PCI设备直通

    为了将主机上的PCI设备(沐曦GPU)直通到虚拟机,需要以下准备步骤:

    1. 开启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
    
    1. 加载vfio-pci驱动模块

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

    1. 将沐曦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 驱动。

  2. 获取集群中可用的沐曦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加入可用设备列表。

  3. 查看GPU设备型号

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

    输出示例:

    109:00.0 Display controller [0380]: Device [9999:4001]
    2        Subsystem: Red Hat, Inc. Device [1af4:1100]
    3        Kernel driver in use: vfio-pci
    4        Kernel modules: metax
    50a:00.0 Display controller [0380]: Device [9999:4001]
    6        Subsystem: Red Hat, Inc. Device [1af4:1100]
    7        Kernel driver in use: METAX
    8        Kernel modules: metax
    9... ...
    

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

  4. 安装KubeVirt

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

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

  5. 准备虚拟机镜像

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

    备注

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

    也可以通过如下Dockerfile构建,例如准备一个qcow2格式的Ubuntu虚拟机镜像并拷贝到 /disk 目录下:

    #Dockerfile文件
    $ cat ./Dockerfile
    
    FROM scratch
    
    ADD ubuntu-template.qcow2 /disk/
    
    #build镜像
    $ docker build -t ubuntu-vm:18.04 .
    

    之后可使用构建好的虚拟机镜像创建虚拟机。

  6. 创建带GPU的虚拟机

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

    其中可通过指定 spec.domain.devices.hostDevices 字段来为虚拟机分配沐曦GPU,示例配置可参考 vfio-gpu资源申请 中 步骤2 。 其中关键字段配置为:

    • deviceName : 表示设备的资源名称

    • name: 表示虚拟机中设备的名称

    • containerDisk.image: 虚拟机镜像

    将示例配置保存为 testvm.yaml ,用户可通过命令 kubectl apply -f testvm.yaml 创建名为 testvm 的虚拟机。

  7. 启动KubeVirt虚拟机

    用户可通过 virtctl 二进制工具管理KubeVirt虚拟机。 virtctl 获取请参阅kubevirt Release [5] 。

    1. 启动名为 testvm 的虚拟机:

    $ virtctl start testvm
    
    1. 登录名为 testvm 的虚拟机:

    #vnc登录
    $ virtctl vnc testvm
    
    #ssh账号密码登录
    $ virtctl ssh testvm --local-ssh
    
  8. 验证GPU设备

    登录到虚拟机内部,通过 lspci 命令检查GPU设备是否存在:

    $ lscpi | grep 9999
    

    备注

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