ghcr.io/run-ai/fake-gpu-operator/kwok-gpu-device-plugin:0.0.0-5a37f51

Fake GPU Operator

🎮 在没有实际硬件的情况下在 Kubernetes 中模拟 NVIDIA GPU

[!NOTE] 容器镜像和 Helm 图表现已在 ghcr.io/run-ai/fake-gpu-operator 提供。

[!NOTE] 容器镜像和 Helm 图表现已在 ghcr.io/run-ai/fake-gpu-operator 提供。

ghcr.io/run-ai/fake-gpu-operator

🚀 概述

Fake GPU Operator 是一款轻量级工具，可在 Kubernetes 集群中模拟 NVIDIA GPU，无需物理硬件。它为开发人员和测试人员提供以下基本功能：

• 在仅含 CPU 的节点上模拟虚拟 GPU
• 支持基本功能发现和 NVIDIA MIG
• 生成用于 GPU 监控的 Prometheus 指标
• 降低测试环境的硬件成本

使用场景包括：

• 测试依赖 GPU 的应用程序
• CI/CD 流水线测试
• 开发环境
• 学习和实验

✨ 功能特性

• 基本 GPU 拓扑模拟
• 发布 NUMA 拓扑（NodeResourceTopology）以支持 NUMA 感知调度

NodeResourceTopology

• Prometheus 指标生成
• 基本 NVIDIA MIG 资源调度（暂不支持指标监控）
• 可配置的 GPU 类型和内存
• 基本 nvidia-smi 模拟

🏃 快速开始

前提条件

• 未安装 NVIDIA GPU Operator 的 Kubernetes 集群
• Helm 3.x
• kubectl 命令行工具

1. 为节点打标签

kubectl label node run.ai/simulated-gpu-node-pool=default

2. 安装 Operator

helm upgrade -i gpu-operator oci://ghcr.io/run-ai/fake-gpu-operator/fake-gpu-operator --namespace gpu-operator --create-namespace --version

3. 部署测试工作负载

apiVersion: v1
kind: Pod
metadata:
name: gpu-pod
spec:
containers:
- name: gpu-container
image: nvidia/cuda-vector-add:v0.1
resources:
limits:
nvidia.com/gpu: 1

🎭 KWOK Integration (Simulated Nodes)

KWOK (Kubernetes WithOut Kubelet) 是一个工具包，允许您在不运行实际 kubelet 进程的情况下模拟数千个 Kubernetes 节点。与 Fake GPU Operator 结合使用时，您可以完全无需硬件即可创建大规模 GPU 集群模拟——非常适合测试调度器、自动扩缩器和大规模资源管理。

Why KWOK + Fake GPU Operator?

• 规模测试：模拟数百个 GPU 节点以测试调度器行为
• 成本效益：无需云 VM 或物理硬件
• 快速迭代：在几秒钟内启动/关闭模拟集群
• CI/CD：针对真实集群拓扑运行端到端测试

Prerequisites

• 在集群中安装 KWOK 控制器：

KWOK_VERSION=v0.7.0
kubectl apply -f "https://github.com/kubernetes-sigs/kwok/releases/download/${KWOK_VERSION}/kwok.yaml"
kubectl apply -f "https://github.com/kubernetes-sigs/kwok/releases/download/${KWOK_VERSION}/stage-fast.yaml"

• 在 Helm 值中启用 kwok-dra-plugin：

# values.yaml
kwokDraPlugin:
  enabled: true
draPlugin:
  enabled: true

Create a Simulated GPU Node

apiVersion: v1
kind: Node
metadata:
  annotations:
    kwok.x-k8s.io/node: fake
  labels:
    type: kwok
    run.ai/simulated-gpu-node-pool: default
  name: kwok-gpu-node-1
spec:
  taints:
  - effect: NoSchedule
    key: kwok.x-k8s.io/node
    value: fake
status:
  allocatable:
    cpu: "32"
    memory: 128Gi
    pods: "110"
  capacity:
    cpu: "32"
    memory: 128Gi
    pods: "110"

status-updater 会自动为此节点创建拓扑 ConfigMap，kwok-dra-plugin 会创建带有已配置 GPU 的 ResourceSlice。

Schedule a GPU Pod on KWOK Node

apiVersion: resource.k8s.io/v1
kind: ResourceClaimTemplate
metadata:
  name: gpu-claim
spec:
  spec:
    devices:
      requests:
      - name: gpu
        exactly:
          deviceClassName: gpu.nvidia.com
---
apiVersion: v1
kind: Pod
metadata:
  name: kwok-gpu-pod
spec:
  nodeSelector:
    type: kwok
  tolerations:
  - key: kwok.x-k8s.io/node
    operator: Equal
    value: fake
    effect: NoSchedule
  containers:
  - name: main
    image: ubuntu:22.04
    command: ["sleep", "infinity"]
    resources:
      claims:
      - name: gpu
  resourceClaims:
  - name: gpu
    resourceClaimTemplateName: gpu-claim

Pod 将被“调度”到 KWOK 节点上并显示为 Running 状态（KWOK 模拟 Pod 生命周期）。ResourceClaim 将从模拟的 GPU ResourceSlice 中分配。

Verify Setup

# Check KWOK node is Ready
kubectl get nodes -l type=kwok

# Check ResourceSlice was created
kubectl get resourceslices | grep kwok

# Check pod is running on KWOK node
kubectl get pod kwok-gpu-pod -o wide

🏃 快速开始

前提条件

• 不含 NVIDIA GPU Operator 的 Kubernetes 集群
• Helm 3.x
• kubectl 命令行工具

1. 为节点打标签

kubectl label node run.ai/simulated-gpu-node-pool=default

2. 安装 Operator

helm upgrade -i gpu-operator oci://ghcr.io/run-ai/fake-gpu-operator/fake-gpu-operator --namespace gpu-operator --create-namespace --version

3. 部署测试工作负载

apiVersion: v1
kind: Pod
metadata:
name: gpu-pod
spec:
containers:
- name: gpu-container
image: nvidia/cuda-vector-add:v0.1
resources:
limits:
nvidia.com/gpu: 1

🛠️ 配置

GPU 拓扑

在 values.yaml 中自定义 GPU 配置：

topology:
nodePools:
default:
gpuProduct: Tesla-K80
gpuCount: 2
gpuMemory: 11441

GPU 利用率

通过 Pod 注解控制 GPU 利用率指标：

metadata:
annotations:
run.ai/simulated-gpu-utilization: "10-30" # 模拟 10-30% 的 GPU 使用率

Knative 推理工作负载集成

Operator 为基于 Knative 的推理工作负载提供特殊处理，其中 GPU 利用率会根据实际请求流量动态计算，而非使用静态值。

工作原理

当 Pod 被识别为推理工作负载（通过 workloadKind: "InferenceWorkload" 标签或 PodGroup priorityClassName: "inference"）时，Operator 会：

1. 查询 Prometheus 获取实时请求指标，使用 revision_app_request_count 指标
2. 基于请求速率计算利用率：rate(revision_app_request_count[1m])
3. 更新 GPU 指标 以反映实际推理负载

这提供了与推理流量模式相关的真实 GPU 利用率指标。

配置

在 Helm 值中配置 Prometheus 连接：

prometheus:
url: http://prometheus-operated.runai:9090 # 默认值

对于使用端口转发的本地开发：

prometheus:
url: http://localhost:9090

示例

apiVersion: v1
kind: Pod
metadata:
name: inference-pod
labels:
workloadKind: "InferenceWorkload" # 启用 Knative 利用率计算
spec:
containers:
- name: model-server
image: my-inference-server:latest
resources:
limits:
nvidia.com/gpu: 1

当请求流向此推理 Pod 时，GPU 利用率指标将反映来自 Knative 的实际请求速率。

支持的 Knative 工作负载类型：

• workloadKind: "InferenceWorkload" - 带 Knative 指标的单节点推理
• workloadKind: "DistributedWorkload" - 带 Knative 指标的分布式推理

🎭 KWOK 集成（模拟节点）

https://kwok.sigs.k8s.io/（Kubernetes WithOut Kubelet）是一个工具包，允许您模拟数千个 Kubernetes 节点，而无需运行实际的 kubelet 进程。当与 Fake GPU Operator 结合使用时，您可以完全无需硬件创建大规模 GPU 集群模拟——非常适合测试调度器、自动扩缩器和大规模资源管理。

为什么选择 KWOK + Fake GPU Operator？

• 规模测试：模拟数百个 GPU 节点以测试调度器行为
• 成本效益：无需云 VM 或物理硬件
• 快速迭代：在几秒钟内启动/关闭模拟集群
• CI/CD：针对真实集群拓扑运行端到端测试

前提条件

1. 在集群中安装 KWOK 控制器：

KWOK_VERSION=v0.7.0
kubectl apply -f "https://github.com/kubernetes-sigs/kwok/releases/download/${KWOK_VERSION}/kwok.yaml"
kubectl apply -f "https://github.com/kubernetes-sigs/kwok/releases/download/${KWOK_VERSION}/stage-fast.yaml"

2. 在 Helm 值中启用 kwok-dra-plugin：

# values.yaml
kwokDraPlugin:
enabled: true
draPlugin:
enabled: true

创建模拟 GPU 节点

apiVersion: v1
kind: Node
metadata:
annotations:
kwok.x-k8s.io/node: fake
labels:
type: kwok
run.ai/simulated-gpu-node-pool: default
name: kwok-gpu-node-1
spec:
taints:
- effect: NoSchedule
key: kwok.x-k8s.io/node
value: fake
status:
allocatable:
cpu: "32"
memory: 128Gi
pods: "110"
capacity:
cpu: "32"
memory: 128Gi
pods: "110"

status-updater 将自动为此节点创建拓扑 ConfigMap，kwok-dra-plugin 将创建包含已配置 GPU 的 ResourceSlice。

在 KWOK 节点上调度 GPU Pod

apiVersion: resource.k8s.io/v1
kind: ResourceClaimTemplate
metadata:
name: gpu-claim
spec:
spec:
devices:
requests:
- name: gpu
exactly:
deviceClassName: gpu.nvidia.com
---
apiVersion: v1
kind: Pod
metadata:
name: kwok-gpu-pod
spec:
nodeSelector:
type: kwok
tolerations:
- key: kwok.x-k8s.io/node
operator: Equal
value: fake
effect: NoSchedule
containers:
- name: main
image: ubuntu:22.04
command: ["sleep", "infinity"]
resources:
claims:
- name: gpu
resourceClaims:
- name: gpu
resourceClaimTemplateName: gpu-claim

Pod 将“调度”到 KWOK 节点上并显示为 Running 状态（KWOK 模拟 Pod 生命周期）。ResourceClaim 将从模拟的 GPU ResourceSlice 分配。

验证设置

# 检查 KWOK 节点是否就绪
kubectl get nodes -l type=kwok

# 检查是否创建了 ResourceSlice
kubectl get resourceslices | grep kwok

# 检查 Pod 是否在 KWOK 节点上运行
kubectl get pod kwok-gpu-pod -o wide

🔀 混合真实 + 模拟 GPU 节点

您可以在同一集群上同时运行 Fake GPU Operator 和真实的 NVIDIA GPU Operator：真实 GPU 节点由真实 Operator 完全管理，而模拟 GPU 节点用于规模和调度器测试。

默认情况下，Fake GPU Operator 是真实 Operator 的直接替代品，因此要使它们共存，您必须（1）在其自己的命名空间（而非 gpu-operator）中安装它，以及（2）禁用那些节点选择器/集群范围对象与真实 Operator 冲突的组件：

# mixed-mode-values.yaml — 与真实 NVIDIA GPU Operator 共存
devicePlugin: { enabled: false } # 选择器与真实 GPU 节点上的真实 device-plugin 冲突
statusExporter: { enabled: false } # 选择器与真实 GPU 节点上的真实 dcgm-exporter 冲突
runtimeClass: { enabled: false } # 集群范围的 RuntimeClass/nvidia 已由真实 Operator 拥有

安装到专用命名空间：

helm upgrade -i fake-gpu-operator oci://ghcr.io/run-ai/fake-gpu-operator/fake-gpu-operator \
--namespace fake-gpu-operator --create-namespace \
--version -f mixed-mode-values.yaml

然后：

• 模拟 GPU 在 KWOK 节点上运行（参见上文 KWOK 集成）。它们的 nvidia.com/gpu 容量由中央 kwok-gpu-device-plugin 发布，因此不需要已禁用的每节点 DaemonSet，并且 KWOK 的 NoSchedule 污点可防止真实 Operator 的 DaemonSet 部署到模拟节点。
• 真实 GPU 节点保持不变——只需不要用 run.ai/simulated-gpu-node-pool 标签标记它们。status-updater 仅对带有该标签的节点起作用，因此真实 Operator 保持对硬件的独占所有权。

🔍 故障排除

Pod 安全准入

为确保正常功能，请为 gpu-operator 命名空间配置 Pod 安全准入：

kubectl label ns gpu-operator pod-security.kubernetes.io/enforce=privileged

nvidia-smi 支持

Operator 会将模拟的 nvidia-smi 工具注入 GPU Pod 中。nvidia-smi 使用 NODE_NAME 环境变量解析 Pod 的节点拓扑；device-plugin 和 DRA 驱动程序都会在分配时自动注入该变量，因此无需手动配置 Pod。

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

📝 许可证

本项目采用 Apache License 2.0 许可证——详情参见 LICENSE 文件。

🙋 支持

• 🐛 https://github.com/run-ai/fake-gpu-operator/issues

---

由 Run:ai 用心创建