# Moffett Container Toolkit 用户手册

## **概述**

MOFFETT Container Toolkit，即墨芯容器工具包，旨在用于帮助用户在容器中使用墨芯 AI 计算卡。MOFFETT Container Toolkit 通过生成容器设备接口 CDI （Container Device Interface） 的方式，自动配置容器以利用墨芯 AI 计算卡，并兼容了主流的容器运行时（如 Docker、containerd、Podman 等）。

## 前提条件

- 服务器已安装墨芯 AI 计算卡，且能被系统正确识别。
-  安装 SOLA ToolKit， 且 SOLA ToolKit 版本>= 3.11.0。
- 安装支持 CDI 特性的容器引擎，如 Docker（Docker >=  25.0.0）。

## **安装步骤**

### **下载 MOFFETT Container Toolkit**

**Debian/Ubuntu**

```bash
$ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/CloudNative/container-toolkit/moffett-container-toolkit_1.1.0_amd64.deb
```

**RHEL/CentOS/Rockey**

```bash
$ wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/CloudNative/container-toolkit/moffett-container-toolkit-1.1.0-1.x86_64.rpm
```

### **安装 MOFFETT Container Toolkit**

**Debian/Ubuntu**

执行以下命令：

```bash
$ sudo dpkg -i moffett-container-toolkit_1.1.0_amd64.deb
```

**RHEL/CentOS/Rockey**

执行以下命令：

```bash
$ sudo rpm -ivh moffett-container-toolkit-1.1.0-1.x86_64.rpm
```

### **确认安装结果**

安装后执行如下命令，返回版本信息即表示安装成功。

```bash
$ moffett-ctk --version
MOFFETT Container Toolkit CLI version 1.1.0
```

## **配置使用环境**

1. 启用 CDI 特性。

    MOFFETT Container Toolkit  需要使用 Docker CDI 特性，Docker 默认禁用 CDI 特性，

    您可通过设定默认配置文件（/etc/docker/daemon.json）中的 cdi-spec-dir 选项来启用 CDI。

    ```json
    {
      "features": {
         "cdi": true
      },
      "cdi-spec-dirs": ["/etc/cdi/", "/var/run/cdi"]
    }
    ```

2. 重启 Docker 服务，使配置生效。

    ```bash
    $ systemctl daemon-reload
    $ systemctl restart docker
    $ systemctl status docker
    ```

3. 确认 CDI 被启用。

    ```bash
    #返回 cdi 信息即代表启用成功
    $ docker info|grep -A 2 "CDI spec directories"
    ```

4. 生成 CDI 配置文件。

    ***说明**：您可通过 output 选项指定配置文件目录位置，默认路径为 /etc/cdi/moffett.yaml。*

    ```bash
    $ sudo moffett-ctk cdi generate --output=/etc/cdi/moffett.yaml
    ```

5. 查看可用的 CDI 设备。

    ```bash
    $ moffett-ctk cdi list
    ```

## 工作负载示例

安装和配置完成后，您可创建 Docker 容器运行一些简单的工作负载进行快速验证。示例如下：

- 使用所有设备
  创建容器并指定在容器中使用本机全部设备。 

  ```bash
  # 通过 all 参数项 指定所有的设备
  $ docker run --rm --device moffett.ai/spu=all ubuntu:22.04 mx-smi list
  ```

- 使用指定设备
  创建容器并指定在容器内需要使用的设备 ID， 同时设置相应的环境变量 SOLA_VISIBLE_DEVICES。

  ```bash
  # 查看本机可用的设备
  $ moffett-ctk cdi list
  # 创建容器时指定使用的设备
  $ docker run --rm --device moffett.ai/spu=1 --device moffett.ai/spu=2 ubuntu:22.04 mx-qual list
  ```

## 卸载 Moffett Container Toolkit

**Debian/Ubuntu**

```bash
$ dpkg -l moffett-container-toolkit
$ sudo dpkg -P moffett-container-toolkit
```

**RHEL/CentOS/Rockey**

```bash
$ rpm -qa moffett
$ sudo rpm -e moffett-container-toolkit
```