# MOFFETT Container Toolkit 用户手册

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

## 部署

### 前提条件

- 安装 SOLA Toolkit ≥ 3.11.0，具体请参见 [SOLA Toolkit 安装指南](../installation/sola-toolkit-installation-guide.md)。
- 安装容器运行时，如 Docker、containerd 等。
- 容器运行时配置启用 CDI。如使用 Docker，版本需 ≥ 25.0.0，启用 CDI 配置方法请参见 <a href="https://github.com/cncf-tags/container-device-interface?tab=readme-ov-file#docker-configuration" target="_blank">Docker configuration</a>。

### 操作步骤

1. 获取 MOFFETT Container Toolkit 安装包。

   ````{tabs}

   ```{tab} Ubuntu/Debian
   ```Bash
   wget https://moffett-release.tos-cn-guangzhou.volces.com/macs/macs-v1.10/container-toolkit/moffett-container-toolkit_1.2.0_amd64.deb
   ```

   ```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler
   ```Bash
   wget https://moffett-release.tos-cn-guangzhou.volces.com/macs/macs-v1.10/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
   ```Bash
   sudo rpm -ivh moffett-container-toolkit-1.2.0-1.x86_64.rpm
   ```
   ````

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

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

4. 根据 SOLA 驱动的安装方式生成 CDI 规范文件。

   ```{admonition} 注意
   :class: caution

   SOLA Toolkit 版本变更后，必须再次执行以下命令生成新的 CDI 规范文件。
   ```

   ````{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 设备列表。

## 部署后验证

以下示例基于 Ubuntu 22.04 容器镜像使用 MOFFETT Container Toolkit 载入墨芯设备：

- 载入全部设备执行 `mx-smi list` 命令。

  ```Bash
  docker run --rm --device moffett.ai/spu=all ubuntu:22.04 mx-smi list
  ```

  以上命令的输出与在主机上直接运行 `mx-smi` 命令相同。

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

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

  以上命令的输出与在主机中运行 `mx-qual list -i 1 2` 命令的结果相对应。

  ```{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
```Bash
sudo rpm -e moffett-container-toolkit
```
````