1. 版本申明¶

版本	修改内容	修改时间
v1.0	初始化	5/11/2023
v1.1	更新containerd与run包内容	1/15/2024
v1.2	更新一些格式与内容	4/8/2024
v1.3	更新一些格式	4/9/2024
v1.4	更新一些使用说明	5/21/2024
v1.5	更新安装说明	6/18/2024
v1.6	更新一些格式	6/24/2024

2. 简介¶

Enflame-container-toolkit 是一个容器扩展工具套件，通过这一工具套件使得燧原的GCU卡可以在docker、containerd等容器内使能。k8s-device-plugin 与enflame-container-toolkit组合使用以支撑Enflame GCU 在K8S系统内的资源调度，本文档主要描述enflame-container-toolkit的单独使用方式。

Enflame-container-toolkit依赖于以下三个条件:

Enflame Driver已经在OS里安装好，缺少这一步会找不到Enflame GCU加速卡；
Docker-ce 已经在OS里安装好；
用户: root, 或者 sudo [command] ，安装需要root权限。

3. container-toolkit安装包¶

在topscloud/container-toolkit安装包里涵盖以下几个文件，如下：

container-toolkit_${VERSION}/
├── config.toml.template
├── daemon.json.template
├── enflame-container-toolkit_${VERSION}_amd64.deb
├── enflame-container-toolkit_${VERSION}_x86_64.run
├── enflame-container-toolkit_${VERSION}_x86_64.rpm
├── install.sh
├── LICENSE.md
└── README.md

1） enflame-container-toolkit_${VERSION}_amd64.deb 是 ubuntu 系统安装包，安装命令：

dpkg -i enflame-container-toolkit_${VERSION}_amd64.deb

2）enflame-container-toolkit_${VERSION}_x86_64.rpm 是 tlinux ，centos，redhat系统安装包，安装命令：

rpm -ivh enflame-container-toolkit_${VERSION}_x86_64.rpm

3）enflame-container-toolkit_${VERSION}_x86_64.run 是linux run安装包，安装命令：

./enflame-container-toolkit_${VERSION}_x86_64.run

run包使用帮助如下：

Usage: ./enflame-container-toolkit.run [--install | --uninstall | --help | --x]
Command:
    --install     install the run file, as the default
    --uninstall   uninstall the run file
    --x           decompress the package
    --help        show help usage

4）daemon.json.template为 docker /etc/docker/daemon.json 配置模板，内容如下:

{
    "default-runtime": "enflame",
    "runtimes": {
        "enflame": {
            "path": "/usr/bin/enflame-container-runtime",
            "runtimeArgs": []
        }
    },

    "registry-mirrors": ["https://mirror.ccs.tencentyun.com", "https://docker.mirrors.ustc.edu.cn"],
    "insecure-registries": ["127.0.0.1/8"],
    "max-concurrent-downloads": 10,
    "log-driver": "json-file",
    "log-level": "warn",
    "log-opts": {
        "max-size": "10m",
        "max-file": "3"
    },
    "default-shm-size": "1G",
    "default-ulimits": {
         "memlock": { "name":"memlock", "soft":  -1, "hard": -1 },
         "stack"  : { "name":"stack", "soft": 67108864, "hard": 67108864 },
         "nofile": {"name": "nofile","soft": 65536, "hard": 65536}
    },
    "data-root": "/var/lib/docker"
}

可以根据自己的具体需求，更改daemon.json.template 的内容，然后copy到 /etc/docker下，这个配置文件会将docker的default-runtime 设置成enflame container runtime。需要注意的是考虑到安全问题，安装 enflame-container-toolkit 时，当OS 的 /etc/docker 下已经有 daemon.json 存在，则不会覆盖；

5） config.toml.template, containerd 配置文件；

6） install.sh，一键安装脚本, 执行 ./install.sh 会将enflame-container-toolkit自动安装到系统；

7） LICENSE.md ，版权说明;

8） README.md，readme 文件。

4. 安装container-toolkit¶

在topscloud_xxx内执行：

cd container-toolkit_<VERSION>
./install.sh

以上步骤会把enflame-container-toolkit 安装进系统，用户也可以根据自己的需要采用dpkg命令安装对应的deb包，采用rpm命令安装rpm包。

注：

1）这一步需要注意daemon.json 的内容要根据自己的实际情况按需修改，再安装进/etc/docker下，默认如果/etc/docker/daemon.json 已存在则不会覆盖；

2）这一步需要注意config.toml 的内容要根据自己的实际情况按需修改，再安装进/etc/containerd下，默认如果/etc/containerd/config.toml 已存在则不会覆盖；

3）要确保deamon.json 里 “default-runtime”: 为”enflame”，不然docker识别不了enflame GCU；

4）对应的logs目录为/var/log/enflame/，可以从这个目录下获取container-toolkit 的运行日志信息；

为了保留用户原有的容器配置信息，如果OS系统里本身已经存在 “/etc/docker/daemon.json” 与 “/etc/containerd/config.toml” 这两个文件，安装container-toolkit的过程中只会打印出一个提示，而不会强制覆盖这两个文件。因此，用户如果需要替换这两个文件，需要先备份或先将这两个文件挪出对应目录，再执行”./install.sh force”强制安装container-toolkit。

如果需要修改这两个文件，则需要在修改后需要重启docker与containerd服务生效, 如下：

# 如果修改了 lib/systemd/system/docker.service
# 或 /lib/systemd/system/containerd.service
systemctl daemon-reload
# 修改了/etc/docker/daemon.json，也需要重启docker
systemctl restart docker
# 修改了/etc/containerd/config.toml，也需要重启containerd
systemctl restart containerd

5. 环境变量¶

enflame-container-toolkit 采用 ENFLAME_VISIBLE_DEVICES 这个环境变量挂载GCUs进容器内。

5.1. 这个变量支持的值¶

0,1,2, GCU-0,GCU-1,GCU-2 …: 采用逗号, 分割.
all: 默认值，挂载所有的GCUs设备进容器内.
none: 全部不挂载
void 为空或未设置，这时 enflame-container-runtime 等同 runc.

5.2. GCU挂载用例¶

直接docker挂载用例如下：

### all gcus
docker run -it --network host -e ENFLAME_VISIBLE_DEVICES=all enflame/enflame:latest /bin/bash

### gcu 0,1,2
docker run -it --network host -e ENFLAME_VISIBLE_DEVICES=0,1,2 enflame/enflame:latest /bin/bash

### gcu 0
docker run -it --network host -e ENFLAME_VISIBLE_DEVICES=0 enflame/enflame:latest /bin/bash

### enflame runtime
docker run -it --network host --runtime enflame  enflame/enflame:latest /bin/bash

### enflame-docker
enflame-docker run  -it --network host enflame/enflame:latest /bin/bash

6. 配置文件与日志¶

1）配置文件路径：/etc/enflame-container-runtime/config.toml，内容如下：

.deb包配置:

[enflame-container-cli]
debug = "/var/log/enflame/enflame-container-runtime-hook.log"
environment = []

ldconfig = "@/sbin/ldconfig.real"

[enflame-container-runtime]
# debug = "/var/log/enflame/enflame-container-runtime.log"

.rpm 与 .run包配置:

[enflame-container-cli]
debug = "/var/log/enflame/enflame-container-runtime-hook.log"
environment = []

ldconfig = "@/sbin/ldconfig"

[enflame-container-runtime]
# debug = "/var/log/enflame/enflame-container-runtime.log"

2）日志路径：/var/log/enflame

7. 查看工具版本号¶

container-toolkit包含三个可执行组件

1）enflame-container-runtime –version，可查看enflame-container-runtime组件对应的版本号；

2）enflame-container-runtime-hook –version，可查看enflame-container-runtime-hook组件对应的版本号；

3）enflame-container-cli –version, 可查看enflame-container-cli组件对应的版本号。

8. 常见问题¶

1）最低runc版本是什么？

建议的 runc 最低版本为 1.0.0-rc10。

2）如果是直接调用containerd的场景，比如使用k8s 1.24以上版本，containerd应该如何配置？

安装container-toolkit软件包后，如果之前没有配置过containerd，会新生成一份containerd配置，
如果之前存在containerd配置，则会在/etc/containerd/下生成一份template模板config.toml.template，用户可以参考该模板去配置enflame runtime。

3）如果使用ctr命令行映射gcu设备，发现在非特权模式下gcu设备没有成功映射，该如何解决？

需要在ctr run命令后加上”–runc-binary /usr/bin/enflame-container-runtime” 来指定enflame runtime的路径，就可以正常映射gcu设备。

4）如何配置k8s 1.24以上镜像源？

以内网为例，在/etc/containerd/config.toml中加入如下配置：

[plugins."io.containerd.grpc.v1.cri".registry]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
        [plugins."io.containerd.grpc.v1.cri".registry.mirrors."artifact.enflame.cn"]
            endpoint = ["http://artifact.enflame.cn"]
    [plugins."io.containerd.grpc.v1.cri".registry.configs]
        [plugins."io.containerd.grpc.v1.cri".registry.configs."artifact.enflame.cn".tls]
            insecure_skip_verify = true
    [plugins."io.containerd.grpc.v1.cri".registry.configs."artifact.enflame.cn".auth]
        username = ""
        password = ""

该配置规定了镜像源的网络资源地址，是否走TLS协议以及是否需要用户名密码。

5）如何处理用ctr创建的容器efsmi不能正常工作？

由于使用ctr创建容器时，systemd服务未能对容器根目录进行初始化，导致/var/lock目录指向的/run/lock缺失，而efsmi启动时会在/var/lock目录下创建初始化相关文件，如果目录不存在，则会启动失败。

发生问题时错误log如下：

-----------------------------------------------------------------------
----------------- Enflame System Management Interface -----------------
-------- Enflame Tech, All Rights Reserved. 2023 Copyright (C) --------
-----------------------------------------------------------------------

Failed to create lock /var/lock/efml_init
Please check to make sure the folder '/var/lock/' exists and is readable and writable
warn: Unknow Exception failed to create lock /var/lock/efml_init

只要执行如下命令，就可以解决上述问题：

mkdir /run/lock

再次执行efsmi，执行结果如下：

-----------------------------------------------------------------------
----------------- Enflame System Management Interface -----------------
-------- Enflame Tech, All Rights Reserved. 2023 Copyright (C) --------
-----------------------------------------------------------------------

*Tue Jan 30 10:26:32 2024-------------------------------------------------*
*EFSMI    V1.23.0          Driver Ver: 2.5.20231213                       *
*-------------------------------------------------------------------------*
*-------------------------------------------------------------------------*
* DEV    NAME                | FW VER          | BUS-ID     ECC           *
* TEMP   DPM   Pwr(Usage/Cap)| Mem         vGCU| DEV-Util   UUID          *
*-------------------------------------------------------------------------*
* 0      T20                 | 10.19.2         | 00:01:0.0  Enable        *
* 31C    80      52.0W  300W | 32G      Disable|   0.0%     V49000150602  *
*-------------------------------------------------------------------------*

如此efsmi就可以正常工作。

6）如何调试k8s 找不到设备得情况？基本调试策略如下：

kubectl logs 与 kubectl describe po 获取k8s-device-plugin的运行日志；
查看 /var/log/enflame 下的 container-toolkit 运行日志；
查看 /etc/docker/daemon.json 与 /etc/containerd/config.toml 配置是否正确；
mount | grep cgroup 查看用的哪个版本的 cgroup

7）修改了docker.service或containerd.service

如果修改了docker.service或containerd.service，需要执行”systemctl daemon-reload”后再重启相关服务。如下：

# 如果修改了 lib/systemd/system/docker.service
# 或 /lib/systemd/system/containerd.service
systemctl daemon-reload
# 修改了/etc/docker/daemon.json，也需要重启docker
systemctl restart docker
# 修改了/etc/containerd/config.toml，也需要重启containerd
systemctl restart containerd