AI Platform

HAMi 平台版离线部署手册

本文档面向 SRE / 平台工程师，说明如何使用 All-in-One 离线包在 Kubernetes 集群中部署 HAMi AI Platform ，并完成证书激活、GPU 节点启用和示例工作负载验证。

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

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

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

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

离线包内容

外层交付包命名格式为：

以下示例使用 v0.0.5、amd64 和完整版包。Slim 外层包为 hami-ai-platform-slim-v0.0.5-airgap-amd64.tar.gz，不包含示例包和 NVIDIA 驱动镜像，但保留 GPU Operator。选择 Slim 时，GPU 节点须已安装兼容的 NVIDIA 驱动。

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

当前 hami-ai-platform-v0.0.5-airgap-amd64.tar.gz 中包含以下关键文件：

文件	用途
`zarf-linux-amd64`	Linux amd64 Zarf CLI
`zarf-init-amd64-v0.86.0.tar.zst`	Zarf init 离线包
`hami-ai-platform-v0.0.5-airgap-amd64.tar.zst`	HAMi AI Platform 主部署包
`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 示例验证包
`kantaloupe/`	kantaloupe values 示例和完整 values 说明文档
`hami/README.md`	hami-enterprise 完整 values 说明文档
`collect-hami-license-info.sh`	证书申请信息收集脚本
`collect-cluster-info.sh`	集群诊断信息收集脚本
`package-values.yaml`	按组件分组的配置模板
`PACKAGE-VALUES.md`	组件映射和旧配置迁移说明
`COLLECT-CLUSTER-INFO.md`	集群信息收集脚本使用说明

前置条件清单

类型	要求	验证命令
Kubernetes	v0.0.5 离线包要求 Kubernetes ≥ 1.27，并提供可用的默认 StorageClass。	`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；选择 `prometheus-crds` 组件可由离线包安装	`kubectl api-resources --api-group=monitoring.coreos.com`
GPU Operator	已有 GPU Operator 时，确认其内置 device-plugin 和 CDI 已关闭，避免与当前 HAMi Enterprise 部署冲突。完整版和 Slim 包都保留 `gpu-operator` 组件；Slim 不含 NVIDIA 驱动镜像，GPU 节点须已安装兼容驱动。	`zarf tools helm list -A`
存储空间	建议大于 30 GB	`df -h`

HAMi 自带的 NVIDIA device-plugin 与 GPU Operator 内置 device-plugin 不应同时启用。在线 Helm 配置使用 devicePlugin.enabled=false；v0.0.5 package values 中对应 gpu-operator.devicePlugin.enabled=false，包内默认已禁用。集群还需有可用的默认 StorageClass。

解压、校验和安装 Zarf

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

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

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

# 进入解压目录
cd hami-ai-platform-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 AI Platform

本包没有必选组件；所有组件默认关闭。部署时按场景通过 --components 显式选择。填写组件 values 不会自动安装该组件。

组件清单如下：

组件名称	说明	必须安装	推荐安装
`tools`	运维工具集：jq、nerdctl 等	否	按需
`hami`	hami-enterprise Helm Chart	否	是
`ascend-device-plugin`	Ascend Device Plugin	否	Ascend 集群按需
`npu-exporter`	Ascend NPU 指标采集	否	需要 NPU 指标时安装
`prometheus-crds`	Prometheus Operator CRD	否	需要随包安装 Prometheus 时选择
`prometheus`	kube-prometheus-stack Helm Chart	否	按需
`gpu-operator`	NVIDIA GPU Operator	否	NVIDIA 场景按需选择；Slim 需预装兼容驱动
`envoy-gateway-crds`	Gateway API 与 Envoy Gateway CRD	否	启用平台 Gateway 时安装
`envoy-gateway`	Envoy Gateway	否	启用平台 Gateway 时安装
`hami-ai-platform`	HAMi AI Platform（Kantaloupe）	否	是

envoy-gateway-crds 使用 Envoy Gateway v1.6.2 官方 CRD Chart 的固定渲染结果，在 Helm release 之外通过 Server-Side Apply 管理 12 个 Gateway API v1.4.1 Experimental CRD 和 8 个 Envoy Gateway CRD，避免大型 CRD 导致 Helm release Secret 超过 Kubernetes 1 MiB 上限。若目标集群已经安装 Gateway API，则不会覆盖现有版本，但会检查所需的 12 个 CRD 是否齐全；Envoy Gateway CRD 会幂等更新并等待 Established。envoy-gateway 使用已移除 crds/ 的官方主 Chart 副本，避免重复安装或降级 CRD。

Zarf v0.86.0 直接支持 --values。主包 v0.0.5 起，配置必须放在同名组件键下；每个子对象按 sourcePath 传给对应 Chart，再合并到 Chart 根级 values。覆盖优先级为：Chart 默认值 → 包内 valuesFiles → 对应组件的 package values。需要命令行覆盖时，同样使用完整组件路径，例如 --set-values hami.scheduler.leaderElect=true。

工具和 CRD 组件没有 Chart values 映射。平台的认证和入口分别使用 hami-ai-platform.auth、hami-ai-platform.gateway；Envoy Gateway 控制器配置使用独立的 envoy-gateway 键。

准备 custom values

从外层归档的 package-values.yaml 模板开始，按 PACKAGE-VALUES.md 填写需要覆盖的组件。模板中七个组件均为空对象；不需要覆盖时可以省略 --values。v0.0.4 及更早配置中的根级 scheduler、nodeSelector、global 等不会传给 v0.0.5 的 Chart，必须分别移到目标组件键下。

`hami-enterprise` values

从包内 package-values.yaml 模板开始配置，完整说明见 PACKAGE-VALUES.md。七个顶层键彼此独立：

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

工具和 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.devices 下开启对应厂商。昇腾节点必须配置以下两项：

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

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

从 v0.0.4 及更早版本迁移时，裸露的 scheduler、nodeSelector、global 等根级键不会再传给 Chart。把每个 Chart 的配置移到对应组件下；hami/ 和平台版的 kantaloupe/ 示例也需这样转换。仅迁移 HAMi 时可执行：

zarf tools yq '{"hami": .}' hami-current-values.yaml > package-values.yaml

多个 Chart 原先共用的键应分别设置；例如 Prometheus Operator 使用 prometheus.prometheusOperator，Kantaloupe 使用 hami-ai-platform。

`kantaloupe` values

包内 kantaloupe/README.md 提供完整 Chart values 说明。下方示例及包内 kantaloupe/、hami/ 示例使用 Chart 原生结构。用于 Zarf v0.0.5 主包时，分别放在 hami-ai-platform 和 hami 顶层键下；直接执行 Helm 安装时仍使用 Chart 原生结构。下方示例中的根级 auth、gateway 等配置不能直接作为 package values。

kantaloupe 由于需要配置功能特性、服务暴露、监控指标采集等功能，配置项较多，请按需配置，完整 values 配置请见 kantaloupe Helm Chart Value Reference。

以下示例用于 v0.0.5 离线部署。请将以下 Kantaloupe 配置放在 package-values.yaml 的 hami-ai-platform 键下，例如 hami-ai-platform.auth 和 hami-ai-platform.gateway。Envoy Gateway 控制器配置使用顶层 envoy-gateway 键。

配置默认平台管理员信息

auth:
  jwtSecret: "<JWT_SIGNING_SECRET>"
  bootstrapAdminUsername: "bootstrap-platform-admin"
  bootstrapAdminPassword: "<ADMIN_PASSWORD>"
  bootstrapAdminFullName: "Platform Administrator"
  bootstrapAdminEmail: "admin@email.com"

使用 envoy-gateway NodePort 暴露服务，在集群外部使用LoadBalancer（云厂商负载均衡、自建负载均衡等）转发四层流量 。

gateway:
  enabled: true
  hostnames:
    - your-domain.example.com
  apiserverCors:
    enabled: true
    allowCredentials: true
    allowOrigins:
      - https://your-domain.example.com
  envoy:
    service:
      ports:
        http:
          nodePort: 30080
        https:
          nodePort: 30443
      type: NodePort
  listeners:
    - name: http
      port: 80
      protocol: HTTP
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRef:
          name: your-domain-tls-secret
        redirectFromHttp: true

使用 envoy-gateway NodePort 暴露服务，简单 PoC

gateway:
  enabled: true
  listeners:
    - name: http
      port: 80
      protocol: HTTP
  envoy:
    service:
      type: NodePort
      ports:
        http:
          nodePort: 30080

使用云厂商或裸金属服务提供的负载均衡 controller 接手的 LoadBalancer service

gateway:
  enabled: true
  hostnames:
    - your.domain
  listeners:
    - name: http
      port: 80
      protocol: HTTP
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        certificateRef:
          name: your-tls-secret
        redirectFromHttp: true
  envoy:
    service:
      type: LoadBalancer
      ports:
        http: {}
        https: {}

替换 prometheus Query API addr（默认为 http://prometheus-kube-prometheus-prometheus.monitoring.svc.cluster.local:9090）

apiserver:
  prometheusAddr: http://your-prometheus-query-api.com:9090

controllerManager:
  prometheusAddr: http://your-prometheus-query-api.com:9090

将本次配置整理为 package-values.yaml。以下示例分别配置 HAMi、平台认证和平台 Gateway；按实际环境调整，并在部署前替换认证占位符：

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

hami-ai-platform:
  auth:
    enabled: true
    jwtSecret: "<JWT_SIGNING_SECRET>"
    bootstrapAdminUsername: "<ADMIN_USERNAME>"
    bootstrapAdminPassword: "<ADMIN_PASSWORD>"
  gateway:
    enabled: true
    listeners:
      - name: http
        port: 80
        protocol: HTTP
    envoy:
      service:
        type: NodePort
        ports:
          http:
            nodePort: 30080
  hamiNamespace: hami-system

如需核对自定义配置，可用相同的 --components 和 --values 查看各 Chart 收到的 values 与渲染结果。以下示例选择 HAMi、Gateway 和平台服务；可选硬件与监控组件按需加入。

zarf package inspect values-files hami-ai-platform-v0.0.5-airgap-amd64.tar.zst \
  --components=hami,envoy-gateway-crds,envoy-gateway,hami-ai-platform \
  --values=package-values.yaml
zarf package inspect manifests hami-ai-platform-v0.0.5-airgap-amd64.tar.zst \
  --components=hami,envoy-gateway-crds,envoy-gateway,hami-ai-platform \
  --values=package-values.yaml

执行部署

首次部署平台服务时，选择 HAMi 核心、Gateway CRD、Envoy Gateway 和 HAMi AI Platform。已有 HAMi Enterprise 时，使用下方增量安装命令。GPU Operator、Ascend 组件和监控栈均按需单独选择。

zarf package deploy hami-ai-platform-v0.0.5-airgap-amd64.tar.zst \
  --components=hami,envoy-gateway-crds,envoy-gateway,hami-ai-platform \
  --values=package-values.yaml \
  --confirm

如果集群已经部署 HAMi Enterprise，后续只需要加装 Gateway 和 AI Platform：

zarf package deploy hami-ai-platform-v0.0.5-airgap-amd64.tar.zst \
  --components=envoy-gateway-crds,envoy-gateway,hami-ai-platform \
  --values=package-values.yaml \
  --confirm

可选：NVIDIA GPU Operator

GPU Operator 与 Ascend 组件一样按需安装。节点已有兼容驱动、NVIDIA Container Toolkit 和运行时配置时可跳过。较复杂的 values 取舍参见 HAMi NVIDIA GPU 节点准备文档。当前 Enterprise 使用 scheduler.useDownward，不要启用 CDI；包内 GPU Operator 已关闭 CDI 和自身的 device-plugin。Slim 包也可选择 GPU Operator，但 GPU 节点须已安装兼容驱动。

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

可选：Ascend 组件

ascend-device-plugin 和 npu-exporter 均为默认关闭的可选组件，企业版、AI 平台版及其 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 中填写镜像地址不会将镜像加入离线包。

监控对接

Kantaloupe 管理的集群： Exporter 默认不创建 ServiceMonitor，由平台管理本地和成员集群的采集。Service 位于 npu-exporter Namespace，标签和端口与平台默认模板一致，无需手工编写抓取清单。

数据面每接入一种新的厂商设备，都需要在控制面 Kantaloupe 打开对应厂商的 monitor 开关，并执行 Helm upgrade。Ascend 使用以下配置；即使控制面没有 Ascend 设备，也要开启，以启用成员集群指标所需的转换规则。通过 Zarf 更新平台时放在 hami-ai-platform 下；直接 Helm upgrade 时去掉该顶层键，并保留已有配置。

hami-ai-platform:
  monitoring:
    enabled: true
    vendorServiceMonitor:
      enabled: true
      enableAscendServicemonitor: true

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

npu-exporter:
  serviceMonitor:
    enabled: true

验证

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 资源的工作负载，确认设备分配与访问。

Kantaloupe 场景还需在控制面查询成员集群的原始 npu_chip_info_* 和转换后的 kantaloupe_gpu_core_used{vendor="ascend",cluster="<成员集群名称>"}。仅有 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；这些设置不会消除特权容器的主机访问权限。

组件长时间未完成时，先区分镜像导入、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 状态。

监控对接

监控栈是可选组件。集群已有兼容的 Prometheus 或 VictoriaMetrics 时，对接现有系统即可。需要随包安装 kube-prometheus-stack 时，一并选择 prometheus-crds 和 prometheus：

zarf package deploy hami-ai-platform-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 字段匹配，否则 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`	返回非空值

除了 exporter 的指标，还需要查询 kantaloupe_gpu_temp 验证 kantaloupe 服务指标是否被正确采集。

证书获取

HAMi 核心与平台服务就绪后即可获取授权申请信息；按需安装的 GPU Operator、昇腾及监控组件不构成前置条件。

使用平台管理员账号登录 HAMi AI Platform。
进入 License 与系统信息页面。
按照页面提示获取授权申请信息。
将授权申请信息发送给密瓜智能销售或交付人员。
根据指引完成激活。

激活后验证

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

HAMi AI Platform验证

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

# 2. 服务可达
kubectl -n kantaloupe-system get svc

HAMi AI Platform 服务暴露后，打开站点，确认前后端正常工作。

创建工作负载

在控制台工作负载 页面创建应用（如 gpu-burn）。离线环境中，镜像必须已进入相应 Zarf package 或目标可访问的内网 Registry；使用 Zarf 镜像改写时，业务 Namespace 需有 zarf.dev/agent: mutate 标签。

创建完成后，确认以下验证项均通过：

创建成功 ，控制台无报错
负载列表 ：应用状态、检索、列表指标与监控面板（GPU SM / GPU MEM / CPU / Memory）正常，时间切换与图表符合预期

应用详情 ：基础信息、资源总览、与监控数据正常；从详情页跳转 GPU / 节点页面，资源总览与监控数据正常

示例工作负载验证

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 已设置 `devicePlugin.enabled=false`。
无法查询 HAMi 指标	Prometheus 或 VictoriaMetrics 的 selector 与监控对象标签不匹配	检查监控组件的 selector，并确认其与 HAMi `ServiceMonitor` 的标签一致。
`nvidia-smi` 报错	GPU 驱动未就绪	检查 `gpu-operator` Namespace 中的 driver Pod 状态。
示例工作负载一直为 `Pending`	许可证未激活、GPU 资源不足或节点标签缺失	检查许可证状态、GPU 节点标签、可用 GPU 资源和 `kubectl describe pod` 事件。
`Gateway` 没有入口地址	Gateway API 或 Envoy Gateway CRD 未就绪、Envoy Gateway release 异常，或 Envoy Service 类型不适配集群	检查 20 个相关 CRD 的 `Established` 状态，运行 `zarf tools helm status eg -n envoy-gateway-system`，并检查 `Gateway` 条件和 Envoy `Service`。不要通过卸载 CRD release 或删除 CRD 重试。

使用 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 AI Platform​

准备 custom values​

hami-enterprise values​

kantaloupe values​

执行部署​

可选：NVIDIA GPU Operator​

可选：Ascend 组件​

启用 GPU 节点​

监控对接​

验证指标采集​

证书获取​

激活后验证​

HAMi AI Platform验证​

创建工作负载​

示例工作负载验证​

GPU burn 验证​

vLLM + Qwen 验证​

排障​

常见问题​

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

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

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

获取支持​