Skip to content

docs(get-started): simplify quick start and online installation guides #712

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
singhsrijan46 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs(get-started): simplify quick start and online installation guides #712

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1eedf07
docs(get-started): simplify quick start and online installation guides
singhsrijan46 Aug 3, 2026
40d6606
docs(get-started): address maintainer review feedback
singhsrijan46 Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 41 additions & 115 deletions docs/get-started/deploy-with-helm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,124 +1,53 @@
---
title: Deploy HAMi using Helm
title: Quick Start
sidebar_label: Get Started
---

This guide covers:

- Configuring NVIDIA container runtime on each GPU node
- Deploying HAMi using Helm
- Launching a vGPU task
- Verifying container resource limits
Get HAMi up and running in minutes by deploying the Helm chart and submitting your first shared GPU workload.

## Prerequisites {#prerequisites}

Before deploying HAMi, ensure your GPU nodes meet the following prerequisites:

- [Helm](https://helm.sh/docs/) v3+
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) v1.23+
- [CUDA](https://developer.nvidia.com/cuda-toolkit) v10.2+
- [NVIDIA Driver](https://www.nvidia.cn/drivers/unix/) v440+
- [NVIDIA Container Toolkit](../installation/prerequisites) (with `nvidia-container-runtime` set as default runtime)

## Installation {#installation}

### 1. Configure nvidia-container-toolkit {#configure-nvidia-container-toolkit}

Perform the following steps on all GPU nodes.

This guide assumes that NVIDIA drivers and the `nvidia-container-toolkit` are already installed, and that `nvidia-container-runtime` is set as the default low-level runtime.

See [nvidia-container-toolkit installation guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html).

The following example applies to Debian-based systems using Docker or containerd:

#### Install the `nvidia-container-toolkit` {#install-the-nvidia-container-toolkit}

```bash
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
&& curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
```

#### Configure Docker {#configure-docker}

When running Kubernetes with Docker, edit the configuration file (usually `/etc/docker/daemon.json`) to set `nvidia-container-runtime` as the default runtime:

```json
{
"default-runtime": "nvidia",
"runtimes": {
"nvidia": {
"path": "/usr/bin/nvidia-container-runtime",
"runtimeArgs": []
}
}
}
```

Restart Docker:

```bash
sudo systemctl daemon-reload && sudo systemctl restart docker
```

#### Configure containerd {#configure-containerd}

When using Kubernetes with containerd, modify the configuration file (usually `/etc/containerd/config.toml`) to set `nvidia-container-runtime` as the default runtime:

```toml
version = 2
[plugins]
[plugins."io.containerd.grpc.v1.cri"]
[plugins."io.containerd.grpc.v1.cri".containerd]
default_runtime_name = "nvidia"

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]
privileged_without_host_devices = false
runtime_engine = ""
runtime_root = ""
runtime_type = "io.containerd.runc.v2"
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]
BinaryName = "/usr/bin/nvidia-container-runtime"
```

Restart containerd:

```bash
sudo systemctl daemon-reload && sudo systemctl restart containerd
```
---

### 2. Label your nodes {#label-your-nodes}
## 1. Label your nodes {#label-your-nodes}

Label your GPU nodes for HAMi scheduling with `gpu=on`. Nodes without this label cannot be managed by the scheduler.
Label the target GPU nodes with `gpu=on`. Nodes without this label will not be managed by HAMi:

```bash
kubectl label nodes <node-name> gpu=on
```

### 3. Deploy HAMi using Helm {#deploy-hami-using-helm}
---

Check your Kubernetes version:
## 2. Deploy HAMi using Helm {#deploy-hami-using-helm}

```bash
kubectl version
```

Add the Helm repository:
Add the official HAMi Helm repository and deploy the chart:

```bash
helm repo add hami-charts https://project-hami.github.io/HAMi/
helm repo update
helm install hami hami-charts/hami -n kube-system
```

If successful, both `hami-device-plugin` and `hami-scheduler` pods should be in the `Running` state.
Verify that the `hami-scheduler` and `hami-device-plugin` pods are running:

```bash
kubectl get pods -n kube-system | grep hami
```

## Demo {#demo}
---

### 1. Submit demo task {#submit-demo-task}
## 3. Submit a vGPU Workload {#submit-a-vgpu-workload}

Containers can now request NVIDIA vGPUs using the `nvidia.com/gpu` resource type.
Create a Pod requesting 1 vGPU with 10240 MiB of GPU memory limit:

```yaml
Comment on lines +50 to 52

@coderabbitai coderabbitai Bot Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Tell users to save the manifest as gpu-pod.yaml.

The page shows an inline manifest, but the next command applies gpu-pod.yaml. A user who follows the steps literally does not create that file.

  • docs/get-started/deploy-with-helm.md#L51-L53: add “Save the following manifest as gpu-pod.yaml:”.
  • i18n/zh/docusaurus-plugin-content-docs/current/get-started/deploy-with-helm.md#L51-L53: add “将以下清单保存为 gpu-pod.yaml：”.
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/get-started/deploy-with-helm.md#L51-L53: add the same Chinese instruction.
  • versioned_docs/version-v2.9.0/get-started/deploy-with-helm.md#L51-L53: add the same English instruction.
📍 Affects 4 files
  • docs/get-started/deploy-with-helm.md#L51-L53 (this comment)
  • i18n/zh/docusaurus-plugin-content-docs/current/get-started/deploy-with-helm.md#L51-L53
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/get-started/deploy-with-helm.md#L51-L53
  • versioned_docs/version-v2.9.0/get-started/deploy-with-helm.md#L51-L53
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/get-started/deploy-with-helm.md` around lines 51 - 53, Update the
manifest introduction in docs/get-started/deploy-with-helm.md:51-53 and
versioned_docs/version-v2.9.0/get-started/deploy-with-helm.md:51-53 to tell
users to save it as “gpu-pod.yaml”; add the equivalent Chinese instruction in
i18n/zh/docusaurus-plugin-content-docs/current/get-started/deploy-with-helm.md:51-53
and
i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/get-started/deploy-with-helm.md:51-53.

apiVersion: v1
Expand All @@ -132,59 +61,56 @@ spec:
command: ["bash", "-c", "sleep 86400"]
resources:
limits:
nvidia.com/gpu: 1 # Request 1 vGPU
nvidia.com/gpumem: 10240 # Each vGPU provides 10240 MiB device memory (optional)
nvidia.com/gpu: 1
nvidia.com/gpumem: 10240
```

Wait for the pod to be ready:
Apply the manifest and wait for the Pod to become ready:

```bash
kubectl apply -f gpu-pod.yaml
kubectl wait --for=condition=Ready pod/gpu-pod --timeout=120s
```

### 2. Verify container resource limits {#verify-in-container-resource-control}
---

## 4. Verify GPU Memory Isolation {#verify-gpu-memory-isolation}

Run the following command:
Execute `nvidia-smi` inside the running container:

```bash
kubectl exec -it gpu-pod -- nvidia-smi
```

Expected output:
Expected output showing HAMi-core hard memory limit (`10240MiB`):

```text
[HAMI-core Msg(28:140561996502848:libvgpu.c:836)]: Initializing.....
Wed Apr 10 09:28:58 2024
[HAMI-core Msg]: Initializing.....
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.54.15 Driver Version: 550.54.15 CUDA Version: 12.4 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 Tesla V100-PCIE-32GB On | 00000000:3E:00.0 Off | 0 |
| N/A 29C P0 24W / 250W | 0MiB / 10240MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| No running processes found |
+-----------------------------------------------------------------------------------------+
[HAMI-core Msg(28:140561996502848:multiprocess_memory_limit.c:434)]: Calling exit handler 28
```

## Cleanup
---

## Cleanup {#cleanup}

Delete the test Pod:

```bash
kubectl delete pod gpu-pod
```

## Next steps
---

## Next steps {#next-steps}

- Verify your setup in detail with [Verify HAMi Installation](./verify-hami.md).
- Learn how to customize your deployment parameters in the [Configuration Guide](../userguide/configure.md).

- [Validate HAMi](./verify-hami) - deeper validation including native GPU stack checks
- [Configure HAMi](../userguide/configure) - resource limits, scheduling policies, and more
- [Device Sharing](../key-features/device-sharing) - how GPU sharing works under the hood
28 changes: 14 additions & 14 deletions docs/installation/online-installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,41 +3,41 @@ sidebar_label: Online Installation from Helm
title: Online Installation from Helm (Recommended)
---

The recommended way to deploy HAMi is via Helm.
The recommended way to deploy HAMi in a Kubernetes cluster is via the official Helm chart.

## Add HAMi repo
## 1. Add HAMi Helm Repository {#add-hami-repo}

You can add HAMi chart repository using the following command:
Add the HAMi chart repository and update local repository cache:

```bash
helm repo add hami-charts https://project-hami.github.io/HAMi/
helm repo update
```

## Get your Kubernetes version
## 2. Deploy HAMi {#deploy-hami}

A Kubernetes version is required for proper installation. You can retrieve your Kubernetes server version with:
Ensure `scheduler.kubeScheduler.imageTag` matches your Kubernetes server version (e.g. `v1.29.0`). Deploy HAMi into the `kube-system` namespace using Helm:

```bash
kubectl version
helm install hami hami-charts/hami --set scheduler.kubeScheduler.imageTag=v1.29.0 -n kube-system
```

## Installation
### Customizing Helm Configurations

Ensure the `scheduler.kubeScheduler.image.tag` matches your Kubernetes server version. For instance, if your cluster server is v1.29.0, use the following command to deploy:
You can customize your deployment by passing parameters with `--set` or providing a custom `values.yaml` file:

```bash
helm install hami hami-charts/hami --set scheduler.kubeScheduler.image.tag=v1.29.0 -n kube-system
helm install hami hami-charts/hami --set scheduler.kubeScheduler.imageTag=v1.29.0 -n kube-system -f custom-values.yaml
```

Customize your installation by editing the [configurations](../userguide/configure.md).
For a detailed breakdown of available chart options and configuration keys, see the [Configuration Guide](../userguide/configure.md).

## Verify your installation
## 3. Verify Installation {#verify-installation}

You can verify your installation using the following command:
Verify that the HAMi components (`hami-device-plugin` and `hami-scheduler`) are running correctly:

```bash
kubectl get pods -n kube-system
kubectl get pods -n kube-system | grep hami
```

If both hami-device-plugin and hami-scheduler pods are in the Running state, your installation is successful.
If both `hami-device-plugin` and `hami-scheduler` pods are in the `Running` state, your installation is successful.
Comment on lines +35 to +43

@coderabbitai coderabbitai Bot Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

files=(
  "docs/installation/online-installation.md"
  "i18n/zh/docusaurus-plugin-content-docs/current/installation/online-installation.md"
  "i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/online-installation.md"
  "versioned_docs/version-v2.9.0/installation/online-installation.md"
)

for file in "${files[@]}"; do
  rg -n 'gpu=on|label nodes|标记节点' "$file" || {
    echo "Missing GPU-node labeling instructions: $file"
    exit 1
  }
done

Repository: Project-HAMi/website

Length of output: 239

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== target files =="
for f in \
  docs/installation/online-installation.md \
  i18n/zh/docusaurus-plugin-content-docs/current/installation/online-installation.md \
  i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/online-installation.md \
  versioned_docs/version-v2.9.0/installation/online-installation.md
do
  echo "--- $f"
  wc -l "$f"
  sed -n '1,120p' "$f"
done

echo "== search for selector/label references in docs =="
rg -n "gpu=on|matchLabels|nodeSelector|label nodes|节点标签|GPU 节点|device-plugin|hami-device-plugin" docs i18n versioned_docs -S || true

Repository: Project-HAMi/website

Length of output: 50377

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== target lines =="
for f in \
  docs/installation/online-installation.md \
  i18n/zh/docusaurus-plugin-content-docs/current/installation/online-installation.md \
  i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/online-installation.md \
  versioned_docs/version-v2.9.0/installation/online-installation.md
do
  echo "--- $f"
  wc -l "$f"
  sed -n '1,90p' "$f"
done

echo "== prerequisites labeling sections =="
for f in \
  docs/installation/prerequisites.md \
  docs/installation/offline-installation.md \
  i18n/zh/docusaurus-plugin-content-docs/current/installation/prerequisites.md \
  i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/prerequisites.md \
  versioned_docs/version-v2.9.0/installation/prerequisites.md
do
  echo "--- $f"
  if [ -f "$f" ]; then
    rg -n "gpu=on|label nodes|标记节点|Prepare|准备" "$f" -C 3 || true
  fi
done

echo "== hami-device-plugin manifest snippets in docs = "
rg -n "app\.kubernetes\.io/component: hami-device-plugin|nodeSelector:|gpu: on|gpu=\"on\"|gpu:=on" docs/versioned_docs i18n/zh/docusaurus-plugin-content-docs -S --glob '*.md' --max-count 50 || true

Repository: Project-HAMi/website

Length of output: 9119

Add the GPU-node labeling prerequisite to the online installation pages.

hami-device-plugin depends on GPU nodes having the gpu=on label for HAMi scheduling. Add this step before helm install hami, or link clearly to the existing prerequisite, on all four pages:

  • docs/installation/online-installation.md
  • i18n/zh/docusaurus-plugin-content-docs/current/installation/online-installation.md
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/online-installation.md
  • versioned_docs/version-v2.9.0/installation/online-installation.md
📍 Affects 4 files
  • docs/installation/online-installation.md#L35-L43 (this comment)
  • i18n/zh/docusaurus-plugin-content-docs/current/installation/online-installation.md#L36-L44
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/online-installation.md#L36-L44
  • versioned_docs/version-v2.9.0/installation/online-installation.md#L35-L43
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/installation/online-installation.md` around lines 35 - 43, Add the
GPU-node labeling prerequisite before the helm install hami step, instructing
users to label applicable nodes with gpu=on or clearly link to the existing
prerequisite. Apply the same update to docs/installation/online-installation.md
lines 35-43,
i18n/zh/docusaurus-plugin-content-docs/current/installation/online-installation.md
lines 36-44,
i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/installation/online-installation.md
lines 36-44, and
versioned_docs/version-v2.9.0/installation/online-installation.md lines 35-43.

Source: MCP tools

Loading