NPU Exporter

使用约束

在安装NPU Exporter前，需要提前了解相关约束，具体说明请参见表1。

表1 约束说明

约束场景

约束说明

NPU驱动

NPU Exporter会周期性调用NPU驱动的相关接口以检测NPU状态。如果要升级驱动，请先停止业务任务，再停止NPU Exporter容器服务。

K8s版本

使用NPU Exporter前需要确保环境的K8s版本，若K8s版本在1.24.x及以上版本，需要用户自行安装cri-dockerd依赖。

DCMI动态库

DCMI动态库目录权限要求如下：

NPU Exporter调用的DCMI动态库其所有父目录，需要满足属主为root，其他属主程序无法运行；同时，这些文件及其目录需满足group和other不具备写权限。

DCMI动态库路径深度必须小于20。

如果通过设置LD_LIBRARY_PATH设置动态库路径，LD_LIBRARY_PATH环境变量总长度不能超过1024。

Atlas 200I SoC A1 核心板

Atlas 200I SoC A1 核心板使用NPU Exporter组件，需要确保Atlas 200I SoC A1 核心板的NPU驱动在23.0.RC2及以上版本。升级NPU驱动可参考《Atlas 200I SoC A1 核心板 25.0.RC1 NPU驱动和固件升级指导书》中“升级驱动”章节进行操作。

Atlas 200I SoC A1 核心板节点上使用容器化部署NPU Exporter，需要配置多容器共享模式，具体请参考《Atlas 200I SoC A1 核心板 25.0.RC1 NPU驱动和固件安装指南》中“容器内运行”章节。

虚拟机场景

如果在虚拟机场景下部署NPU Exporter，需要在NPU Exporter的镜像中安装systemd，推荐在Dockerfile中加入RUN apt-get update && apt-get install -y systemd命令进行安装。

操作步骤

NPU Exporter支持两种安装方式，用户可根据实际情况选择其中一种进行安装。该组件仅提供HTTP服务，如需使用更为安全的HTTPS服务，请自行修改源码进行适配。

容器化方式运行

  1. 以root用户登录各计算节点，并执行以下命令，查看NPU Exporter镜像和版本号是否正确。

    • Docker场景：执行如下命令。
      docker images | grep npu-exporter
      回显示例如下。
      1
      npu-exporter                         v7.0.RC1              20185c45f1bc        About an hour ago         90.1MB
    • Containerd场景：执行如下命令。
      ctr -n k8s.io c ls | grep npu-exporter

      回显示例如下。

      docker.io/library/npu-exporter:v7.0.RC1                                                         application/vnd.docker.distribution.manifest.v2+json      sha256:38fd69ee9f5753e73a55a216d039f6ed4ea8a5de15c0e6b3bb503022db470c7b 91.5 MiB  linux/arm64

  2. 将NPU Exporter软件包解压目录下的YAML文件，拷贝到K8s管理节点上任意目录。
  3. 请根据实际使用的容器化方式，选择执行以下步骤。

    • Containerd场景：需要将containerMode设置为containerd，并对以下加粗的代码进行修改。

    如果使用默认的NPU Exporter启动参数“-containerMode=docker”时，可跳过本步骤。

    apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: npu-exporter
  namespace: npu-exporter
spec:
  selector:
    matchLabels:
      app: npu-exporter
...
    spec:
...
      args: [ "umask 027;npu-exporter -port=8082 -ip=0.0.0.0  -updateTime=5
                 -logFile=/var/log/mindx-dl/npu-exporter/npu-exporter.log -logLevel=0 -containerMode=containerd" ]
...
      volumeMounts:
...
        - name: docker-shim                                       
          mountPath: /var/run/dockershim.sock
          readOnly: true
        - name: docker                                       # 仅使用containerd时删除
          mountPath: /var/run/docker
          readOnly: true
        - name: cri-dockerd                                 
          mountPath: /var/run/cri-dockerd.sock
          readOnly: true
        - name: containerd                             
          mountPath: /run/containerd
          readOnly: true
        - name: isulad                                
          mountPath: /run/isulad.sock
          readOnly: true
...
      volumes:
...
        - name: docker-shim                             
          hostPath:
            path: /var/run/dockershim.sock
        - name: docker                                # 仅使用containerd时删除
          hostPath:
            path: /var/run/docker
        - name: cri-dockerd                           
          hostPath:
            path: /var/run/cri-dockerd.sock
        - name: containerd                            
          hostPath:
            path: /run/containerd
        - name: isulad                               
          hostPath:
            path: /run/isulad.sock

...
    • Docker场景：删除原有容器运行时的挂载文件，新增dockershim.sock文件的挂载目录，并对以下加粗的代码进行修改。
    如果使用的NPU Exporter启动参数“-containerMode=containerd”，可跳过本步骤。

    该步骤可有效解决kubelet重启后，造成的NPU-Exporter数据丢失问题。新增挂载目录后，会同时新增很多挂载文件，如docker.sock，有容器逃逸的风险。

    ...
        volumeMounts:
          - name: log-npu-exporter
...
          - name: sys
            mountPath: /sys
            readOnly: true
          - name: docker-shim                        # 删除以下加粗字段
            mountPath: /var/run/dockershim.sock
            readOnly: true
          - name: docker 
            mountPath: /var/run/docker
            readOnly: true
          - name: cri-dockerd 
            mountPath: /var/run/cri-dockerd.sock
            readOnly: true
          - name: sock                   # 新增以下加粗字段
            mountPath: /var/run        # 以实际的dockershim.sock文件目录为准
          - name: containerd  
            mountPath: /run/containerd
...
      volumes:
        - name: log-npu-exporter
...
        - name: sys
          hostPath:
            path: /sys
        - name: docker-shim                    # 删除以下加粗字段
          hostPath:   
            path: /var/run/dockershim.sock
        - name: docker 
          hostPath:
            path: /var/run/docker
        - name: cri-dockerd 
          hostPath:
            path: /var/run/cri-dockerd.sock
        - name: sock                 # 新增以下加粗字段
          hostPath:
            path: /var/run                    # 以实际的dockershim.sock文件目录为准
        - name: containerd  
          hostPath:
            path: /run/containerd
 ...

  4. 如不修改组件的其他启动参数，可跳过本步骤。否则，请根据实际情况修改YAML文件中NPU Exporter的启动参数。启动参数如表2所示，也可执行./npu-exporter -h查看参数说明。
  5. 在管理节点的YAML所在路径，执行以下命令，启动NPU Exporter。如果集群中同时存在Atlas 200I SoC A1 核心板和其他类型的节点，请分别执行对应命令。

    • K8s集群中使用Atlas 200I SoC A1 核心板节点，执行以下命令。
      kubectl apply -f npu-exporter-310P-1usoc-v{version}.yaml
    • K8s集群中使用除Atlas 200I SoC A1 核心板外的其他类型节点，执行以下命令。
      kubectl apply -f npu-exporter-v{version}.yaml
    启动示例如下：
    namespace/npu-exporter unchanged
networkpolicy.networking.K8s.io/exporter-network-policy unchanged
daemonset.apps/npu-exporter created

  6. 在任意节点执行以下命令，查看组件是否启动成功。

    kubectl get pod -n npu-exporter

    回显示例如下，出现Running表示组件启动成功。若状态为CrashLoopBackOff，可能是因为目录权限不正确导致，可以参见NPU Exporter检查动态路径失败，日志出现check uid or mode failed章节进行处理。

    1
2
3
    NAME                            READY   STATUS    RESTARTS   AGE
...
npu-exporter-hqpxl        1/1    Running   0        11s

二进制方式运行

NPU Exporter组件以容器化方式运行时需使用特权容器、root用户和挂载了docker-shim或Containerd的socket文件，如果容器被人恶意利用，有容器逃逸风险。当安全性要求较高时，请直接在物理机上通过二进制方式运行。

以二进制方式运行NPU Exporter需要将日志目录权限修改为非root，可以执行chown hwMindX:hwMindX /var/log/mindx-dl/npu-exporter命令修改日志权限。

  1. 使用root用户登录服务器。
  2. 将软件包上传至服务器的任意目录（如“/home/ascend-npu-exporter”）并进行解压操作。
  3. 创建并编辑npu-exporter.service文件。

    1. 执行以下命令，创建npu-exporter.service文件。
      vi /home/ascend-npu-exporter/npu-exporter.service

    2. 参考如下内容，写入npu-exporter.service文件中。

      [Unit]
Description=Ascend npu exporter
Documentation=hiascend.com

[Service]
ExecStart=/bin/bash -c "/usr/local/bin/npu-exporter -ip=127.0.0.1 -port=8082 -logFile=/var/log/mindx-dl/npu-exporter/npu-exporter.log>/dev/null  2>&1 &"
Restart=always
RestartSec=2
KillMode=process
Environment="GOGC=50"
Environment="GOMAXPROCS=2"
Environment="GODEBUG=madvdontneed=1"
Type=forking
User=hwMindX
Group=hwMindX

[Install]
WantedBy=multi-user.target
    3. 按“Esc”键，输入:wq!保存并退出。

  4. 创建并编辑npu-exporter.timer文件。通过配置timer延时启动，可保证NPU Exporter启动时NPU卡已就位。

    1. 执行以下命令，创建npu-exporter.timer文件。
       vi /home/ascend-npu-exporter/npu-exporter.timer
    2. 参考以下示例，并将其写入npu-exporter.timer文件中。
      [Unit]
Description=Timer for NPU Exporter Service

[Timer]
OnBootSec=60s            # 设置NPU Exporter延时启动时间，请根据实际情况调整
Unit=npu-exporter.service

[Install]
WantedBy=timers.target
    3. 按“Esc”键，输入:wq!保存并退出。

  5. NPU Exporter默认情况只侦听127.0.0.1，可通过修改的启动参数“-ip”和“npu-exporter.service”文件的“ExecStart”字段修改需要侦听的IP地址。

    ...
[Service]
ExecStart=/bin/bash -c "/usr/local/bin/npu-exporter -ip=127.0.0.1 -port=8082 -logFile=/var/log/mindx-dl/npu-exporter/npu-exporter.log &"
Restart=always
RestartSec=2
...

  6. 依次执行以下命令，在节点上将hwMindX用户加入到HwBaseUser、HwDmUser用户组中。如果部署节点为Atlas 200I SoC A1 核心板，可跳过该步骤。

    usermod -a -G HwBaseUser hwMindX
usermod -a -G HwDmUser hwMindX

  7. 依次执行以下命令，启用NPU Exporter服务。

    cd /home/ascend-npu-exporter
cp npu-exporter /usr/local/bin
cp npu-exporter.service /etc/systemd/system
chattr +i /etc/systemd/system/npu-exporter.service
cp npu-exporter.timer /etc/systemd/system     
chattr +i /etc/systemd/system/npu-exporter.timer      
chmod 500 /usr/local/bin/npu-exporter
chown hwMindX:hwMindX /usr/local/bin/npu-exporter
chattr +i /usr/local/bin/npu-exporter
systemctl enable npu-exporter.timer 
systemctl start npu-exporter
systemctl start npu-exporter.timer
    如果需要获取容器相关数据信息，NPU Exporter需要临时提权以便于和CRI、OCI的socket建立连接，需要执行以下命令。
    chattr -i /usr/local/bin/npu-exporter
setcap cap_setuid+ep /usr/local/bin/npu-exporter
chattr +i /usr/local/bin/npu-exporter
systemctl restart npu-exporter

参数说明

表2 NPU Exporter启动参数

参数

类型

默认值

说明

-port

int

8082

侦听端口，取值范围为1025~40000。

-updateTime

int

5

信息更新周期1~60秒。如果设置的时间过长，一些生存时间小于更新周期的容器可能无法上报。

-ip

string

无

参数无默认值，必须配置。

侦听IP地址，在多网卡主机上不建议配置成0.0.0.0。

-version

bool

false

是否查询NPU Exporter版本号。

  • true：查询。
  • false：不查询。

-concurrency

int

5

HTTP服务的限流大小，默认5个并发，取值范围为1~512。

-logLevel

int

0

日志级别：

  • -1：debug
  • 0：info
  • 1：warning
  • 2：error
  • 3：critical

-maxAge

int

7

日志备份时间，取值范围为7~700，单位为天。

-logFile

string

/var/log/mindx-dl/npu-exporter/npu-exporter.log

日志文件。

说明：

单个日志文件超过20 MB时会触发自动转储功能，文件大小上限不支持修改。转储后文件的命名格式为：npu-exporter-触发转储的时间.log，如：npu-exporter-2023-10-07T03-38-24.402.log。

-maxBackups

int

30

转储后日志文件保留个数上限，取值范围为1~30，单位为个。

-containerMode

string

docker

设置容器运行时类型。

  • 设置为“docker”表示当前环境使用Docker作为容器运行时。
  • 设置为“containerd”表示当前环境使用Containerd作为容器运行时。
  • 设置为“isula”表示当前环境使用iSula作为容器运行时。

-containerd

string
  • (Docker)

    unix：///var/run/docker/containerd/docker-containerd.sock

  • (Containerd)

    unix：///run/containerd/containerd.sock

  • (iSula)

    unix：///run/isulad.sock

containerd daemon进程endpoint，用于与Containerd通信。

  • 若containerMode=docker，则默认值为/var/run/docker/containerd/docker-containerd.sock；连接失败后，自动尝试连接：unix：///run/containerd/containerd.sock。
  • 若containerMode=containerd，则默认值为/run/containerd/containerd.sock。
  • 若containerMode=isula，则默认值为/run/isulad.sock。

一般情况下使用默认值即可。若用户自行修改了Containerd的sock文件路径则需要进行相应路径的修改。

可通过ps aux | grep containerd命令查询Containerd的sock文件路径是否修改。

-endpoint

string
  • (Docker)

    unix：///var/run/dockershim.sock

  • (Containerd)

    unix：///run/containerd/containerd.sock

  • (iSula)

    unix：///run/isulad.sock

CRI server的sock地址：

  • 若containerMode=docker，将连接到dockershim获取容器列表，默认值/var/run/dockershim.sock；
  • 若containerMode=containerd，默认值/run/containerd/containerd.sock。
  • 若containerMode=isula，则默认值为/run/isulad.sock。

一般情况下使用默认值即可，除非用户自行修改了dockershim或者Containerd的sock文件路径。

-limitIPConn

int

5

每个IP的TCP限制数的取值范围为1~128。

-limitTotalConn

int

20

程序总共的TCP限制数的取值范围为1~512。

-limitIPReq

string

20/1

每个IP的请求限制数，20/1表示1秒限制20个请求，“/”两侧最大只支持三位数。

-cacheSize

int

102400

缓存key的数量限制，取值范围为1~1024000。

-h或者-help

无

无

显示帮助信息。

-platform

string

Prometheus

指定对接平台。

  • Prometheus：对接Prometheus
  • Telegraf：对接Telegraf

-poll_interval

duration(int)

1

Telegraf数据上报的间隔时间，单位：秒。此参数在对接Telegraf平台时才起作用，即需要指定-platform=Telegraf时才生效，否则该参数不生效。

-profilingTime

int

200

配置采集PCIe带宽时间，单位：毫秒，取值范围为1~2000。

-hccsBWProfilingTime

int

200

HCCS链路带宽采样时长，取值范围1~1000，单位：毫秒。
父主题： 手动安装