实验 1: 在线安装 HAMi

入门时长：约 60 分钟环境：带一块 NVIDIA T4 的 GCP 虚拟机费用：约 $1 的虚拟机费用验证于： 2026-06-04作者： @rootsongjc, @saiyam1814

本实验将在一台 Google Cloud GPU 虚拟机上，从零搭建 Kubernetes 集群并在线安装 HAMi，形成完整的 GPU 虚拟化运行环境。

你将得到什么

完成本实验后，你将拥有一台完整的 GPU 虚拟化 Kubernetes 集群。关于集群架构和各组件职责的详细解释，参见 HAMi 集群架构。

安装全景图

整个安装过程分 6 步，每一步都在解决一个具体问题：

HAMi 安装全景图

步骤	目的	解决什么问题
创建 GCP VM	准备一台带 GPU 的 Linux 服务器	Kubernetes 需要 GPU 硬件才能调度 GPU 工作负载
安装 Helm	Kubernetes 的包管理器	后续所有组件都通过 Helm 安装，类似 apt/yum
安装 Kubernetes	容器编排平台	HAMi 运行在 Kubernetes 之上，所有 GPU 资源由 K8s 管理
安装 Prometheus	监控系统	HAMi 和 GPU Operator 依赖 Prometheus 采集和存储指标
安装 GPU Operator	NVIDIA GPU 软件栈自动化管理	自动安装 GPU 驱动、容器工具包、指标采集器等组件
安装 HAMi	GPU 虚拟化与共享	让多个 Pod 共享同一张 GPU，实现显存切分和算力分配

前提条件

Google Cloud 账号，已启用 Compute Engine API
已安装 gcloud CLI 并完成认证（gcloud auth login）
GCP 配额中有 NVIDIA T4 GPU 可用

费用提示：n1-standard-4 + T4 虚拟机约 $0.55/小时。实验 3 和实验 4 直接复用这套集群，一次开机即可完成全部三个实验。实验结束后请删除虚拟机。

步骤 1: 创建 GCP 虚拟机

目的

创建一台带 GPU 的虚拟机，作为整个实验的基础环境。HAMi 需要物理 GPU 硬件（或直通虚拟 GPU）才能工作，它不是模拟 GPU，而是在真实 GPU 之上做切分和共享。

操作

设置环境变量：

export PROJECT_ID=$(gcloud config get-value project)
export ZONE=us-central1-a
export VM_NAME=hami-workshop
export MACHINE_TYPE=n1-standard-4
export GPU_TYPE=nvidia-tesla-t4
export IMAGE_FAMILY=ubuntu-2204-lts
export IMAGE_PROJECT=ubuntu-os-cloud
export DISK_SIZE=100

创建虚拟机：

gcloud compute instances create ${VM_NAME} \
    --project=${PROJECT_ID} \
    --zone=${ZONE} \
    --machine-type=${MACHINE_TYPE} \
    --accelerator=type=${GPU_TYPE},count=1 \
    --maintenance-policy=TERMINATE \
    --image-family=${IMAGE_FAMILY} \
    --image-project=${IMAGE_PROJECT} \
    --boot-disk-size=${DISK_SIZE}GB \
    --boot-disk-type=pd-ssd

--maintenance-policy=TERMINATE 是必须的，GPU 不支持在线迁移，如果 GCP 要维护宿主机，VM 会被终止而不是迁移。

SSH 登录：

gcloud compute ssh ${VM_NAME} --zone=${ZONE}

登录后切换到 root：

sudo su -

步骤 2: 安装 Helm

目的

Helm 是 Kubernetes 的包管理器，后续安装 Prometheus、GPU Operator、HAMi 都通过 Helm 完成。你可以把它理解成 Kubernetes 世界里的 apt 或 yum。

操作

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

验证：

helm version

步骤 3: 安装 Kubernetes

目的

HAMi 是 Kubernetes 上的 GPU 调度增强层，它以 Pod 形式运行在 Kubernetes 中。没有 Kubernetes，HAMi 没有运行的基础。

本步骤使用 kubeadm 搭建一个单节点集群。在单节点上，这个节点既是 Master（控制平面）也是 Worker（运行工作负载）。

操作

3.1 关闭 swap

Kubernetes 要求关闭 swap，因为 Kubernetes 的资源调度假设内存是固定的，swap 会导致性能不可预测。

swapoff -a
sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

3.2 加载内核模块

容器网络需要 overlay 和 br_netfilter 内核模块。overlay 用于容器文件系统层叠，br_netfilter 用于让 iptables 正确处理桥接流量。

cat <<EOF | tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

modprobe overlay
modprobe br_netfilter

3.3 配置内核网络参数

这些参数确保容器之间的网络流量能被正确路由和转发。

cat <<EOF | tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sysctl --system

3.4 安装 containerd

containerd 是 Kubernetes 默认的容器运行时，负责真正创建和运行容器。Docker 在 Kubernetes 1.24 后已不再是默认运行时。

apt-get update
apt-get install -y containerd

mkdir -p /etc/containerd
containerd config default | tee /etc/containerd/config.toml

# 启用 systemd cgroup 驱动，Kubernetes 要求运行时和 kubelet 使用相同的 cgroup 驱动
sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml

systemctl restart containerd
systemctl enable containerd

3.5 安装 kubeadm、kubelet、kubectl

这三个工具的关系：

kubeadm, kubelet, kubectl 关系

kubeadm：一次性工具，用来初始化集群
kubelet：常驻进程，负责本节点上 Pod 的创建和销毁
kubectl：日常运维使用的命令行工具

apt-get install -y apt-transport-https ca-certificates curl gpg

mkdir -p /etc/apt/keyrings

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | \
    gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.34/deb/ /' | \
    tee /etc/apt/sources.list.d/kubernetes.list

apt-get update
apt-get install -y kubelet kubeadm kubectl
apt-mark hold kubelet kubeadm kubectl

apt-mark hold 防止这些包被自动升级，Kubernetes 组件版本需要手动控制。

3.6 初始化集群

kubeadm init --pod-network-cidr=10.244.0.0/16

初始化完成后，配置 kubectl 访问权限：

mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

3.7 安装网络插件（Calico）

Pod 之间需要网络通信。Calico 是一个 CNI（Container Network Interface）插件，负责为 Pod 分配 IP 地址并处理网络路由。没有 CNI 插件，Pod 无法相互通信，节点会一直处于 NotReady 状态。

kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/tigera-operator.yaml

curl -fsSL https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/custom-resources.yaml | \
    sed 's|192.168.0.0/16|10.244.0.0/16|' | kubectl create -f -

第一个 manifest 安装 tigera-operator，负责管理 Calico 的生命周期。第二个创建 Installation 资源，告诉 operator 部署 Calico 本身。sed 把 Calico 默认的 IP 池（192.168.0.0/16）替换为 kubeadm init 时指定的 --pod-network-cidr 网段。如果不替换，tigera-operator 会报 Degraded（IPPool 192.168.0.0/16 is not within the platform's configured pod network CIDR(s)），节点永远不会变成 Ready。各 Calico 组件的职责参见 HAMi 集群架构。

等待 Calico Pod 就绪：

kubectl get pods -n calico-system

3.8 允许 Master 节点调度 Pod

单节点集群中，这个节点既是控制平面又是工作节点。默认情况下 Kubernetes 不会在 Master 节点上调度工作负载，需要手动移除这个限制：

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

3.9 验证集群状态

kubectl get nodes

预期输出（STATUS 为 Ready 表示集群就绪）：

NAME            STATUS   ROLES           AGE    VERSION
hami-workshop   Ready    control-plane   2m     v1.34.8

步骤 4: 安装 Prometheus

目的

Prometheus 是集群监控系统，负责采集和存储所有组件的指标数据。HAMi 和 GPU Operator 都依赖 Prometheus，HAMi 的调度器指标、设备插件指标、GPU 利用率指标都需要 Prometheus 来采集。

为什么先装 Prometheus

因为后续安装的 GPU Operator 和 HAMi 都会创建 ServiceMonitor（告诉 Prometheus 采集哪些指标）。如果 Prometheus 没准备好，这些 ServiceMonitor 就没有消费者。

操作

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm install prometheus prometheus-community/kube-prometheus-stack \
    -n monitoring --create-namespace \
    --set grafana.enabled=false \
    --set prometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues=false \
    --version=75.15.1

--set grafana.enabled=false 禁用了 Grafana，因为后续 HAMi WebUI 会提供 GPU 可视化界面。

serviceMonitorSelectorNilUsesHelmValues=false 让 Prometheus 采集所有命名空间的 ServiceMonitor，不受标签限制。如果不加这个参数，Prometheus 只会选择带 release: prometheus 标签的 ServiceMonitor，GPU Operator 为 dcgm-exporter 创建的 ServiceMonitor 会被静默忽略，最终一条 GPU 指标都采不到。

验证 Prometheus 组件状态：

kubectl get po -n monitoring

预期所有 Pod 状态为 Running：

NAME                                                   READY   STATUS    RESTARTS   AGE
prometheus-kube-prometheus-operator-xxxxxxxxxx-xxxxx   1/1     Running   0          2m
prometheus-kube-state-metrics-xxxxxxxxxx-xxxxx         1/1     Running   0          2m
prometheus-prometheus-kube-prometheus-prometheus-0     2/2     Running   0          2m
prometheus-prometheus-node-exporter-xxxxx              1/1     Running   0          2m

如果安装失败，需要先卸载再重装：helm uninstall -n monitoring prometheus

步骤 5: 安装 GPU Operator

目的

NVIDIA GPU Operator 自动管理 GPU 软件栈（驱动、容器工具包、指标采集、特征发现）。GPU Operator 各组件的详细说明参见 HAMi 集群架构。

关键： 必须禁用 GPU Operator 自带的 device-plugin（--set devicePlugin.enabled=false），因为 HAMi 会提供自己的增强版 device-plugin 来支持显存切分和 GPU 共享。两者不能共存。

操作

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update

helm install --wait --generate-name \
    -n gpu-operator --create-namespace \
    nvidia/gpu-operator \
    --set devicePlugin.enabled=false \
    --set dcgmExporter.serviceMonitor.enabled=true \
    --version=v25.3.0

--wait 参数会等待所有 Pod 就绪后才返回。首次安装需要几分钟下载 NVIDIA 驱动镜像。

等待所有 Pod 就绪：

kubectl get pods -n gpu-operator

预期输出（驱动编译耗时最长，整个软件栈大约 10 分钟达到这个状态）：

NAME                                                              READY   STATUS      RESTARTS   AGE
gpu-feature-discovery-4hjmc                                       1/1     Running     0          8m47s
gpu-operator-1780588875-node-feature-discovery-gc-585cccbdtvxgf   1/1     Running     0          9m34s
gpu-operator-1780588875-node-feature-discovery-master-d7cdrtkgv   1/1     Running     0          9m34s
gpu-operator-1780588875-node-feature-discovery-worker-2t5nw       1/1     Running     0          9m34s
gpu-operator-75ccfb6b7b-zmctx                                     1/1     Running     0          9m34s
nvidia-container-toolkit-daemonset-phf4g                          1/1     Running     0          8m47s
nvidia-cuda-validator-jdcsm                                       0/1     Completed   0          23s
nvidia-dcgm-exporter-f5tdt                                        1/1     Running     0          8m47s
nvidia-driver-daemonset-bccs7                                     1/1     Running     0          9m13s
nvidia-operator-validator-2jctf                                   1/1     Running     0          8m47s

nvidia-cuda-validator 状态为 Completed 是正常的，它是一个一次性 Job，验证 CUDA 可用后退出。node-feature-discovery 系列 Pod 是 GPU Operator 的依赖组件，负责检测硬件特征并给节点打标签。

验证 GPU 驱动

进入 nvidia-driver-daemonset Pod 验证 GPU 驱动是否正常加载（关于 nvidia-smi 背后的调用链，参见理解 GPU 驱动）：

kubectl -n gpu-operator exec -it $(kubectl get pods -n gpu-operator -l app=nvidia-driver-daemonset -o name | head -1) -- nvidia-smi

预期输出包含 GPU 信息（驱动版本、CUDA 版本、GPU 型号）：

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 570.124.06             Driver Version: 570.124.06     CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|=========================================+========================+======================|
|   0  Tesla T4                       On  |   00000000:00:04.0 Off |                    0 |
| N/A   64C    P8             17W /   70W |       1MiB /  15360MiB |      0%      Default |
+-----------------------------------------------------------------------------------------+

步骤 6: 安装 HAMi

目的

安装 HAMi GPU 虚拟化平台，让多个 Pod 可以共享同一张 GPU。HAMi 的架构和组件说明参见 HAMi 集群架构。

操作

通过 Helm 仓库在线安装 HAMi 开源版：

# 添加 HAMi Helm 仓库
helm repo add hami-charts https://project-hami.github.io/HAMi/

# 安装 HAMi
helm install hami hami-charts/hami -n kube-system --version 2.9.0

HAMi 开源版安装在 kube-system 命名空间中。

验证：

kubectl get pods -n kube-system | grep -E 'hami-scheduler|hami-device'

预期输出：

hami-scheduler-6d659887fc-j5ngc   2/2     Running   0          1m

此时只有 scheduler 在运行。device plugin DaemonSet 的节点选择器是 gpu=on，要等下一步给节点打标签后才会启动。

开启 GPU 节点

HAMi 不会自动接管所有 GPU 节点，需要手动标记哪些节点由 HAMi 管理。这种设计是为了让 HAMi 和非 HAMi 节点可以在同一个集群中共存。

# 获取节点名称
NODE_NAME=$(kubectl get nodes -o jsonpath='{.items[0].metadata.name}')

# 标记节点由 HAMi 管理
kubectl label nodes ${NODE_NAME} gpu=on

打完标签后，device plugin 在节点上启动：

kubectl get pods -n kube-system | grep -E 'hami-scheduler|hami-device'

hami-device-plugin-bbrjj          2/2     Running   0          30s
hami-scheduler-6d659887fc-j5ngc   2/2     Running   0          95s

验证 GPU 注册信息：

kubectl get node ${NODE_NAME} -o jsonpath='{.metadata.annotations.hami\.io/node-nvidia-register}'

预期输出是每张 GPU 一个 JSON 对象：

[{"id":"GPU-859b872c-0ba2-97b0-10b4-8b7185c55039","count":10,"devmem":15360,"devcore":100,"type":"NVIDIA-Tesla T4","mode":"hami-core","health":true,"devicepairscore":{}}]

这个 annotation 的字段含义：

字段	含义
`id`	设备 UUID
`count`	这张卡的 vGPU 切分数量
`devmem`	显存（MiB）
`devcore`	算力容量（%）
`type`	GPU 型号
`mode`	`hami-core` 表示软件层切分；配置了 MIG 的卡显示 `mig`
`health`	设备健康状态

其中 count=10 表示这张 GPU 被虚拟化为 10 个 vGPU，可以被最多 10 个 Pod 共享。节点的 allocatable 资源中 nvidia.com/gpu 会从 1 变成 10。HAMi v2.9.0 以 JSON 格式写入这个 annotation，旧版本使用逗号分隔的字符串格式。

（可选）安装 HAMi WebUI

HAMi WebUI 提供 GPU 资源的可视化管理界面：

helm repo add hami-webui https://project-hami.github.io/HAMi-WebUI

helm install my-hami-webui hami-webui/hami-webui \
    --set externalPrometheus.enabled=true \
    --set externalPrometheus.address="http://prometheus-kube-prometheus-prometheus.monitoring.svc.cluster.local:9090" \
    --set dcgm-exporter.enabled=false \
    -n kube-system

--set dcgm-exporter.enabled=false 因为 GPU Operator 已经安装了 dcgm-exporter，避免重复部署。

通过端口转发访问 WebUI：

kubectl port-forward service/my-hami-webui 3000:3000 --namespace=kube-system

访问 http://localhost:3000 即可打开 HAMi WebUI。

你将得到什么​

安装全景图​

前提条件​

步骤 1: 创建 GCP 虚拟机​

目的​

操作​

步骤 2: 安装 Helm​

目的​

操作​

步骤 3: 安装 Kubernetes​

目的​

操作​

3.1 关闭 swap​

3.2 加载内核模块​

3.3 配置内核网络参数​

3.4 安装 containerd​

3.5 安装 kubeadm、kubelet、kubectl​

3.6 初始化集群​

3.7 安装网络插件（Calico）​

3.8 允许 Master 节点调度 Pod​

3.9 验证集群状态​

步骤 4: 安装 Prometheus​

目的​

为什么先装 Prometheus​

操作​

步骤 5: 安装 GPU Operator​

目的​

操作​

验证 GPU 驱动​

步骤 6: 安装 HAMi​

目的​

操作​

开启 GPU 节点​

（可选）安装 HAMi WebUI​