# MOFFETT Container Toolkit 用户手册

`moffett-ctk`（MOFFETT Container Toolkit）通过生成容器设备接口（Container Device Interface，CDI）规范文件，支持在容器环境中识别并使用搭载稀疏处理单元 SPU（Sparse Processing Unit）的墨芯计算卡。CDI 是一种面向容器运行时的开放规范文件，它抽象了对设备的访问方式，并实现了在不同容器运行时之间访问的标准化。

```{admonition} 须知
:class: note

本文介绍通过 Container Toolkit 生成 CDI 规范文件并在容器中使用 SPU 的操作。在 Kubernetes 集群中，通常由 SPU Operator 统一部署，无需单独安装；仅在需要单独管理组件时参照本手册操作，详见[《MOFFETT SPU Operator 用户手册》](./k8s-spu-operator.md)。
```

(mct-deploy)=
## 部署

### 前提条件

- 安装 SOLA Toolkit ≥ 3.11.0，详见 [《SOLA Toolkit 安装指南》](../installation/sola-toolkit-installation-guide.md)。
- 安装容器运行时，如 Docker、containerd 等；在容器运行时配置 CDI 的版本要求和操作详见 <a href="https://github.com/cncf-tags/container-device-interface?tab=readme-ov-file#how-to-configure-cdi" target="_blank">How to configure CDI</a>。

(mct-procedure)=
### 操作步骤

1. 获取 MOFFETT Container Toolkit 安装包。

   ````{tabs}

   ```{tab} Ubuntu/Debian
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/container-toolkit/moffett-container-toolkit_1.2.0_amd64.deb
   ```

   ```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.11/container-toolkit/moffett-container-toolkit-1.2.0-1.x86_64.rpm
   ```
   ````

2. 安装 MOFFETT Container Toolkit。

   ````{tabs}

   ```{tab} Ubuntu/Debian
   ```bash
   sudo dpkg -i moffett-container-toolkit_1.2.0_amd64.deb
   ```

   ```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
   ```bash
   sudo rpm -ivh moffett-container-toolkit-1.2.0-1.x86_64.rpm
   ```
   ````

3. （可选）查看 MOFFETT Container Toolkit 版本。

   ```bash
   moffett-ctk --version
   ```

(mct-generate-cdi)=
4. 生成 CDI 规范文件。

   ```{include} ../_includes/cdi-environment-change.inc
   ```

   ````{tabs}

   ```{tab} SOLA 驱动安装在主机上
   ```bash
   sudo moffett-ctk cdi generate --driver-root / --output=/etc/cdi/moffett.yaml
   ```

   ```{tab} SOLA 驱动通过 SPU Operator 容器镜像安装
   ```bash
   sudo moffett-ctk cdi generate --driver-root /run/moffett/driver --output=/etc/cdi/moffett.yaml
   ```
   ````

   --driver-root
   : SOLA 驱动挂载的根目录。

   --output
   : 保存 CDI 规范文件的路径，默认为 `/etc/cdi/moffett.yaml`。

   生成 CDI 规范文件后，可执行 `moffett-ctk cdi list` 命令查看 CDI 设备列表。

## 部署后验证

以下验证操作以 Docker 为例，使用 `ubuntu:22.04` 镜像。如果目标主机尚未准备该镜像，按以下方式获取；已有镜像时，直接执行设备验证。

```bash
docker pull ubuntu:22.04
```

镜像准备完成后，执行以下设备验证：

- 分别在主机和载入全部设备的新容器中执行 `mx-smi list` 命令。

  ```bash
  # 查看主机设备
  mx-smi list
  # 查看容器设备
  docker run --rm --device moffett.ai/spu=all ubuntu:22.04 mx-smi list
  ```

  确认主机已列出预期设备，再对照容器输出，确认设备数量及 PCI Bus ID 一致。

- （可选）载入指定设备执行 `mx-qual list` 命令。

  以下以设备 `1`、`2` 为例。执行前，通过 `moffett-ctk cdi list` 确认对应设备存在，并根据实际设备名称调整 `--device` 参数。

  ```bash
  docker run --rm --device moffett.ai/spu=1 --device moffett.ai/spu=2 ubuntu:22.04 mx-qual list
  ```

  对照主机上对应设备的 `mx-qual list` 输出，确认容器能够列出所选设备。

  ```{admonition} 须知
  :class: note

  `mx-smi list` 或 `mx-qual list` 命令返回的设备 Index 按 PCI Bus ID 从小到大排序。因此，在容器内和主机上执行该命令时，设备 Index 可能不同。
  ```

## 卸载

````{tabs}

```{tab} Ubuntu/Debian
```bash
sudo dpkg -P moffett-container-toolkit
```

```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
```bash
sudo rpm -e moffett-container-toolkit
```
````

## 故障处理

(mct-stale-cdi)=
### 运行容器工作负载时提示 SOLA 路径不存在

运行容器工作负载时可能出现类似以下错误：

```text
failed to fulfil mount request: open /usr/local/sola-<version>: no such file or directory
```

CDI 规范文件与当前主机环境不一致时，可能仍引用已不存在的 SOLA 安装路径。按以下步骤处理：

1. 检查当前 SOLA 安装路径和 CDI 规范文件中记录的路径。

   ```bash
   readlink -e /usr/local/sola
   sudo grep -n '/usr/local/sola' /etc/cdi/moffett.yaml
   ```

2. 根据 SOLA 驱动的安装方式，按照{ref}`生成 CDI 规范文件 <mct-generate-cdi>`中的步骤更新文件。已根据当前环境重新生成文件时，可跳过此步骤。

3. 使用 Docker 部署时，按照{ref}`验证容器设备访问 <mct-restart-docker>`中的步骤验证新容器，通过后恢复工作负载；异常时，参见{ref}`生成 CDI 规范文件 <mct-generate-cdi>`中的注意事项，并检查 Docker 日志中的 CDI 文件解析或设备冲突错误。