HAMi 企业版在线部署手册

本文档面向 SRE / 平台工程师，介绍如何在 Kubernetes 集群上部署 HAMi Enterprise （HAMi 企业版），并完成 GPU 节点开启、监控对接与功能验证。

⚠️ 安装 ≠ 激活

完成本节的 Helm Charts 安装后，HAMi 企业版的核心组件会运行，但 GPU 虚拟化和调度功能需要激活证书后才能正常使用。

安装过程本身不依赖证书，您可以先完成部署，再通过后续步骤申请并导入证书。

简而言之：先装软件，后拿证书；不激活则 vGPU 切分与调度功能不可用，验证也会失败。

前置条件清单

类型	要求	验证命令
Kubernetes	在线安装请按所选 Chart 的 Kubernetes 支持范围配置集群。	kubectl version
容器运行时	containerd、CRI-O 等 Kubernetes CRI 运行时；GPU 节点已配置 NVIDIA Container Toolkit	kubectl get nodes -o wide
GPU 驱动	NVIDIA driver ≥ 470（推荐 ≥ 550）	nvidia-smi
Prometheus CRD	启用 Prometheus 或 VictoriaMetrics 监控对接时，需要 monitoring.coreos.com CRD。	kubectl api-resources --api-group=monitoring.coreos.com
GPU Operator	如已安装 GPU Operator，请确认 NVIDIA device-plugin 的管理方式，避免与 HAMi 重复提供设备。	helm list -A
存储空间	建议大于 30 GB	df -h

HAMi 自带的 NVIDIA device-plugin 与 GPU Operator 内置 device-plugin 不应同时启用。请在 GPU Operator 的 Helm values 中设置 devicePlugin.enabled=false。集群还需有可用的默认 StorageClass。

安装

本节使用在线 Helm Charts 安装。安装完成后，还需要申请证书并激活。

路径 A：在线 Helm Charts 安装

使用当前 kubeconfig context 指向目标集群后，先安装 HAMi 核心，再按需安装 NVIDIA GPU Operator、昇腾设备插件和监控组件。

推荐使用版本追踪系统维护集群中所有 Helm Chart releases 的 values 文件。 通过使用 -f example-values.yaml 覆盖 Charts 中默认 values 中与之相对应的 key。

选择好 kubeconfig context 后，开始操作：

安装 dynamia-ai/hami-enterprise：

helm install hami \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/charts/hami-enterprise \
  --version 2.10.0-r2 \
  --namespace hami-system \
  --create-namespace

hami-enterprise 常见 Chart 自定义选项如下表，完整 values 配置请见：HAMi Helm Chart Values Reference。

参数	说明	默认值
dra.enabled	是否部署启用 DRA	false
scheduler.leaderElect	是否启用hami-scheduler的多节点选举	true
scheduler.replicas	调整 hami-scheduler的实例数量	1
scheduler.kubeScheduler.image.registry	hami-scheduler所使用的kube-scheduler镜像仓库。	registry.cn-hangzhou.aliyuncs.com
scheduler.kubeScheduler.image.repository	hami-scheduler所使用的kube-scheduler镜像名称。	"google_containers/kube-scheduler"
scheduler.kubeScheduler.image.tag	hami-scheduler所使用的kube-scheduler镜像版本。如果不填，chart 会推算一个合适的版本。	""

使用非 NVIDIA 设备时，必须在 HAMi values 的 devices 下启用对应厂商。昇腾节点至少配置：

devices:
  ascend:
    enabled: true
    hamiVnpuCore: true

可选：NVIDIA GPU Operator

NVIDIA GPU Operator 是可选组件。节点已具备兼容的驱动、NVIDIA Container Toolkit 和运行时配置时，可以跳过。节点准备及 GPU Operator values 取舍请参阅 HAMi NVIDIA GPU 节点准备文档。如安装或复用 GPU Operator，关闭其内置 device-plugin（devicePlugin.enabled=false）和 CDI（cdi.enabled=false）。当前 HAMi Enterprise 使用 scheduler.useDownward，与 CDI 不兼容。调整已有集群的 CDI 配置前，请先评估运行中的 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 \
  --set cdi.enabled=false \
  --version=v25.10.1

可选：昇腾设备插件

在 HAMi 核心安装完成且 devices.ascend.enabled 与 devices.ascend.hamiVnpuCore 已启用后，按需安装昇腾设备插件。已有同类设备插件时避免重复安装。插件复用 HAMi 创建的 hami-scheduler-device ConfigMap。

nameOverride: "ascend-device-plugin"
fullnameOverride: "ascend-device-plugin"
config:
  create: false
  existingDeviceConfigMapName: hami-scheduler-device

helm install ascend-device-plugin \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/dynamia-ai/charts/ascend-device-plugin \
  --version 0.2.1 \
  --namespace hami-system \
  -f ascend-device-plugin.yaml

启用 GPU 节点

HAMi 的 NVIDIA device-plugin 仅在带 gpu=on 标签的节点上启动。以下标签用于需要由 HAMi 管理的 NVIDIA 节点；Ascend 组件通过各自的 nodeSelector 选择节点：

kubectl label nodes <node-name> gpu=on

验证：kubectl -n hami-system get pods 应能看到 hami-device-plugin-*、hami-scheduler-* 处于 Running 状态。

监控为可选项。仅在需要采集指标且集群尚无兼容监控系统时，按下例安装 kube-prometheus-stack；已有 Prometheus 或 VictoriaMetrics 时，请在后面的“监控对接”章节接入现有系统。

helm install prometheus \
  oci://ghcr.io/prometheus-community/charts/kube-prometheus-stack \
  --version 72.3.0 \
  --namespace monitoring \
  --create-namespace \
  --set alertmanager.enabled=false \
  --set grafana.enabled=false

监控对接

按需将 HAMi、DCGM Exporter 或 NPU Exporter 指标接入现有监控系统。需要随本手册安装 Prometheus 时，可选用前述 kube-prometheus-stack 命令。查询指标前，先检查相应采集目标 up=1。

如果使用 Prometheus， ServiceMonitor 资源的 metadata.labels 必须与 Prometheus 资源的 spec.serviceMonitorSelector 字段匹配，否则 Prometheus不会采集这些指标。

使用 VictoriaMetrics Operator 时，VMAgent.spec.serviceScrapeSelector 匹配 VMServiceScrape.metadata.labels，同时检查 serviceScrapeNamespaceSelector。从 ServiceMonitor 转换时，应确认已生成对应的 VMServiceScrape。

验证指标采集

Exporter	查询指标	预期
dcgm-exporter	DCGM_FI_DEV_GPU_UTIL	返回非空值
hami-exporter	hami_host_gpu_utilization_ratio	返回非空值
hami-device-plugin-exporter	hami_gpu_core_allocated_ratio	返回非空值

证书获取

HAMi 核心组件就绪后即可收集许可证信息；无需等待按需部署的 GPU Operator、昇腾或监控组件。

执行以下脚本收集许可证信息（需要 kubectl、jq）：

curl -fsSL https://public.hami.run/collect-hami-license-info.sh | bash

执行后可以看到以下 JSON 内容：

{
  "esn": "96565d61-986a-4918-aafb-448ff6e3746b",
  "deviceInstances": [
    {
      "uuid": "GPU-ceee905d-48ac-93de-a81b-17c00e1e5e02",
      "deviceType": "NVIDIA A10"
    }
  ]
}

把上述 JSON 发送给 Dynamia.ai 的售前/技术支持获取证书。

激活后验证

kubectl -n hami-system get pods
kubectl describe node <gpu-node>
kubectl get events --field-selector involvedObject.name=hami-license -n hami-system
kubectl get nodes -o custom-columns='NODE:.metadata.name,LICENSE:.metadata.annotations.hami\.io/nvidia-license'

事件中出现 LicenseValid 表示许可证校验通过。确认已选择组件的 Pod 处于 Running 或 Completed 状态，并确认受管节点已注册加速卡资源。

在线示例工作负载验证

运行以下示例前，确认目标集群能够拉取测试镜像 nvidia/cuda:12.4.0-base-ubuntu22.04。如果集群使用私有镜像仓库，请先将该镜像同步到私有仓库，并修改示例中的镜像地址。

kubectl delete pod hami-smoke --ignore-not-found

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: hami-smoke
spec:
  restartPolicy: Never
  containers:
    - name: cuda
      image: nvidia/cuda:12.4.0-base-ubuntu22.04
      command: ["sh", "-c", "nvidia-smi && sleep 30"]
      resources:
        limits:
          nvidia.com/gpu: 1
          nvidia.com/gpumem: 2000
EOF

kubectl wait --for=condition=Ready pod/hami-smoke --timeout=180s
kubectl logs hami-smoke

Pod 进入 Ready 状态且日志正常输出 GPU 信息，表示 HAMi 已完成 GPU 调度，容器内的 NVIDIA 运行时可以正常访问 GPU。验证完成后删除测试 Pod。

kubectl delete pod hami-smoke

常见问题

现象	可能原因	处理
镜像拉不下来	目标节点无法访问镜像仓库、镜像仓库认证信息缺失或无效，或者镜像地址错误	检查 Pod 事件和实际镜像地址，确认节点能够解析并访问镜像仓库，并配置所需的 imagePullSecrets。
hami-device-plugin Pod Pending 或者不存在	节点未打 gpu=on 标签	kubectl label nodes <node> gpu=on
hami-device-plugin Pod CrashLoopBackOff	与 NVIDIA 默认 device-plugin 冲突	禁用 GPU Operator 的 devicePlugin（--set devicePlugin.enabled=false）。
查不到 HAMi 指标	Prometheus 资源的serviceMonitorSelector 与 ServiceMonitor 资源中的 label 不匹配	对齐 prometheus/prometheus-kube-prometheus-prometheus 的 spec.serviceMonitorSelector 和 hami-enterprise 的 serviceMonitor labels。
nvidia-smi 报错	GPU 驱动未就绪	检查 gpu-operator namespace 下 driver Pod 状态。
示例 workload Pending	证书未激活、GPU 不足或节点标签缺失	检查证书、GPU 节点标签和 kubectl describe pod 事件

获取支持

• 邮箱：info@dynamia.ai

• 售前 / 技术支持：400-026-7800

• 已签订商业合同的客户请通过专属支持渠道提交 Issue