Enterprise

HAMi 企业版离线部署手册

本文档面向 SRE / 平台工程师，说明如何使用 v0.0.5 All-in-One 离线包和 Zarf v0.86.0，在 Kubernetes 集群中部署 HAMi Enterprise，并完成证书激活、GPU / NPU 节点启用和工作负载验证。命令以 Linux amd64 为例，其他架构需替换对应文件名。

本交付包使用 Zarf，是为了在无外网或受限网络中完成镜像导入、Helm Charts 安装和后续升级，减少用户手工同步镜像与维护安装顺序的成本。

Zarf 是面向 Kubernetes 离线 / 半离线环境的应用打包与部署工具，可以把镜像、Helm chart、脚本和部署动作封装成一个可携带的包。

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

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

离线包内容

外层交付包命名格式为：

hami-enterprise-v<VERSION>-airgap-<ARCH>.tar.gz
hami-enterprise-v<VERSION>-airgap-<ARCH>.tar.gz.sha256

hami-enterprise-v0.0.5-airgap-amd64.tar.gz 完整版中包含以下关键文件：

文件	用途
`zarf-linux-amd64`	Zarf v0.86.0 Linux amd64 CLI
`zarf-init-amd64-v0.86.0.tar.zst`	Zarf init 离线包
`hami-enterprise-v0.0.5-airgap-amd64.tar.zst`	HAMi Enterprise 主部署包
`package-values.yaml`	按组件分组的 package values 模板，七个组件键默认为空对象
`PACKAGE-VALUES.md`	组件键映射与配置覆盖说明
`zarf-package-hami-example-gpu-burn-amd64-v0.0.2.tar.zst`	GPU Burn 示例验证包，仅完整版包含
`zarf-package-hami-example-vllm-qwen-amd64-v0.0.4.tar.zst`	vLLM + Qwen 示例验证包，仅完整版包含
`collect-hami-license-info.sh`	证书申请信息收集脚本
`collect-cluster-info.sh` / `COLLECT-CLUSTER-INFO.md`	集群信息收集脚本及工具、权限、kubeconfig 使用说明
`hami/` / `hami/README.md`	HAMi Chart 原生 values 示例及完整参数说明；不能直接作为 v0.0.5 package values

Slim 外层归档命名为 hami-enterprise-slim-v0.0.5-airgap-amd64.tar.gz，内层主包使用同名 .tar.zst。Slim 保留 GPU Operator，但不包含 NVIDIA 驱动镜像和示例包。选择 Slim 时，GPU 节点须已安装兼容的 NVIDIA 驱动。

前置条件清单

类型	要求	验证命令
Kubernetes	v0.0.5 离线包要求 Kubernetes ≥ 1.27，并提供可用的默认 StorageClass。	`kubectl version`
容器运行时	目标集群的 Kubernetes CRI 运行时可用；GPU 节点的运行时配置需与本次 NVIDIA 组件组合匹配。	`kubectl get nodes -o wide`
GPU 驱动	Slim 包不包含 NVIDIA 驱动镜像。选择 Slim 时，GPU 节点须已安装与硬件和目标环境兼容的驱动。	`nvidia-smi`
Prometheus CRD	启用 Prometheus 或 VictoriaMetrics 监控对接时，需要 `monitoring.coreos.com` CRD；选择 `prometheus-crds` 组件可由离线包安装	`kubectl api-resources --api-group=monitoring.coreos.com`
GPU Operator	已有 GPU Operator 时，避免重复安装；确认其内置 device-plugin 不与 HAMi 的设备插件冲突。	`zarf tools helm list -A`
存储空间	预留足够空间解压交付归档并导入镜像；按本次包大小和目标集群容量核算。	`df -h`

HAMi 的 NVIDIA device-plugin 与 GPU Operator 内置 device-plugin 不应同时运行。本交付包已关闭 GPU Operator 内置 device-plugin；如果集群已有 GPU Operator，部署前检查其设备插件配置。

解压、校验和安装 Zarf

# 下载交付包和校验文件
curl -L -O <URL>
curl -L -O <SHA256_URL>

# 校验完整性
shasum -a 256 -c hami-enterprise-v0.0.5-airgap-amd64.tar.gz.sha256

# 解压外层 tar.gz
tar -xzf hami-enterprise-v0.0.5-airgap-amd64.tar.gz

# 进入解压目录
cd hami-enterprise-v0.0.5-airgap-amd64

交付包内包含 Zarf v0.86.0 Linux amd64 CLI。进入解压目录后，安装包内 Zarf，并检查输出版本：

chmod +x ./zarf-linux-amd64
sudo install -m 0755 ./zarf-linux-amd64 /usr/local/bin/zarf
zarf version

Zarf 自带 Helm 工具，后续排查 Helm release、values 和 chart 状态时请使用 zarf tools helm，避免目标环境没有单独安装 Helm：

zarf tools helm version
zarf tools helm list -A

初始化 Zarf

仅在目标集群尚未初始化 Zarf 时执行 zarf init。建议使用 labeled 策略，仅改写显式标记的 Namespace 或工作负载镜像。已初始化的集群应先检查现有 Zarf、Registry、StorageClass 和 Agent mutation policy；部署主包不会自动修改已有 policy，不要重复初始化。

使用 Zarf 内置 registry：

zarf init zarf-init-amd64-v0.86.0.tar.zst \
  --agent-mutation-policy=labeled \
  --confirm

使用外部 registry：

zarf init zarf-init-amd64-v0.86.0.tar.zst \
  --agent-mutation-policy=labeled \
  --registry-url=harbor.example.com/zarf-amd64 \
  --registry-push-username=<username> \
  --registry-push-password=<password> \
  --confirm

💡 多架构集群必须使用不同的 registry 前缀。 AMD64 和 ARM64 集群可以共用同一个 Harbor 实例，但不得共用同一个 Zarf registry Project 或仓库前缀。Zarf 离线包中的镜像已按目标架构打包。将 AMD64 与 ARM64 包依次部署到同一路径时，同名 tag 不会自动合并为多架构 manifest；后一次推送可能覆盖前一次推送的 tag，导致另一架构的 Pod 在重建或重新调度后拉取到不兼容的镜像。

初始化集群时，请为每种架构指定独立的 --registry-url，例如 AMD64 使用 registry.example.com/zarf-amd64，ARM64 使用 registry.example.com/zarf-arm64。请提前创建对应的 Harbor Project 或仓库前缀，并确保 Zarf 使用的账号具备推送和拉取权限。

外部 registry 参数说明：

参数	说明
`--registry-url`	外部镜像仓库地址
`--registry-push-username`	用于推送镜像的用户名
`--registry-push-password`	用于推送镜像的密码

初始化完成后，zarf package deploy 会导入包内镜像，并通过 admission webhook 将受管工作负载的镜像地址改写到 Zarf registry。使用 labeled 策略时，只处理带 zarf.dev/agent: mutate 标签的资源，或位于带该标签 Namespace 中的资源；资源自身的标签优先于 Namespace 标签。部署前应确认所选组件的 Namespace 已设置该标签 ，自行创建的离线工作负载也应先确认 Namespace 已标记。标签变更不会影响已经创建的 Pod，需要重新创建 Pod 才会再次触发改写。

仅当目标 registry 的 TLS 证书确实无法校验、且已经评估中间人攻击风险时，才在对应命令中临时使用 --insecure-skip-tls-verify。生产环境应优先修复证书链或为 Zarf Agent 配置可信 CA，不应把跳过 TLS 校验作为默认参数。

部署 HAMi Enterprise

业务组件默认关闭。部署时使用 --components 选择所需组件；仅传 --confirm 不会安装业务组件。

组件清单如下。已有 Prometheus、GPU Operator 等组件时，先核对版本、values、CRD 所有权和 Namespace，避免重复安装。

tools 会覆盖主机上的 /usr/local/bin/jq 和 /usr/local/bin/nerdctl，移除 Zarf 不会恢复这些文件。选择前记录已有文件及恢复方式。

组件名称	说明	是否必选	选择条件
`tools`	向主机 `/usr/local/bin` 安装 jq、nerdctl	否	运行 collector 前按说明安装
`hami`	HAMi Enterprise Chart 2.10.0-r2，Namespace 为 `hami-system`	是	部署 HAMi 核心时选择
`prometheus-crds`	Prometheus Operator CRD，使用 Server-Side Apply 安装	否	需要随包部署 Prometheus 时，与 prometheus 一同选择
`prometheus`	kube-prometheus-stack	否	需要随包部署 kube-prometheus-stack 时选择；已有监控系统可跳过
`gpu-operator`	NVIDIA GPU Operator；随包部署时不启用其内置 device-plugin	否	NVIDIA 场景按需选择；使用 Slim 时，GPU 节点须已安装兼容驱动
`ascend-device-plugin`	Ascend Device Plugin，Namespace 为 `hami-system`	否	按目标 NPU 型号和软切分配置选择
`npu-exporter`	可选的 Ascend NPU 指标采集组件；部署与监控说明见后文「可选：Ascend 节点与 NPU 监控」	否	需要 NPU 指标且满足 containerd/驱动前提时选择

Zarf v0.86.0 使用 --values=package-values.yaml 传入 package 级配置。v0.0.5 起，每个 Chart 的配置必须放在对应组件键下；不需要覆盖时可省略 --values。合并顺序为 Chart 默认值 → 包内 valuesFiles → 对应组件的 package values。填写某个组件的 values 不会自动选择该组件，仍需指定 --components。

准备自定义配置

从包内 package-values.yaml 模板开始配置，完整说明见 PACKAGE-VALUES.md。企业版可配置以下五个顶层键，各键彼此独立：

Package values 顶层键	目标 Chart / 适用范围
`hami`	HAMi Enterprise；企业版
`prometheus`	kube-prometheus-stack；企业版
`gpu-operator`	NVIDIA GPU Operator；完整版和 Slim 包均可配置
`ascend-device-plugin`	Ascend Device Plugin；企业版
`npu-exporter`	NPU Exporter；企业版

工具和 CRD 组件没有 Chart values 映射。hami/README.md 仍使用 Chart 原生参数名；在 package values 中应加上 hami. 前缀。常见配置项如下：

参数	说明	默认值
`hami.dra.enabled`	是否部署启用 DRA	`false`
`hami.scheduler.leaderElect`	是否启用 `hami-scheduler` 的多节点选举。单节点集群强烈建议关闭。	`true`
`hami.scheduler.replicas`	调整 `hami-scheduler` 的实例数量	1
`hami.scheduler.kubeScheduler.image.registry`	`hami-scheduler` 使用的 `kube-scheduler` 镜像仓库	`registry.cn-hangzhou.aliyuncs.com`
`hami.scheduler.kubeScheduler.image.repository`	`hami-scheduler` 使用的 `kube-scheduler` 镜像名	`google_containers/kube-scheduler`
`hami.scheduler.kubeScheduler.image.tag`	`hami-scheduler` 使用的 `kube-scheduler` 镜像版本，应与目标集群一致	`""`

最小配置示例：package-values.yaml。模板中的其他组件可以保持 {}；以下示例只列出需要覆盖的 HAMi 配置。

hami:
  dra:
    enabled: false
  scheduler:
    leaderElect: true

HAMi scheduler 依赖与目标 Kubernetes 集群版本匹配的 kube-scheduler 镜像。Chart 默认按目标集群版本选择镜像标签；无论集群内是否运行 kube-scheduler Pod，部署前都应检查渲染出的镜像是否能从目标离线环境获取。需要覆盖时，在 package values 中填写对应组件的镜像配置：

hami:
  scheduler:
    kubeScheduler:
      image:
        registry: your-registry.example.com
        repository: google_containers/kube-scheduler
        tag: v1.29.8

本离线包只内置 kube-scheduler:v1.37.0。目标集群需要其他版本时，应先准备匹配的镜像，并确认部署时填写的镜像地址可从目标离线 Registry 拉取；单独修改 tag 不会把镜像加入离线包。

非 NVIDIA 设备需要检查 HAMi values 中 devices 下的厂商开关；使用昇腾时必须启用以下两项。 在 package-values.yaml 中设置：

hami:
  devices:
    ascend:
      enabled: true
      hamiVnpuCore: true

kube-scheduler 镜像必须包含在交付包中，并在部署时导入 zarf init 指定的 Registry。 hami-system 中由 Zarf Agent 管理的工作负载会改写镜像地址；仅在 values 中填写其他仓库地址，不能补齐交付包中缺失的镜像。若目标 Kubernetes 版本需要其他镜像，请联系技术支持获取对应交付包。

执行部署

最小安装，仅部署 HAMi Enterprise 核心组件：

zarf package deploy hami-enterprise-v0.0.5-airgap-amd64.tar.zst \
  --components=hami \
  --values=package-values.yaml \
  --confirm

组件长时间未完成时，先区分镜像导入、Helm hook 和工作负载健康检查，再用 zarf tools helm、Pod 事件和日志诊断。values 错误时，修正 package-values.yaml 中对应组件的配置，重新 inspect 后再执行相同的部署命令。超过默认 15 分钟时，确认原因后按需设置 --timeout。

部署中断后，可以处理问题并用相同的 zarf package deploy ... --components=... --values=... 命令继续。镜像 digest 未变化时 Zarf 会跳过重复导入；Helm Charts 或 values 变化时会进行 Helm upgrade。

如果目标资源已经由其他 Helm release 管理，且确认要交由当前 Zarf 包接管，可在核对资源范围后使用 --take-ownership。--force-conflicts 只用于 Server-Side Apply 字段所有权冲突；它会覆盖其他 field manager 管理的字段，仅在确认冲突字段可以由本次部署接管时使用，不能作为通用重试参数。

启用 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 状态。

可选：NVIDIA GPU Operator

NVIDIA GPU Operator 是可选组件。驱动和 NVIDIA Container Toolkit 均由宿主机管理时，可不选择该组件。驱动、Toolkit 与 RuntimeClass 的配置取决于节点环境，参见 HAMi 的 NVIDIA 节点准备文档：中文、English。

不要启用 GPU Operator 的 CDI。 本交付使用 HAMi Enterprise 的 scheduler.useDownward 模式，与 CDI 不兼容。包内 GPU Operator 已关闭 CDI 和内置 device-plugin。复用集群已有 GPU Operator 时，也应检查这两项配置；调整已有集群的 CDI 设置前，先评估运行中的 GPU 工作负载。

HAMi 核心部署完成后，如需由本包安装 GPU Operator，可执行以下命令。首次部署时，也可以将 gpu-operator 与 hami 一同选择。使用 Slim 包时，GPU 节点须已安装兼容驱动。

zarf package deploy hami-enterprise-v0.0.5-airgap-amd64.tar.zst \
  --components=gpu-operator \
  --values=package-values.yaml \
  --confirm

可选：Ascend 组件

ascend-device-plugin 和 npu-exporter 均为默认关闭的可选组件，企业版及其 Slim 包均可按需选择。插件部署到 hami-system，使用已有的 hami-scheduler-device ConfigMap；Exporter 部署到 npu-exporter Namespace。已有同类组件时避免重复安装。仅使用 Ascend 节点的集群无需选择 GPU Operator；混合节点集群按需选择。

准备节点

NPU Exporter 适用于使用 containerd 的普通 Ascend 计算节点。目标节点需预装驱动、固件和运行时。Atlas 200I SoC A1 核心板需要上游单独提供的清单和启动脚本，不在该组件的适用范围内。

默认沿用插件的 ascend: "on" 节点标签，无需为 Exporter 单独打标签。containerd 默认目录为 /run/containerd。只有实际节点标签或运行时路径不同时，才需要覆盖 Exporter 配置。

安装器自动创建 Exporter 日志目录，并设置为 root:root、权限 0750，无需登录各节点手工建目录。安装使用 Zarf 和 Helm 的常规就绪检查；指标采集和监控接入按下文「验证」验收。

配置与部署

默认节点标签和 containerd 路径无需额外配置。保留按目标 NPU 型号、切分方式准备的 HAMi 配置。如节点运行时目录与默认值不同，在 package-values.yaml 的 npu-exporter.hostPaths.containerd 中填写实际路径。

需要同时安装 Ascend Device Plugin 和 NPU Exporter 时，选择以下两个组件；只需要其中一个时选择对应组件。首次部署可与 hami 一同选择。需要随包安装 Prometheus 时，另选 prometheus-crds,prometheus。使用与目标架构匹配的主包。

zarf package deploy <main-package.tar.zst> \
  --components=ascend-device-plugin,npu-exporter \
  --values=package-values.yaml --confirm

无需覆盖 values 时可省略 --values。已有插件时只选择 npu-exporter。如需使用交付包外的镜像，请联系技术支持获取包含该镜像的新交付包；仅在 values 中填写镜像地址不会将镜像加入离线包。

NPU Exporter 监控

Exporter 默认不创建 ServiceMonitor。可启用 Exporter 自带的 ServiceMonitor。使用包内监控时，确认已安装 prometheus-crds,prometheus。部署完成后，在 Prometheus 中确认目标和指标。不要同时启用两套指向同一 Exporter 的抓取。

npu-exporter:
  serviceMonitor:
    enabled: true

验证 Ascend 组件

kubectl -n hami-system get daemonsets
kubectl -n npu-exporter get daemonset npu-exporter
kubectl -n npu-exporter rollout status daemonset/npu-exporter --timeout=180s
kubectl -n npu-exporter get pods -o wide
kubectl -n npu-exporter get endpointslice -l kubernetes.io/service-name=npu-exporter

检查 Exporter DaemonSet 的 DESIRED 与 READY：二者应等于预期 Ascend 节点数，且大于零。在 Prometheus 中查询 up{job="npu-exporter",namespace="npu-exporter"} 和 npu_chip_info_utilization，确认各节点的抓取和指标正常；利用率为零可以表示设备空闲。设备插件还需验证注册情况，并运行申请对应 Ascend 资源的工作负载，确认设备分配与访问。

Exporter Pod Ready 不代表指标采集已接通。ServiceMonitor 创建后，Prometheus 配置同步和首次抓取需要一定时间。没有指标时检查驱动/DCMI；抓取失败时检查目标发现、配置重载、ServiceMonitor 标签、重复抓取及网络策略。

维护参考与非默认环境

以下信息用于环境检查和故障排查。containerd 挂载整个目录，socket 文件名保持 containerd.sock。

NetworkPolicy 允许各 Namespace 中带 app.kubernetes.io/name: prometheus 标签的 Pod 访问 TCP 8082，默认禁止网络出口，实际执行取决于 CNI。外部监控标签不同时覆盖 npu-exporter.networkPolicy.prometheusPodSelector；独立 ServiceMonitor 的选择标签通过 npu-exporter.serviceMonitor.labels 配置。

Exporter 使用 root、特权容器，并访问主机驱动、DCMI 和运行时 socket。只读挂载 socket 不会限制运行时 API 调用。DCMI 动态库及其父目录需由 root 持有，group 和 other 不可写。驱动升级前，先停止业务任务，再停止 NPU Exporter。

默认主机路径	用途	挂载访问方式
`/usr/local/Ascend/driver`	驱动动态库	只读
`/usr/local/dcmi`	DCMI 动态库	只读
`/sys`	设备信息	只读
`/run/containerd`	containerd 和 CRI socket	只读挂载目录
`/etc/localtime`	节点时区	只读
`/var/log/mindx-dl/npu-exporter`	Exporter 日志	可写

test -d /usr/local/Ascend/driver
test -d /usr/local/dcmi
test -S /run/containerd/containerd.sock

移除组件不会删除主机日志。容器根文件系统只读，/tmp 使用 emptyDir，不挂载 ServiceAccount token；这些设置不会消除特权容器的主机访问权限。

监控对接（可选）

已有 Prometheus 或 VictoriaMetrics 时，可沿用现有监控系统。需要由本包部署 kube-prometheus-stack 时，在 HAMi 核心部署后选择 prometheus-crds 和 prometheus；这两个组件不属于 HAMi 核心安装的必选项。

zarf package deploy hami-enterprise-v0.0.5-airgap-amd64.tar.zst \
  --components=prometheus-crds,prometheus \
  --values=package-values.yaml \
  --confirm

确认指标系统能采集所选硬件对应的 HAMi、DCGM-Exporter 或 NPU Exporter 指标。v0.0.5 离线包默认 hami.legacyMetrics=false；下表使用当前指标名。指标非空前，先检查相应采集目标 up=1。

使用 Prometheus 时，ServiceMonitor 的 metadata.labels 必须与 Prometheus 的 spec.serviceMonitorSelector 匹配，否则无法采集对应指标。

使用 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 和设备插件后，收集集群及设备信息以申请许可证。激活后再验证需要许可证的工作负载。

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

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 的售前/技术支持获取证书。

激活后验证

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 状态，并确认受管节点已注册加速卡资源。

示例工作负载验证

amd64 完整版外层 airgap 包包含 GPU Burn v0.0.2 和 vLLM Qwen v0.0.4 两个独立 Zarf 示例包；Slim 不包含示例。示例版本独立于主包 v0.0.5。先完成核心组件和真实设备分配验证，再部署示例。以下两个 NVIDIA 示例会创建工作负载，无需另行 kubectl apply；部署前确认早期版本在 default 中的同名资源可被示例包清理。vLLM Ascend 是单独提供的 arm64 镜像包，不会自动部署工作负载。

GPU burn 验证

zarf package deploy zarf-package-hami-example-gpu-burn-amd64-v0.0.2.tar.zst --confirm

GPU Burn 会运行 GPU 满载计算。部署后检查 Deployment / Pod、实际分配的 GPU 资源和 HAMi 日志；该测试不能替代长期稳定性或完整硬件验证：

kubectl -n hami-example get deploy turbo-gpu-burn
kubectl -n hami-example get pods -l app=turbo-gpu-burn
kubectl -n hami-example logs -l app=turbo-gpu-burn --tail=50

该示例会创建 hami-example/turbo-gpu-burn Deployment，请在验证完成后按需清理：

kubectl -n hami-example delete deploy turbo-gpu-burn

vLLM + Qwen 验证

zarf package deploy zarf-package-hami-example-vllm-qwen-amd64-v0.0.4.tar.zst --confirm

部署后检查推理服务状态：

kubectl -n hami-example get deploy vllm-qwen3
kubectl -n hami-example get pods -l app=vllm-qwen3
kubectl -n hami-example get svc vllm-qwen3-webui

待 Pod 就绪后，确认防火墙和集群网络允许 NodePort 30081，再访问 http://<node-ip>:30081/openwebui：

# 获取可访问的节点 IP
kubectl get nodes -o wide

# 浏览器访问
# http://<node-ip>:30081/openwebui

Open WebUI 与同 Pod 内的 vLLM 服务对接。打开页面后提交一次对话请求，确认模型返回内容；Pod Ready 本身不能证明推理请求成功。

如果 Pod 一直 Pending，优先检查证书是否已激活、GPU 节点是否已打 gpu=on 标签，以及节点 GPU 驱动是否正常。

排障

部署失败时，先查看 Pod、事件和 Zarf package 状态。查询 Helm release 时使用 zarf tools helm。诊断资料可能包含集群配置和日志，发送前请检查敏感信息，不要附带 Secret。

kubectl get pods -A | grep -E 'hami|gpu-operator|prometheus|vllm|gpu-burn'
kubectl get events -A --sort-by=.lastTimestamp | tail -50
zarf package list

按包内 COLLECT-CLUSTER-INFO.md 先通过 tools 安装 jq，并核对目标 kubeconfig。collector 不依赖 Python；使用 sudo 时必须显式传入 kubeconfig，避免访问 root 账号的默认集群。以下在已安装工具后收集信息：

KUBECONFIG_PATH="${KUBECONFIG:-$HOME/.kube/config}"
COLLECTOR_PATH="$PWD/collect-cluster-info.sh"
ROOT_PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin"

sudo env PATH="$ROOT_PATH" sh -c 'command -v kubectl >/dev/null && command -v jq >/dev/null'
sudo env KUBECONFIG="$KUBECONFIG_PATH" PATH="$ROOT_PATH" \
  "$COLLECTOR_PATH" > cluster-info.json
sudo /usr/local/bin/jq empty cluster-info.json

常见问题

现象	可能原因	处理
镜像拉取失败	Namespace 或工作负载未标记 `zarf.dev/agent: mutate`、Pod 在添加标签前已经创建，或镜像未包含在 Zarf package 中	检查 Namespace 或工作负载标签、Zarf Agent webhook 和日志，以及 Pod 的实际镜像地址。确认镜像已包含在 package 中。修正标签后重新创建 Pod。
`hami-device-plugin` Pod 为 `Pending` 或不存在	节点未添加 `gpu=on` 标签	运行 `kubectl label nodes <node> gpu=on`。
`hami-device-plugin` Pod 反复重启	与 NVIDIA GPU Operator 的默认 device-plugin 冲突	复用集群已有的 GPU Operator 时，检查其内置 device-plugin 是否已关闭。使用包内组件时，收集相关 Pod 日志与事件并联系技术支持排查。
无法查询 HAMi 指标	Prometheus 或 VictoriaMetrics 的 selector 与监控对象标签不匹配	检查监控组件的 selector，并确认其与 HAMi `ServiceMonitor` 的标签一致。
`nvidia-smi` 报错	GPU 驱动未就绪	使用完整版并由 GPU Operator 安装驱动时，检查 GPU Operator 的驱动 Pod。使用 Slim 时，检查节点已有驱动和容器运行时配置。
示例工作负载一直为 `Pending`	许可证未激活、GPU 资源不足或节点标签缺失	检查许可证状态、GPU 节点标签、可用 GPU 资源和 `kubectl describe pod` 事件。

使用 Zarf 安装组件带来的限制

镜像改写范围应通过标签明确控制

建议在初始化时使用 zarf init --agent-mutation-policy=labeled。此策略只改写带 zarf.dev/agent: mutate 标签的资源，或位于带该标签 Namespace 中的资源；需要保留原镜像地址的单个工作负载可标记 zarf.dev/agent: ignore，且资源标签优先于 Namespace 标签。因此，同一集群甚至同一 Namespace 中可以按资源划分是否由 Zarf 改写，不再需要让 Agent 默认接管全部业务 Namespace。需要注意：只有已经打入 Zarf package 的镜像才能在离线环境中被改写并拉取；修改标签后还需重新创建 Pod，已创建 Pod 不会自动变化。

同一批资源应由单一交付链管理

Zarf 通过 Helm 管理 package 中的 Chart release。对同一批 Kubernetes 资源再并行使用另一套原生 Helm 流程，仍可能产生 release ownership、字段所有权和升级顺序冲突。日常升级应继续使用新的 Zarf package；若确需把已有资源交给 Zarf 管理，应先核对 release 和资源范围，再使用 --take-ownership。--force-conflicts 仅用于确认可以覆盖的 Server-Side Apply 字段冲突，不应作为常规安装参数。

获取支持

邮箱：info@dynamia.ai
售前 / 技术支持：400-026-7800
已签订商业合同的客户请通过专属支持渠道提交 Issue

离线包内容​

前置条件清单​

解压、校验和安装 Zarf​

初始化 Zarf​

部署 HAMi Enterprise​

准备自定义配置​

执行部署​

启用 GPU 节点​

可选：NVIDIA GPU Operator​

可选：Ascend 组件​

NPU Exporter 监控​

验证 Ascend 组件​

监控对接（可选）​

验证指标采集​

证书获取​

激活后验证​

示例工作负载验证​

GPU burn 验证​

vLLM + Qwen 验证​

排障​

常见问题​

使用 Zarf 安装组件带来的限制​

镜像改写范围应通过标签明确控制​

同一批资源应由单一交付链管理​

获取支持​