Skip to content

Quick Start Guide

Get Mock NVML running in 5 minutes.

Requires Docker, kind, kubectl, and Helm 3.8+ (for OCI registry support).

kind create cluster --name mokka

helm install nvml-mock oci://ghcr.io/nvidia/k8s-test-infra/chart/nvml-mock \
    --namespace mokka --create-namespace \
    --set gpu.profile=gb300

Every node now reports 4 mock GB300 GPUs, one NVL72 compute tray. gb300 is the chart default; swap in a100, h100, b200, gb200, l40s, or t4 for other hardware.

Verify:

kubectl exec -n mokka ds/nvml-mock -- nvidia-smi -L

Use make cluster-create instead of kind create cluster when you need the CDI-enabled Kind node image — that is what the device plugin, DRA driver, and GPU Operator paths run on. make cluster-delete tears it down.

See the Helm Chart README for full deployment walkthrough including device plugin, DRA driver, and GPU Operator integration.

Building the Library Locally

The sections below build the mock libnvidia-ml.so directly, for local development and CI pipelines outside Kubernetes. They need:

  • Linux (x86_64 or arm64)
  • Go 1.25+ with CGo
  • GCC toolchain (build-essential on Debian/Ubuntu)
  • nvidia-smi binary (optional -- only needed for local nvidia-smi output; the Kubernetes deployment includes it automatically)

Option 1: Local Build (Linux)

Step 1: Build the Library

cd pkg/gpu/mocknvml
make

This creates: 

libnvidia-ml.so.550.163.01  # Versioned library
libnvidia-ml.so.1           # Soname symlink
libnvidia-ml.so             # Linker symlink

Step 2: Run with Default Configuration

# 8x Mock A100 GPUs with default settings
LD_LIBRARY_PATH=. nvidia-smi

Step 3: Run with YAML Configuration

# A100 profile (40GB, 400W)
LD_LIBRARY_PATH=. MOCK_NVML_CONFIG=configs/mock-nvml-config-a100.yaml nvidia-smi

# GB200 profile (192GB, 1000W)
LD_LIBRARY_PATH=. MOCK_NVML_CONFIG=configs/mock-nvml-config-gb200.yaml nvidia-smi

# GB300 profile (288GB, 1400W, Blackwell Ultra)
LD_LIBRARY_PATH=. MOCK_NVML_CONFIG=configs/mock-nvml-config-gb300.yaml nvidia-smi

Option 2: Docker Build (Cross-Platform)

Build Linux binaries from macOS or other platforms:

cd pkg/gpu/mocknvml
make docker-build

Build artifacts (shared libraries) are placed in pkg/gpu/mocknvml/: libnvidia-ml.so, libnvidia-ml.so.1, libnvidia-ml.so.{version}, and nvidia-smi.

Verification

Basic Check

LD_LIBRARY_PATH=. nvidia-smi -L

Expected output: 

GPU 0: NVIDIA A100-SXM4-40GB (UUID: GPU-12345678-1234-1234-1234-123456780000)
GPU 1: NVIDIA A100-SXM4-40GB (UUID: GPU-12345678-1234-1234-1234-123456780001)
...

Full Query

LD_LIBRARY_PATH=. MOCK_NVML_CONFIG=configs/mock-nvml-config-a100.yaml nvidia-smi -q

XML Output

LD_LIBRARY_PATH=. MOCK_NVML_CONFIG=configs/mock-nvml-config-a100.yaml nvidia-smi -x -q

CSV Query

LD_LIBRARY_PATH=. nvidia-smi --query-gpu=index,name,uuid,memory.total --format=csv

Debug Mode

Enable verbose logging to see NVML function calls:

LD_LIBRARY_PATH=. MOCK_NVML_DEBUG=1 nvidia-smi

Output includes: 

[CONFIG] Loaded YAML config: 8 devices, driver 550.163.01
[ENGINE] Creating devices from YAML config
[DEVICE 0] Created: name=NVIDIA A100-SXM4-40GB uuid=GPU-12345678-...
[NVML] nvmlDeviceGetHandleByIndex(0)
[NVML] nvmlDeviceGetTemperature(sensor=0) -> 33

Environment Variables

Variable Description Default
MOCK_NVML_CONFIG Path to YAML config file (none)
MOCK_NVML_NUM_DEVICES Number of GPUs (without YAML) 8
MOCK_NVML_DRIVER_VERSION Driver version (without YAML) 550.163.01
MOCK_NVML_DEBUG Enable debug logging (disabled)

Next Steps