intel/xpumanager repository overview

This container image is intended for demo purposes only and not intended for production use. To receive expanded security maintenance from Canonical on the Ubuntu base layer, you may follow the how-to guide to enable Ubuntu Pro in a Dockerfile⁠ which will require the image to be rebuilt.

⁠Intel XPU Manager

Intel XPU Manager is an in-band node-level tool that provides local/remote GPU management. It is easily integrated into the cluster management solutions and cluster scheduler. GPU users may use it to manage Intel GPUs, locally. It supports local command line interface, local library call and remote RESTFul API interface.

The Intel XPU Manager source repository can be found at intel/xpumanager⁠.

⁠Run XPU Manager in Docker

⁠Prerequisites

To run XPUM image

• Install Docker (recommended Docker Engine v23.0 or higher)

To configure RESTful user credential

• Install Python3

⁠Overview

These examples show how to run XPUM container:

Example #1: Most of XPUM features are enabled. Subcommands vgpu, log and topdown are not supported in the container.

#${xpum_src_root} is the directory where xpumanager code is stored
git clone --depth 1 https://github.com/intel/xpumanager.git
xpum_src_root=$(pwd)/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

#${xpum_image} is XPUM docker image name and tag, you can replace "latest" with the specific version
xpum_image=intel/xpumanager:latest
docker pull ${xpum_image}

#${firmware_image_dir} is the directory where firmware images are stored
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}

Example #2: Limited features are enabled. It is targeted as a Prometheus exporter.

#${xpum_src_root} is the directory where xpumanager code is stored
git clone --depth 1 https://github.com/intel/xpumanager.git
xpum_src_root=$(pwd)/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

#${xpum_image} is XPUM docker image name and tag, you can replace "latest" with the specific version
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}

Please see details below for customized configurations.

⁠Enable TLS

Generate certificate for TLS and configure RESTful user credential:

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

Run the XPUM container:

⁠Disable TLS

Configure RESTful user credential:

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

Run the XPUM container by passing environment variable XPUM_REST_NO_TLS=1:

⁠Support Xe Link Throughput

To enable XPUM for reporting Xe Link throughput metrics, the container must be run in the 'host' network mode (--network host). To avoid port conflict with host network port assignment, you can pass environment variable XPUM_REST_PORT to the container to specify the XPUM RESTful server port. For example:

⁠Support PCIe Throughput

PCIe throughput metrics collection depends on the kernel module 'msr'. It should be loaded on the host by "modprobe msr".

And this metrics collection is not started in XPUM by default. To make XPUM start to collect it, user needs to pass environment variable XPUM_METRICS which includes the PCIe throughput metrics index.

This example shows how to get the list of metrics index from XPUM daemon help text:

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

This example shows how to make XPUM in container start to collect PCIe throughput metrics by passing the environment variable XPUM_METRICS:

⁠Support GFX Firmware Management

To support GFX firmware update in the container, please add the host Intel Management Engine Interface device '/dev/mei?' to the container. For example:

⁠Support AMC Firmware Management

XPUM supports IPMI protocol and Redfish host interface to update AMC (Add-in-card Management Controller) firmware. Please refer to releases/notice⁠ for more details.

OPTION #1 : IPMI protocol. Please add the host device '/dev/ipmi0' to the container. For example:

OPTION #2 : Redfish host interface. Please add the host device '/dev/mem' to the container and be run in the 'host' network mode (--network host). Extended privileges (--privileged) also need to be added to the container. For example:

⁠Support Device Configuration

To support device configuration, Please give extended privileges (--privileged) to the container. For example:

⁠Disable RESTFul API

If you do not use the container as a Prometheus exporter, you can disable RESTFul API by passing environment variable XPUM_REST_DISABLE and then no credential configuration is required. For example: