diff --git a/docs/get-started/local-testing-with-mock-gpu.md b/docs/get-started/local-testing-with-mock-gpu.md new file mode 100644 index 000000000..733e0f119 --- /dev/null +++ b/docs/get-started/local-testing-with-mock-gpu.md @@ -0,0 +1,214 @@ +--- +title: Local Zero-Hardware HAMi Sandbox & Mock GPU Testing +sidebar_label: Local Mock GPU Testing +--- + +This guide demonstrates how to set up a local, zero-hardware HAMi testing sandbox on a CPU-only machine using [Kind](https://kind.sigs.k8s.io/) (or Minikube) and HAMi's built-in **`mockDevicePlugin`**. + +This enables developers, evaluators, and contributors to test `hami-scheduler` resource allocation logic, verify `nvidia.com/gpumem` and `nvidia.com/gpucores` extended resource advertising, inspect mutating webhook annotations, and debug scheduling failure modes without requiring physical NVIDIA GPUs or host-installed CUDA drivers. + +:::note MOCK VALIDATION SCOPE + +- **MOCK VALIDATED**: Kubernetes extended resource registration (`nvidia.com/gpumem`, `nvidia.com/gpucores`), `hami-scheduler` extender allocation, mutating webhook pod annotations (`hami.io/bind-gpu-idx`), and scheduler oversubscription pending diagnostics. +- **REAL GPU VALIDATION REQUIRED**: Hardware-level CUDA symbol interception (`libvgpu.so`), hard GPU memory enforcement, and physical kernel execution. + +::: + +## Prerequisites + +Before starting, ensure your local CPU-only workstation has the following tools installed: + +- **Docker**: Engine v20.10+ +- **Kind**: v0.20.0+ (or Minikube) +- **kubectl**: v1.26+ +- **Helm**: v3.8+ + +## Step 1: Create a Local CPU-Only Kind Cluster + +Create a standard single-node Kubernetes cluster using Kind: + +```bash +kind create cluster --name hami-sandbox +``` + +Verify that `kubectl` is connected to your local cluster: + +```bash +kubectl cluster-info --context kind-hami-sandbox +kubectl get nodes +``` + +Expected output: + +```text +NAME STATUS ROLES AGE VERSION +hami-sandbox-control-plane Ready control-plane 30s v1.27.3 +``` + +## Step 2: Deploy HAMi with Mock Device Plugin + +Deploy HAMi using Helm, explicitly enabling `mockDevicePlugin.enabled=true` and disabling the default physical `devicePlugin.enabled=false`. + +1. Add the official HAMi Helm repository: + + ```bash + helm repo add hami-charts https://project-hami.github.io/HAMi/ + helm repo update + ``` + +2. Install HAMi in the `kube-system` namespace with mock plugin enabled: + + ```bash + helm install hami hami-charts/hami \ + --namespace kube-system \ + --set mockDevicePlugin.enabled=true \ + --set devicePlugin.enabled=false + ``` + +3. Verify that the HAMi components are running: + + ```bash + kubectl get pods -n kube-system -l 'app.kubernetes.io/name=hami' + ``` + +Expected output: + +```text +NAME READY STATUS RESTARTS AGE +hami-scheduler-65b7964448-x8j2l 1/1 Running 0 45s +hami-vgpu-mock-device-plugin-ds-7k9lm 1/1 Running 0 45s +``` + +## Step 3: Verify Node Extended Resource Advertising + +The `mockDevicePlugin` registers simulated NVIDIA GPU extended resources to the Kubernetes node allocator. + +Inspect the node allocatable capacity: + +```bash +kubectl describe node hami-sandbox-control-plane | grep -A 8 "Allocatable:" +``` + +Expected output: + +```text +Allocatable: + cpu: 8 + ephemeral-storage: 100Gi + hugepages-2Mi: 0 + memory: 16300Mi + nvidia.com/gpucores: 100 + nvidia.com/gpumem: 8192 + nvidia.com/gpumem-percentage: 100 + pods: 110 +``` + +Notice that `nvidia.com/gpumem` (8192 MiB) and `nvidia.com/gpucores` (100 core units) are now active allocatable resources on your CPU-only node. + +## Step 4: Submit a Fractional vGPU Pod & Verify Scheduling + +Submit a test pod requesting a fraction of mock GPU memory and cores: + +```yaml +cat < | grep -A 5 "Allocatable:" + ``` + +3. Check scheduling failure reasons for `Pending` pods: + + ```bash + kubectl get events --field-selector reason=FailedScheduling + kubectl logs -n kube-system -l app.kubernetes.io/component=hami-scheduler + ``` + +For a complete step-by-step tutorial, see the [Local Mock GPU Testing Guide](../get-started/local-testing-with-mock-gpu.md). diff --git a/sidebars.js b/sidebars.js index 3487c0e9f..be5df3252 100644 --- a/sidebars.js +++ b/sidebars.js @@ -37,7 +37,11 @@ module.exports = { title: "Get Started", description: "Install and run HAMi quickly with a guided first deployment path.", }, - items: ["get-started/deploy-with-helm", "get-started/verify-hami"], + items: [ + "get-started/deploy-with-helm", + "get-started/verify-hami", + "get-started/local-testing-with-mock-gpu", + ], }, { type: "category", diff --git a/static/img/vllm-meetup-shanghai-2026-recap/li-mengxuan-speaking.webp b/static/img/vllm-meetup-shanghai-2026-recap/li-mengxuan-speaking.webp index 7a780067c..b32a97726 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/li-mengxuan-speaking.webp and b/static/img/vllm-meetup-shanghai-2026-recap/li-mengxuan-speaking.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase0-code.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase0-code.webp index 943d77310..f3dc18cbc 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase0-code.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase0-code.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase0-overview.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase0-overview.webp index 88022fa88..9e36a24b6 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase0-overview.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase0-overview.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase1-k8s.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase1-k8s.webp index 52681195d..bc1b1bae8 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase1-k8s.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase1-k8s.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase1-overview.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase1-overview.webp index a69dee6d5..6f7d20f30 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase1-overview.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase1-overview.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd-detail.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd-detail.webp index 35fbc44bf..bff28f237 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd-detail.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd-detail.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd.webp index f5fb6cdd6..a91727b17 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase2-llmd.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake-code.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake-code.webp index 8248a26cc..9de5cb5b7 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake-code.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake-code.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake.webp index b91ac08af..c2a1f20a4 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase2-mooncake.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase2-nccl.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase2-nccl.webp index 0a86d912f..4794a7c39 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase2-nccl.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase2-nccl.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase2-pd.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase2-pd.webp index 7f56f8457..fc0b755c9 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase2-pd.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase2-pd.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase3-architecture.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase3-architecture.webp index 7881f3a81..dbb023e14 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase3-architecture.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase3-architecture.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase3-overview.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase3-overview.webp index 417d00ca8..97a84e0d8 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase3-overview.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase3-overview.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/phase3-result.webp b/static/img/vllm-meetup-shanghai-2026-recap/phase3-result.webp index 4771af23a..00fbc7369 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/phase3-result.webp and b/static/img/vllm-meetup-shanghai-2026-recap/phase3-result.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/title.webp b/static/img/vllm-meetup-shanghai-2026-recap/title.webp index 4a4775762..f7ea94b59 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/title.webp and b/static/img/vllm-meetup-shanghai-2026-recap/title.webp differ diff --git a/static/img/vllm-meetup-shanghai-2026-recap/vllm-meetup-group-photo.webp b/static/img/vllm-meetup-shanghai-2026-recap/vllm-meetup-group-photo.webp index d3f48ac12..6514b9b37 100644 Binary files a/static/img/vllm-meetup-shanghai-2026-recap/vllm-meetup-group-photo.webp and b/static/img/vllm-meetup-shanghai-2026-recap/vllm-meetup-group-photo.webp differ