1. 概述

Kubernetes（k8s）是一款流行的开源容器编排器，广泛应用于数据中心等场景下。 沐曦实现了一系列的基础软件，用于支持在Kubernetes上使用沐曦GPU以及 MXMACA® 软件栈。 这些组件以容器的形式提供，运行在k8s集群上，服务于用户应用运行的各个环节。 针对于不同的使用需求和场景，沐曦提供了两个名为 GPU Extensions 和 GPU Operator 的 Helm Chart ，用于k8s组件的部署。

1.1. Kubernetes组件

gpu-device

基于Kubernetes Device Plugin Framework实现，负责向Kubernetes注册沐曦GPU设备，并以 metax-tech.com/gpu 资源的形式提供。 gpu-device 包含了资源分配器的逻辑实现，对于确定份数的GPU资源请求，gpu-device 总是确保从避免资源碎片，卡间互联拓扑角度进行最优分配。 gpu-device 会定期检查沐曦GPU设备的健康状态，识别出故障的GPU资源，并将其从可分配资源中移除。

gpu-label

是沐曦私有实现的控制器，负责监控k8s节点上沐曦GPU及 MXMACA® 软件栈的状态信息，并以标签的形式对节点进行标记。 用户提交任务时，可通过在 nodeSelector 字段设置节点标签的形式来筛选符合预期的节点。 例如，根据沐曦GPU显卡型号、虚拟化配置等要求筛选节点。

driver-manager

负责维护k8s节点上的驱动，包括 MXMACA® 用户态软件栈和内核驱动的安装及维护，以及虚拟化相关配置。

vfio-manager

负责将k8s节点上的沐曦GPU绑定至vfio-pci驱动，支持用户通过配置实现沐曦GPU单卡粒度的绑定。 未被选择为绑定到vfio-pci驱动的沐曦GPU，会由 driver-manager 组件接管并绑定。

container-runtime

沐曦私有容器运行时，是k8s云原生方案的核心组件。 在 container-runtime 的帮助下，用户的应用容器镜像无需携带 MXMACA® 软件栈，因此可以得到尺寸更小的容器镜像，并且在有升级 MXMACA® 版本的需求时也无需重新构建容器镜像。

operator-controller

基于Operator Framework实现，负责自动化地完成沐曦k8s组件在集群上的部署以及配置工作。

1.2. Helm Chart

沐曦提供两种k8s组件的推荐部署方案，并分别制作了 Helm Chart 以方便使用，用户应根据实际的应用场景选择其一。

GPU Extensions

方案使用 gpu-device 和 gpu-label 两个组件，为容器使用沐曦GPU提供必需的GPU设备资源注册及分配能力。 此方案较为简明，对集群环境要求少，要求Kubernetes版本 ≥ 1.23。

GPU Operator

方案使用全部的组件，除具备 GPU Extensions 方案的全部能力之外，针对 MXMACA® 软件栈和内核驱动在Kubernetes集群中的使用进一步云原生化，减轻集群中软件运行负担，降低运维难度。 此方案要求集群满足如下条件：

Kubernetes

≥ 1.23

Container Runtime

docker

≥ 18.09.3

containerd

≥ 1.5.0

Host OS

Ubuntu

18.04 / 20.04 / 22.04

CentOS

8.x / 9.x

OpenEuler

20.03 / 22.03

1.3. 软件清单

本文所涉及的软件列表如下，用户可使用 helm 或 docker 工具，根据下表中提供的URL来获取相应制品。

Type

Artifact URL

Helm Chart

oci://cr.metax-tech.com/cloud/metax-gpu-extensions

Helm Chart

oci://cr.metax-tech.com/cloud/metax-operator

Image

cr.metax-tech.com/cloud/gpu-device

Image

cr.metax-tech.com/cloud/gpu-label

Image

cr.metax-tech.com/cloud/driver-manager

Image

cr.metax-tech.com/cloud/vfio-manager

Image

cr.metax-tech.com/cloud/container-runtime

Image

cr.metax-tech.com/cloud/operator-controller

备注

请通过商务途径获得 cr.metax-tech.com 的访问权限或离线安装包。

1.4. 离线安装包

Kubernetes组件容器镜像以及 Helm Chart 可以从 metax-gpu-k8s-package.<VERSION>.tar.gz 压缩包中获取。 以0.8.0版本为例，解压 metax-gpu-k8s-package.0.8.0.tar.gz 以获取容器镜像安装工具，以及 GPU Extensions 和 GPU Operator 的 Helm Chart。

$ mkdir k8s
$ tar -C k8s -xvzf metax-gpu-k8s-package.0.8.0.tar.gz
metax-k8s-images.0.8.0.run
metax-gpu-extensions-0.8.0.tgz
metax-operator-0.8.0.tgz

备注

GPU Operator 目前仅支持曦云®系列加速卡，其他系列的沐曦产品应使用 metax-gpu-k8s-package.<VERSION>-base.tar.gz 软件包，其中不会提供 metax-operator-0.8.0.tgz 。

1.4.1. 推送容器镜像

通常，在Kubernetes集群网络环境内部需要部署容器仓库服务，以提升运行效率。假设容器仓库服务器域名为 DOMAIN ，用于存放沐曦Kubernetes组件镜像的项目名为 PROJECT 。 集群管理员需按照以下步骤完成镜像的推送：

  1. 安装Docker

    确认进行操作的主机已正确安装Docker并完成用户组配置，确认Docker命令可正常工作。 安装步骤参见 Docker官方文档 。

  2. 登录容器仓库，获得推送权限

    docker login DOMAIN -u $USER

  3. 推送容器镜像至仓库

    ./k8s/metax-k8s-images.0.8.0.run push DOMAIN/PROJECT

备注

在一些规模较小或验证性质的集群中，可能缺失容器仓库服务，管理员可将 metax-k8s-images.0.8.0.run 分发至集群的所有节点，并在所有节点上执行如下命令加载容器镜像。

./k8s/metax-k8s-images.0.8.0.run load

1.4.2. 推送Helm Chart

Helm是专为Kubernetes设计的包管理器，沐曦Kubernetes软件方案采用Helm Chart的形式发布，以提供最佳的部署体验。 沐曦提供OCI兼容的Helm Chart，因此可以选择将Helm Chart推送至容器镜像仓库以便后续使用。操作步骤如下：

  1. 安装Helm工具

    在Kubernetes的管理节点上安装Helm工具，可运行如下命令：

    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

    在一些受限的环境下，也可选择合适的方式进行安装，详情参见 Helm官方文档 。

    备注

    Helm版本要求 ≥ 3.0。

  2. 登录容器仓库，获取推送权限

    helm registry login DOMAIN -u $USER

  3. 推送Helm Chart至仓库

    helm push ./k8s/metax-gpu-extensions-0.8.0.tgz oci://DOMAIN/PROJECT
helm push ./k8s/metax-operator-0.8.0.tgz oci://DOMAIN/PROJECT

备注

在一些规模较小或验证性质的集群中，管理员可直接使用本地Helm Chart包进行Kubernetes组件安装，但需自行保管好Chart包以便后续运维使用。

1.4.3. MXMACA® 容器镜像

MXMACA® 容器镜像压缩包随 MXMACA® 软件栈的发布包发布，需另外获取。根据软件版本的不同，镜像及压缩包命名可能存在一些差异，应以实际获得的离线包为准。 用户也可通过商务途径获得授权后，通过 cr.metax-tech.com/library 容器镜像仓库获取容器镜像。

  • 2.23.0.x及之前版本

    在2.23.0的部分版本及之前版本的 MXMACA® 软件栈的发布包中，可找到文件名中包含 -container- 字段的压缩包。执行如下命令加载容器镜像：

    $ docker load < maca-c500-container-2.23.0.4-ubuntu18.04-amd64.xz
9a0ca4bf2bcb: Loading layer [=========================>]  46.79MB/46.79MB
134ccdd0eff6: Loading layer [=========================>]  5.095GB/5.095GB
41b261c7229d: Loading layer [=========================>]  27.65kB/27.65kB
Loaded image: cr.metax-tech.com/library/maca-c500:2.23.0.4-ubuntu18.04-amd64

    备注

    GPU产品与容器镜像命名之间的对应关系如下：

    MXN100

    maca-n100:<version>

    MXC500

    maca-c500:<version>

  • 2.23.0.x及之后版本

    在2.23.0的部分版本及之后版本的 MXMACA® 软件栈的发布包中，可找到扩展名为 .container.xz 的压缩包。执行如下命令加载容器镜像：

    $ docker load < mxc500-maca-2.23.0.4-ubuntu20.04-amd64.container.xz
2d4ccb11c2ef: Loading layer [=========================>]  9.728kB/9.728kB
a3e293fa8e05: Loading layer [=========================>]  1.111MB/1.111MB
c8c5c0b32bb0: Loading layer [=========================>]  15.53MB/15.53MB
447d0cf981f9: Loading layer [=========================>]  9.518GB/9.518GB
Loaded image: mxc500-maca:2.23.0.4-ubuntu20.04-amd64

1.4.4. 内核驱动容器镜像

沐曦在 GPU Operator 方案中提供云原生化的GPU内核态驱动解决方案。该方案提供一个独立的镜像包 driver-image，集成了多个主流Linux内核版本的内核态驱动以及配套的 mx-smi 工具，可自动加载内核态驱动，简化用户操作流程。使用含沐曦GPU的应用容器可以无缝运行GPU应用程序，无需额外安装驱动。

在2.24.0.x及之后版本中， driver-image 容器镜像作为一个独立资源包发布，用户可以通过软件中心获取名为 k8s-driver-image.$version-$arch.run 的文件。根据软件版本的不同，镜像及压缩包命名可能存在一些差异，应以实际获得的离线包为准。

用户可以推送镜像至容器镜像仓库、加载镜像至本地或执行其他相关操作。更多命令详情，在终端执行 k8s-driver-image.$version-$arch.run 查看帮助信息。

执行以下命令推送镜像：

$ REGISTRY="IMAGE REGISTRY"
$ chmod a+x k8s-driver-image.2.27.0.3-x86_64.run
$ ./k8s-driver-image.2.27.0.3-x86_64.run push $REGISTRY
Verifying archive integrity...100%MD5 checksums are OK. All good.
Uncompressing Metax Docker installer 2.27.0.3100%
Loaded image: cr.metax-tech.com/cloud/driver-image:2.27.0.3-amd64
The push refers to repository [$REGISTRY/driver-image]
44bdb21a562a: Pushed
91c2e74bd141: Pushed
d7a64635d9dd: Pushed
319b0faed61a: Pushed
d4fc045c9e3a: Pushed
2.27.0.3-amd64: digest: sha256:a1fe865850d555e5106835caac41b177e8f3cbfa3535c5e57ac2447cc0550f79 size: 1369
Created manifest list $REGISTRY/driver-image:2.27.0.3
sha256:52e1d09850b06bb72ef65ed63394f5d419a33408e0f872031b14781dba440ddd

1.4.5. 容器内使用 MXMACA® 环境要求

用户在基于 MXMACA® 进行实际作业过程中，需确保容器环境满足以下环境要求：

Debian系依赖项

Red Hat系依赖项

运行依赖

libltdl7

libtool-ltdl

libelf

elfutils-libelf

libnuma

numactl-libs

基于非 MXMACA® 容器镜像做应用镜像时，需安装SDK运行时依赖，示例Dockerfile如下：

  • 在 Debian 系发行版上，使用以下命令安装依赖：

    FROM ubuntu:18.04

RUN apt-get update && apt-get install -y \
libelf1  \
libltdl7 \
libnuma1 \
... \
&& rm -rf /var/lib/apt/lists/*

  • 在 Red Hat 系发行版上，使用以下命令安装依赖：

    FROM centos:8

RUN yum update && yum install -y \
elfutils-libelf \
libtool-ltdl \
numactl-libs \
... \
&& yum clean all

提示

基于 MXMACA® 容器镜像做应用镜像时，镜像已提供必要运行时依赖，无需额外安装。