intel/xpumanager

Intel XPU Manager Docker镜像文档

镜像概述和主要用途

Intel XPU Manager是一款带内节点级工具，提供本地/远程GPU管理功能。它可轻松集成到集群管理解决方案和集群调度器中，GPU用户可通过其管理本地Intel GPU。该工具支持本地命令行界面、本地库调用和远程RESTful API接口。

源代码仓库：https://github.com/intel/xpumanager/

核心功能和特性

• 支持本地命令行界面、库调用和远程RESTful API
• 可作为Prometheus指标导出器
• 支持GPU指标监控（如Xe Link吞吐量、PCIe吞吐量）
• 支持GFX固件和AMC固件管理
• 支持设备配置功能
• 可启用/禁用TLS加密

前提条件

运行XPUM镜像

• 安装Docker（推荐Docker Engine v23.0或更高版本）

配置RESTful用户凭证

• 安装Python3

使用方法和配置说明

运行示例

示例1：启用大部分功能

此示例启用XPUM的大部分功能（vgpu、log和topdown子命令在容器中不支持）：

sh
# 克隆源码仓库
git clone --depth 1 https://github.com/intel/xpumanager.git
xpum_src_root=$(pwd)/xpumanager
mkdir -p rest/conf

# 配置RESTful凭证
sudo ${xpum_src_root}/install/tools/rest/keytool.sh --owner=root --group=root
sudo ${xpum_src_root}/install/tools/rest/rest_config.py --owner=root --group=root

# 拉取镜像
xpum_image=intel/xpumanager:latest
docker pull ${xpum_image}

# 创建固件目录
firmware_image_dir=$HOME/firmware
mkdir -p ${firmware_image_dir}

# 运行容器
docker run --rm --privileged \
--network host \
--device /dev/dri:/dev/dri \
--device /dev/mem:/dev/mem \
$(ls /dev/|grep mei|sed 's/^/--device \/dev\//g'|tr "\n" " ") \
$(ls /dev/|grep ipmi|sed 's/^/--device \/dev\//g'|tr "\n" " ") \
-v /sys/kernel/debug:/sys/kernel/debug \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-v ${firmware_image_dir}:/tmp/firmware:ro \
-e XPUM_REST_PORT=12345 \
${xpum_image}

示例2：有限功能（作为Prometheus导出器）

此示例启用有限功能，适用于作为Prometheus导出器：

sh
# 克隆源码仓库
git clone --depth 1 https://github.com/intel/xpumanager.git
xpum_src_root=$(pwd)/xpumanager
mkdir -p rest/conf

# 配置RESTful凭证
sudo ${xpum_src_root}/install/tools/rest/keytool.sh --owner=root --group=root
sudo ${xpum_src_root}/install/tools/rest/rest_config.py --owner=root --group=root

# 拉取镜像
xpum_image=intel/xpumanager:latest
docker pull ${xpum_image}

# 运行容器
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--publish 29999:29999 \
--device /dev/dri:/dev/dri \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
${xpum_image}

启用TLS

生成TLS证书并配置RESTful用户凭证：

sh
xpum_src_root=$HOME/xpumanager
mkdir -p rest/conf
sudo ${xpum_src_root}/install/tools/rest/keytool.sh --owner=root --group=root
sudo ${xpum_src_root}/install/tools/rest/rest_config.py --owner=root --group=root

运行容器：

sh
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--publish 29999:29999 \
--device /dev/dri:/dev/dri \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
${xpum_image}

禁用TLS

配置RESTful用户凭证：

sh
xpum_src_root=$HOME/xpumanager
mkdir -p rest/conf
sudo ${xpum_src_root}/install/tools/rest/rest_config.py --owner=root --group=root

通过环境变量XPUM_REST_NO_TLS=1运行容器：

sh
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--publish 29999:29999 \
--device /dev/dri:/dev/dri \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-e XPUM_REST_NO_TLS=1 \
${xpum_image}

支持Xe Link吞吐量

要启用Xe Link吞吐量指标报告，容器必须以host网络模式运行（--network host）。可通过环境变量XPUM_REST_PORT指定RESTful服务器端口避免端口冲突：

sh
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--network host \
--device /dev/dri:/dev/dri \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-e XPUM_REST_NO_TLS=1 \
-e XPUM_REST_PORT=12345 \
${xpum_image}

支持PCIe吞吐量

PCIe吞吐量指标收集依赖内核模块msr，需在主机上通过modprobe msr加载。默认不启用，需通过环境变量XPUM_METRICS指定包含PCIe吞吐量指标索引的范围。

获取指标索引列表：

sh
docker run --rm --entrypoint /usr/bin/xpumd ${xpum_image} -h

运行容器启用PCIe吞吐量收集：

sh
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--cap-add=SYS_RAWIO \
--publish 29999:29999 \
--device /dev/dri:/dev/dri \
--device /dev/cpu:/dev/cpu \
--device /dev/mem:/dev/mem \
-v /sys/firmware/acpi/tables/MCFG:/pcm/sys/firmware/acpi/tables/MCFG:ro \
-v /proc/bus/pci/:/pcm/proc/bus/pci/ \
-v /proc/sys/kernel/nmi_watchdog:/pcm/proc/sys/kernel/nmi_watchdog \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-e XPUM_REST_NO_TLS=1 \
-e XPUM_METRICS=0-38 \
${xpum_image}

支持GFX固件管理

要支持容器内GFX固件更新，需将主机Intel Management Engine Interface设备/dev/mei?添加到容器：

sh
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--device /dev/dri:/dev/dri \
$(ls /dev/|grep mei|sed 's/^/--device \/dev\//g'|tr "\n" " ") \
-v ${firmware_image_dir}:/tmp/firmware:ro \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-e XPUM_REST_NO_TLS=1 \
${xpum_image}

支持AMC固件管理

XPUM支持通过IPMI协议和Redfish主机接口更新AMC（Add-in-card Management Controller）固件，详情参见https://github.com/intel/xpumanager/releases%E3%80%82

选项1：IPMI协议

添加主机设备/dev/ipmi0到容器：

sh
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--device /dev/dri:/dev/dri \
$(ls /dev/|grep ipmi|sed 's/^/--device \/dev\//g'|tr "\n" " ") \
-v ${firmware_image_dir}:/tmp/firmware:ro \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-e XPUM_REST_NO_TLS=1 \
${xpum_image}

选项2：Redfish主机接口

需以host网络模式运行，添加/dev/mem设备并赋予扩展权限：

sh
docker run --rm --privileged \
--network host \
--device /dev/dri:/dev/dri \
--device /dev/mem:/dev/mem \
-v ${firmware_image_dir}:/tmp/firmware:ro \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-e XPUM_REST_NO_TLS=1 \
${xpum_image}

支持设备配置

要支持设备配置，需赋予容器扩展权限（--privileged）：

sh
docker run --rm --privileged \
--device /dev/dri:/dev/dri \
-v $(pwd)/rest/conf:/usr/lib/xpum/rest/conf:ro \
-e XPUM_REST_NO_TLS=1 \
${xpum_image}

禁用RESTful API

若不将容器用作Prometheus导出器，可通过环境变量XPUM_REST_DISABLE禁用RESTful API，无需配置凭证：

sh
docker run --rm --cap-drop ALL --cap-add=SYS_ADMIN \
--device /dev/dri:/dev/dri \
-e XPUM_REST_DISABLE=1 \
${xpum_image}

环境变量说明