Enterprise

HAMi 企业版在线部署手册

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

⚠️ 安装 ≠ 激活

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

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

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

前置条件清单

类型	要求	验证命令
Kubernetes	≥ 1.24	`kubectl version --short`
容器运行时	containerd 或 Docker	`kubectl get nodes -o wide`
Helm	≥ 3.14	`helm version --short`
GPU 驱动	NVIDIA driver ≥ 470（推荐 ≥ 550）	`nvidia-smi`
Prometheus CRD	必须安装 Prometheus monitoring CRD 以兼容不同的监控指标采集系统：Prometheus, VictoriaMetrics, etc.	`kubectl api-resources \| grep monitoring.coreos.com/v1`
GPU Operator	已安装且 devicePlugin.enabled = false，推荐版本：v25.3.2）	`helm list -A \| grep gpu-operator`
存储空间	建议大于 30 GB	`df -h`

关键约束：HAMi 自带 device-plugin，与 NVIDIA GPU Operator 内置 device-plugin 冲突。若已安装 GPU Operator，务必通过--set devicePlugin.enabled=false 禁用其内置 plugin。

安装

两种安装路径，按场景选：

在线 OCI 安装（评估、PoC、可通外部网络的集群）
All-in-One 离线一体包（金融/政府/运营商等隔离网络场景）

无论如何安装，最后都需要申请证书并激活。

路径 A：在线 Helm Charts 安装

如果希望使用国内镜像仓库，请联系 Dynamia.ai 的售前/技术支持获取相关信息。

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

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

如果没有安装过 nvidia/gpu-operator，先安装。

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.2

如果集群里没有 Prometheus 等监控栈，还需要安装，这里展示 prometheus-community/kube-prometheus-stack 的安装方法。

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

安装 dynamia-ai/hami-enterprise：

helm install hami \
  oci://ghcr.io/dynamia-ai/charts/hami-enterprise \
  --version 2.9.0-rc2 \
  --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 会推算一个合适的版本。	`""`

路径 B：All-in-One 离线一体包

请联系 Dynamia.ai 的售前/技术支持伙伴获取下载地址和操作手册。

启用 GPU 节点

HAMi device-plugin 仅在带 gpu=on 标签（可以通过）的节点上启动：

kubectl label nodes <node-name> gpu=on

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

监控对接

确保集群里的监控指标系统（kube-prometheus-stack Prometheus，VictoriaMetrics vmagent 等）能采集 HAMi 与 DCGM-Exporter 指标。

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

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

验证指标采集

Exporter	查询指标	预期
`dcgm-exporter`	`DCGM_FI_DEV_GPU_UTIL`	返回非空值
`hami-exporter`	`HostCoreUtilization`	返回非空值
`hami-device-plugin-exporter`	`GPUDeviceCoreAllocated`	返回非空值

证书获取

请完成上述安装任务，确保所有组件的 Pod 都正常启动后再开始激活流程。

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

# 在线获取脚本
curl -fsSL https://public.hami.run/collect-hami-license-info.sh | bash

# 离线安装（包内已包含）
bash collect-hami-license-info.sh

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

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

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

激活后验证

# 1. Pod 状态
kubectl -n hami-system get pods

# 2. Device Plugin 注册的 GPU 资源
kubectl describe node <gpu-node> | grep -A 5 'Capacity:'
# 期望看到：nvidia.com/gpu: <N>  以及 nvidia.com/gpumem: <MB>

# 3. 提交一个测试 Pod 验证调度
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: hami-smoke
spec:
  restartPolicy: Never
  containers:
  - name: cuda
    image: nvidia/cuda:12.4.0-base-ubuntu22.04
    command: ["nvidia-smi"]
    resources:
      limits:
        nvidia.com/gpu: 1
        nvidia.com/gpumem: 2000
EOF

kubectl logs hami-smoke

期望：nvidia-smi 输出可见 GPU 信息，且显存被限制为 2000 MiB。

常见问题

现象	可能原因	处理
镜像拉不下来	Node 没有外部网络或者与 `ghcr.io` 连接不畅。	联系 Dynamia.ai 的售前/技术支持获取国内镜像仓库地址或 All-in-One 离线一体包。
`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

前置条件清单​

安装​

路径 A：在线 Helm Charts 安装​

路径 B：All-in-One 离线一体包​

启用 GPU 节点​

监控对接​

验证指标采集​

证书获取​

激活后验证​

常见问题​

获取支持​