5. 支持

5.1. 资源获取

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

5.1.1. 文档获取

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

访问沐曦开发者社区
在顶部导航栏选择「文档」
在左侧菜单中选择「如k8s系列文档」
选择所需版本（如「0.11.1」）
查看文档：
- 点击文档卡片在线预览
- 鼠标悬停卡片显示下载按钮
- 或在预览界面点击下载按钮

5.1.2. 软件获取

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

访问沐曦开发者社区
在顶部导航栏选择「下载」
查找资源：
- 搜索框输入关键词（如「Cloud云平台工具包」）
- 或按分类浏览
下载资源：
- 最新版：点击「立即下载」
- 历史版本：点击资源包右侧「版本历史」

备注

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

5.2. 驱动资源详解

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

5.2.1. 内核驱动镜像

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

包含的资源:
- 预编译内核模块：镜像内集成了为多个主流 Linux 发行版和内核版本预编译好的沐曦 GPU 内核驱动模块。
- 管理工具 mx-smi: 提供了功能强大的命令行工具，用于查询和监控 GPU 的状态、功耗、温度、显存使用率等关键指标。
命名规则与版本:
- 独立发布方案在 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 进行计算所需的全部软件库和依赖。

包含的资源:
- MXMACA^® 运行时库: 包含了应用在用户空间调用 GPU 时所需的全部共享库（.so 文件），这些库负责与内核驱动通信、管理计算任务、分配显存等。
- 系统核心依赖: 预装了运行 MXMACA^® 库所必需的系统基础依赖包，如 libelf、libltdl、libnuma 等，从而简化了应用镜像的构建过程。
命名规则与版本:

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. 运行时配置http的registry (以Harbor为例)

5.3.1. docker配置http私有Harbor

Harbor 是可选的支持 HTTP 连接，但是 Docker 客户端始终尝试首先使用 HTTPS 连接到注册表。如果 Harbor 配置为 HTTP，则必须配置 Docker 客户端，使其可以连接到不安全的注册表。

将选项 --insecure-registry 添加到客户端的 Docker daemon。默认情况下，daemon 文件位于 /etc/docker/daemon.json。

例如，将以下内容添加到 daemon.json 文件中：

{
"insecure-registries" : ["myregistrydomain.com:5000", "192.168.11.20:80"]
}

更新 daemon.json 后，必须重启 Docker Engine：

systemctl restart docker

5.3.2. containerd配置http私有Harbor

首先需要在containerd配置文件目录下创建私有仓库域名端口或IP端口的文件夹，并创建 hosts.toml，将相关配置写入文件（假设私有的http的Harbor仓库IP端口为 192.168.11.20:80）：

mkdir -p /etc/containerd/certs.d/192.168.11.20:80

tee /etc/containerd/certs.d/192.168.11.20:80/hosts.toml << 'EOF'
server = "http://192.168.11.20:80"

[host."http://192.168.11.20:80"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true
EOF

systemctl restart containerd.service

修改 config.toml**（默认在 **/etc/containerd/config.toml）：

containerd 2.x

version = 3

[plugins."io.containerd.cri.v1.images".registry]
   config_path = "/etc/containerd/certs.d"

containerd 1.x

version = 2

[plugins."io.containerd.grpc.v1.cri".registry]
   config_path = "/etc/containerd/certs.d"

5.4. run文件的使用方式详解

run文件支持使用多种容器运行时工具进行镜像的push/load，如docker、nerdctl以及ctr，以及将组件的镜像包dump到本地。并且run文件支持原生工具push参数的透传（0.14.0版本开始支持）。

使用run文件将镜像dump到主机

# 将镜像dump到当前目录
metax-k8s-images.0.14.0.run dump

使用run文件将镜像load到主机

# 默认使用docker进行镜像加载
metax-k8s-images.0.14.0.run load
# 显示使用docker进行镜像加载
metax-k8s-images.0.14.0.run docker load
# 使用nerdctl进行镜像加载
metax-k8s-images.0.14.0.run nerdctl load
# 使用ctr进行镜像加载
metax-k8s-images.0.14.0.run ctr load

使用run文件将镜像push到远程仓库

# REGISTRY一般为<DOMAIN>/<PROJECT>
REGISTRY="IMAGE REGISTRY"
# 默认使用docker进行镜像推送
metax-k8s-images.0.14.0.run push $REGISTRY
# 显示使用docker进行镜像推送
metax-k8s-images.0.14.0.run docker push $REGISTRY
# 使用nerdctl进行镜像推送
metax-k8s-images.0.14.0.run nerdctl push $REGISTRY
# 使用ctr进行镜像推送
metax-k8s-images.0.14.0.run ctr push $REGISTRY

支持原生工具push参数的透传，可通过运行 docker push --help， nerdctl push --help 以及 ctr image push --help 查看原生push命令支持的参数，在使用run文件时添加参数即可。例如：

# 使用ctr进行镜像推送 并跳过SSL认证
metax-k8s-images.0.14.0.run ctr push $REGISTRY -- --skip-verfy
# 使用ctr进行镜像推送 显示注册远程仓库的用户名密码
metax-k8s-images.0.14.0.run ctr push $REGISTRY -- --user "user:password"

5.5. http网络协议的registry下使用run文件进行镜像push

首先需进行运行时配置http的registry，配置方式见 5.3 运行时配置http的registry (以Harbor为例)

使用run文件进行镜像push

使用docker进行镜像push

# REGISTRY一般为<DOMAIN>/<PROJECT>
REGISTRY="IMAGE REGISTRY"
# 默认使用docker进行镜像推送
metax-k8s-images.0.14.0.run push $REGISTRY
# 显示使用docker进行镜像推送
metax-k8s-images.0.14.0.run docker push $REGISTRY

使用nerdctl进行镜像push

# 使用nerdctl进行镜像推送
metax-k8s-images.0.14.0.run nerdctl push $REGISTRY -- --insecure-registry

使用ctr进行镜像push

# 使用ctr进行镜像推送
metax-k8s-images.0.14.0.run ctr push $REGISTRY -- --plain-http

5.6. 常见问题

5.6.1. 卸载异常处理

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

5.6.1.1. 异常场景说明

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

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

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

5.6.1.2. 手动清理步骤

删除残留的验证 Webhook 配置

验证 Webhook 用于在资源创建/更新时执行合法性检查，若卸载时未正确移除，可能影响其他组件运行。
```
kubectl delete validatingwebhookconfiguration upgrade-validating-webhook-configuration \
  --ignore-not-found  # 忽略“资源不存在”错误（避免无该资源时报错）
  --grace-period=60   # 等待 60 秒让资源优雅终止（可选，根据集群负载调整）
```
- 作用：强制删除名为 upgrade-validating-webhook-configuration 的验证 Webhook，解除对资源操作的阻断
- 注意：--ignore-not-found 确保命令在无残留时仍正常执行，避免误操作中断流程
移除 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.6.1.3. 后续验证

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

确认 Webhook 已删除：

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

检查 ClusterOperator 状态：

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

重新执行卸载命令：

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

5.6.1.4. 注意事项

谨慎操作：手动清理涉及集群核心资源，建议先备份集群状态或联系技术支持确认操作风险。
依赖清理：执行前需确保所有依赖 GPU Operator 的业务 Pod 已停止，避免删除过程中出现资源竞争。
版本适配：不同版本的 Operator 可能对应不同的 Webhook 或 ClusterOperator 名称，若命令执行失败，需核对实际资源名称（可通过 kubectl get all -n metax-operator 查看）。