5. 支持

5.1. 资源获取

沐曦开发者社区汇集了完整的技术资源，包括技术文档、软件工具包等。您可以通过以下方式获取所需资源。

5.1.1. 文档获取

沐曦开发者社区提供完整的技术文档资源，包括云原生参考手册、API文档等。获取流程如下：

  1. 访问 沐曦开发者社区

  2. 在顶部导航栏选择「文档」

  3. 在左侧菜单中选择「如k8s系列文档」

  4. 选择所需版本（如「0.11.1」）

  5. 查看文档：

    • 点击文档卡片在线预览

    • 鼠标悬停卡片显示下载按钮

    • 或在预览界面点击下载按钮

5.1.2. 软件获取

沐曦提供完整的云平台工具链和软件资源包。获取流程如下：

  1. 访问 沐曦开发者社区

  2. 在顶部导航栏选择「下载」

  3. 查找资源：

    • 搜索框输入关键词（如「Cloud云平台工具包」）

    • 或按分类浏览

  4. 下载资源：

    • 最新版：点击「立即下载」

    • 历史版本：点击资源包右侧「版本历史」

备注

下载文档和软件需要登录开发者社区账号，建议使用Chrome或Firefox等现代浏览器以获得最佳体验。

5.2. 驱动资源详解

在 GPU Operator 解决方案中，为了实现云原生环境下的高效部署与管理，GPU 驱动被解耦为两个核心的容器镜像资源，它们各自承载了不同的功能组件，共同构成了完整的 GPU 驱动环境。

5.2.1. 内核驱动镜像

此镜像是一个包含了内核态驱动相关组件的资源包。它为宿主机提供在内核层面驱动沐曦 GPU 硬件所需的核心文件。

  1. 包含的资源:

    • 预编译内核模块：镜像内集成了为多个主流 Linux 发行版和内核版本预编译好的沐曦 GPU 内核驱动模块。

    • 管理工具 mx-smi: 提供了功能强大的命令行工具，用于查询和监控 GPU 的状态、功耗、温度、显存使用率等关键指标。

  2. 命名规则与版本:

    • 独立发布方案在 2.24.0.x 版本及之后被正式采用。

    • 以 .run 包形式发布，文件名通常为 metax-k8s-driver-image.$version-$arch.run。

    • 加载后的镜像名通常为 cr.metax-tech.com/cloud/driver-image:<VERSION>-<ARCH>。

5.2.2. MXMACA® 容器镜像

此镜像是一个包含了用户态运行环境的资源包。它为最终运行的应用程序提供调用 GPU 进行计算所需的全部软件库和依赖。

  1. 包含的资源:

    • MXMACA® 运行时库: 包含了应用在用户空间调用 GPU 时所需的全部共享库（.so 文件），这些库负责与内核驱动通信、管理计算任务、分配显存等。

    • 系统核心依赖: 预装了运行 MXMACA® 库所必需的系统基础依赖包，如 libelf、libltdl、libnuma 等，从而简化了应用镜像的构建过程。

  2. 命名规则与版本:

    MXMACA® 容器镜像随 MXMACA® 资源包发布，其离线包的命名规则在不同版本间存在差异，用户在使用时请确认加载的镜像名，这对于识别和使用正确的资源至关重要。

    • 离线压缩包的文件名中通常包含 container 字段，例如 maca-native-<VERSION>-<DISTRO>-<ARCH>.container.xz。

    • 加载后的镜像名通常为 cr.metax-tech.com/library/maca-native:<VERSION>-<DISTRO>-<ARCH>。

    备注

    镜像的名称通常也与具体的 GPU 产品型号相关联。在构建镜像时请务必注意选择与硬件匹配的版本。

    MXN100

    maca-n100:<version>

    MXC500

    maca-c500:<version>

    MXC500/MXC600

    maca-native:<version>

5.3. 常见问题

5.3.1. 卸载异常处理

若在卸载 GPU Operator 过程中遇到资源删除失败、Finalizer 锁死等异常情况，可通过以下手动干预步骤强制清理残留资源，确保集群状态正常。

5.3.1.1. 异常场景说明

当卸载命令（如 helm uninstall）卡住或提示资源被占用时，可能是由于以下原因导致：

  • Webhook 配置残留：验证 Webhook 未被正确删除，导致后续资源操作被阻断

  • Finalizer 锁死：ClusterOperator 资源的 Finalizer 未移除，阻止元数据删除

5.3.1.2. 手动清理步骤

  1. 删除残留的验证 Webhook 配置

    验证 Webhook 用于在资源创建/更新时执行合法性检查，若卸载时未正确移除，可能影响其他组件运行。

    kubectl delete validatingwebhookconfiguration upgrade-validating-webhook-configuration \
  --ignore-not-found  # 忽略“资源不存在”错误（避免无该资源时报错）
  --grace-period=60   # 等待 60 秒让资源优雅终止（可选，根据集群负载调整）

    • 作用：强制删除名为 upgrade-validating-webhook-configuration 的验证 Webhook，解除对资源操作的阻断

    • 注意：--ignore-not-found 确保命令在无残留时仍正常执行，避免误操作中断流程

  2. 移除 ClusterOperator 的 Finalizer 锁

    Finalizer 是 Kubernetes 用于确保资源依赖被正确清理的机制，若卸载时未完成依赖清理，需手动移除锁标记。

    kubectl patch ClusterOperator/cluster-operator \
  --type json \
  --patch='[{"op":"remove", "path":"/metadata/finalizers"}]'

    • 作用：从 ClusterOperator 资源的元数据中移除 Finalizer，允许 Kubernetes 直接删除该资源，避免无限期锁死

    • 原理：Finalizer 会阻塞资源删除，直到所有依赖（如 CRD、Pods）被清理完毕。若依赖已手动清除，可强制移除 Finalizer 以继续卸载

5.3.1.3. 后续验证

完成上述步骤后，建议执行以下检查确保异常已解决：

  1. 确认 Webhook 已删除：

    kubectl get validatingwebhookconfiguration | grep upgrade-validating-webhook-configuration
# 若输出为空，说明已成功删除

  2. 检查 ClusterOperator 状态：

    kubectl get clusteroperators.gpu.metax-tech.com cluster-operator -o json | grep finalizers
# 确保 "finalizers" 字段不存在或为空数组

  3. 重新执行卸载命令：

    helm uninstall [RELEASE_NAME] -n metax-operator --wait # 替换为实际的 Helm 版本名称

5.3.1.4. 注意事项

  1. 谨慎操作：手动清理涉及集群核心资源，建议先备份集群状态或联系技术支持确认操作风险。

  2. 依赖清理：执行前需确保所有依赖 GPU Operator 的业务 Pod 已停止，避免删除过程中出现资源竞争。

  3. 版本适配：不同版本的 Operator 可能对应不同的 Webhook 或 ClusterOperator 名称，若命令执行失败，需核对实际资源名称（可通过 kubectl get all -n metax-operator 查看）。