Enterprise

开源升级商业版本

本文介绍如何将通过 Helm 部署的 HAMi 开源版升级为 HAMi Enterprise。先在现有集群上采集许可证信息、申请并导入许可证，再执行 Helm 升级。升级沿用现有 Helm release 和命名空间，重点核对资源名称、调度器端口及设备插件配置。

本文适用于 NVIDIA GPU 场景。通过其他方式部署 HAMi、同时迁移命名空间，或需要启用其他设备类型时，请先联系密瓜智能技术支持确认迁移方案。

升级对业务的影响

升级包括两个阶段：

升级 HAMi 组件：更新调度器和设备插件，并检查已有业务 Pod 的状态。
更新业务 Pod 使用的运行库：在业务允许的窗口内重建 Pod，使新 Pod 使用商业版的 libvgpu.so。

升级前，请评估调度器和设备插件更新对新建 Pod 的影响，并为业务 Pod 重建安排维护窗口。升级后，分别检查已有业务的运行状态，以及新建 Pod 的 GPU 调度和运行库版本。完成这两项检查及业务验收后，再结束升级。

升级前准备

开始前，确认以下条件：

当前 HAMi 由 Helm 管理，已记录 release 名称、命名空间、Chart 版本和应用版本。
已取得目标 HAMi Enterprise Chart 包及对应镜像，并确认 GPU 节点能够拉取镜像。
已与密瓜智能技术支持确认源版本到目标版本的升级方案及许可证授权范围，并预留许可证签发时间。
已备份当前配置，并保存原 Chart 包及镜像，供回退使用。
已记录业务 Pod 的状态、重启次数和 GPU 业务验证结果。

本文命令使用以下变量。将示例值替换为当前环境的实际值；升级时不要改用新 release 或新命名空间。

RELEASE=hami
NAMESPACE=kube-system
CHART_PACKAGE=./hami-enterprise-<chart-version>.tgz
VALUES_FILE=./enterprise-values.yaml

采集信息并申请许可证

在现有开源 HAMi 集群上提前完成许可证申请，无需等到商业版部署后再采集信息。执行终端需安装 kubectl、jq，能够访问目标集群，并具有读取 kube-system Namespace 和 Node 信息的权限。确认需要授权的 GPU 已由 HAMi 设备插件注册。

从离线交付包中取得 collect-hami-license-info.sh，也可在联网机器上下载采集脚本后传入目标环境。在脚本所在目录执行以下命令，生成许可证申请文件。

bash collect-hami-license-info.sh > hami-license-info.json

核对 hami-license-info.json 中 deviceInstances 的 GPU 数量、UUID 和型号，确保覆盖本次需要授权的全部 NVIDIA GPU。如果列表为空或缺少设备，先检查设备插件的注册状态和节点注解，再重新采集。

脚本还会输出 deviceModels，用于记录仅按型号授权的设备及其物理卡数。纯 NVIDIA 集群的该字段为空。

将核对后的 hami-license-info.json 发送给密瓜智能售前或技术支持申请许可证。收到许可证文件后，确认授权的集群、设备范围和有效期符合本次升级要求，再继续导入。申请流程见许可证申请与激活验证手册。

升级前导入许可证

在执行 helm upgrade 前，将收到的许可证导入现有 release 的命名空间。本文使用 $NAMESPACE 表示该命名空间；不要改用许可证手册中的示例命名空间 hami-system。

将 LICENSE_FILE 设置为实际文件路径。以下命令创建或更新 hami-license Secret，并添加商业版识别许可证所需的标签：

LICENSE_FILE=./hami-license.lic

kubectl create secret generic hami-license \
  -n "$NAMESPACE" \
  --from-file=license="$LICENSE_FILE" \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl label secret hami-license \
  -n "$NAMESPACE" \
  hami.io/license=true --overwrite

检查 Secret 中的许可证数据项和标签：

kubectl describe secret hami-license -n "$NAMESPACE"

确认输出中的 Labels 包含 hami.io/license=true，Data 下存在 license 项，且字节数大于 0。此时完成的是许可证预置；开源 HAMi 不会产生商业版的 LicenseValid 校验事件，需在商业版组件启动后检查。许可证尚未收到或 Secret 导入失败时，不要执行升级，以免在升级期间等待签发或导入，延长业务恢复时间。

记录版本并备份配置

helm version
kubectl version
helm list -A
helm history "$RELEASE" -n "$NAMESPACE"
helm get values "$RELEASE" -n "$NAMESPACE" -o yaml > hami-user-values.yaml
helm get values "$RELEASE" -n "$NAMESPACE" --all -o yaml > hami-computed-values.yaml
helm get manifest "$RELEASE" -n "$NAMESPACE" > hami-manifest-before.yaml
kubectl get pods,deploy,ds,svc -n "$NAMESPACE" -o wide

记录 helm history 中升级前的成功 revision。hami-user-values.yaml 保存用户配置，hami-computed-values.yaml 用于检查包含默认值的完整配置。备份文件可能包含敏感配置，应妥善保存。

记录升级前的业务状态

选择有代表性的 GPU 业务 Pod，记录所在节点、Pod UID、重启次数及服务响应。对于使用 HAMi 运行库的容器，可记录运行库校验和：

kubectl get pod <pod-name> -n <workload-namespace> -o wide
kubectl get pod <pod-name> -n <workload-namespace> \
  -o jsonpath='{.metadata.uid}{"\n"}{.status.containerStatuses[*].restartCount}{"\n"}'
kubectl exec -n <workload-namespace> <pod-name> -c <container-name> -- \
  sha256sum /usr/local/vgpu/libvgpu.so

运行库路径以实际挂载为准；容器内需具备 sha256sum。同时执行业务自身的健康检查或一次推理请求，保存结果供升级后对比。

准备商业版配置

先查看目标 Chart 元数据和默认配置：

helm show chart "$CHART_PACKAGE"
helm show values "$CHART_PACKAGE" > enterprise-default-values.yaml

根据商业版 Chart 的配置结构编写 enterprise-values.yaml，逐项迁移开源版的自定义配置。不要直接把开源版完整 values 当作商业版配置，也不要使用 --reuse-values 代替配置核对。

需要保持一致的配置

配置	核对要求
release 名称与命名空间	沿用现有值，避免新建另一套部署。
`fullnameOverride`	结合目标 Chart 的渲染结果，确保已有资源名称保持一致。示例值为 `hami`，需按现有资源名称调整并核对渲染结果。
`scheduler.service.httpTargetPort`	与现网端口及新旧调度器的监听配置核对，避免滚动升级期间 Service 将请求转发到错误端口。示例值 `443` 需按现网配置核对。
`scheduler.kubeScheduler.image`	选择与当前 Kubernetes 版本匹配的 kube-scheduler 镜像。
`devicePlugin.runtimeClassName`	与当前 NVIDIA 容器运行时配置保持一致。
`devicePlugin.nvidiaDriverRoot`	与当前 GPU 驱动挂载路径保持一致。
`devicePlugin.gpuOperatorToolkitReady.enabled`	根据现有 GPU Operator / Toolkit 部署方式核对。
`devicePlugin.nvidiaNodeSelector`	保留实际 GPU 节点选择条件，避免设备插件部署范围发生变化。
镜像地址与拉取凭据	核对商业版镜像版本、仓库地址和所需的 `imagePullSecrets`。

以下 YAML 为升级配置示例。<enterprise-image-tag> 和 <kube-scheduler-tag> 必须替换为实际版本；其余值也需按现网配置核对。

fullnameOverride: hami

global:
  imageTag: "<enterprise-image-tag>"
  # 使用需要认证的镜像仓库时，填写已创建的 Secret 名称。
  # imagePullSecrets:
  #   - ghcr-pull-secret

devicePlugin:
  runtimeClassName: nvidia
  nvidiaDriverRoot: /
  gpuOperatorToolkitReady:
    enabled: true
  nvidiaNodeSelector:
    gpu: "on"

scheduler:
  kubeScheduler:
    image:
      registry: registry.k8s.io
      repository: kube-scheduler
      tag: "<kube-scheduler-tag>"
  service:
    httpTargetPort: 443

dra:
  enabled: false
devices:
  ascend:
    enabled: false
platform:
  openshift: false
selinux:
  enabled: false

此示例适用于未启用 DRA、昇腾设备支持、OpenShift 和 SELinux 集成的部署，因此将这些配置设为 false。如果现网依赖其中任何一项能力，请保留所需配置，并先确认对应升级方案。

检查渲染结果

helm template "$RELEASE" "$CHART_PACKAGE" \
  -n "$NAMESPACE" \
  -f "$VALUES_FILE" \
  --is-upgrade > hami-manifest-after.yaml

diff -u hami-manifest-before.yaml hami-manifest-after.yaml

diff 在存在差异时返回非零退出码，这是正常现象。重点检查：

现有 Deployment、DaemonSet、Service、ConfigMap、RBAC 和 Webhook 的名称是否发生变化。
Service 的 selector、端口和 targetPort 是否与滚动期间的新旧 Pod 匹配。
设备插件的节点选择条件、RuntimeClass 和驱动路径是否正确。
镜像地址和版本是否符合交付要求。
新增或删除的资源是否符合升级方案。

本地渲染仅用于检查清单，不能替代集群内的升级验证。发现资源意外改名、端口不一致或非预期删除时，先修正配置，再执行升级。

执行升级

确认许可证已收到，且 hami-license Secret 已在 $NAMESPACE 中导入并通过上述数据项和标签检查后，在约定的维护窗口内执行升级。沿用同一个 release 和命名空间。以下命令适用于 Helm 3：

helm upgrade "$RELEASE" "$CHART_PACKAGE" \
  -n "$NAMESPACE" \
  -f "$VALUES_FILE" \
  --atomic \
  --wait \
  --timeout 10m

使用 Helm 4 时，将 --atomic 替换为 --rollback-on-failure。两者均用于升级失败时回退；10m 是示例等待时间，应按镜像拉取和组件启动所需时间调整。

升级后检查 release 和组件状态：

helm status "$RELEASE" -n "$NAMESPACE"
helm history "$RELEASE" -n "$NAMESPACE"
kubectl get pods,deploy,ds,svc -n "$NAMESPACE" -o wide

确认 HAMi 调度器和设备插件已使用目标镜像并完成更新。若组件未就绪，先查看对应 Pod 的事件和日志，不要继续重建业务 Pod。

升级后验证许可证

商业版组件启动后，检查升级前已导入许可证的校验事件：

kubectl get events -n "$NAMESPACE" \
  --field-selector involvedObject.name=hami-license

确认出现 LicenseValid 事件，且许可证产品、授权范围和到期时间正确。仅有 Secret 存在不能证明许可证有效。许可证未通过校验时，先完成排查，再进行新业务 Pod 验证。

验证业务并更新运行库

检查已有业务 Pod

按照「记录升级前的业务状态」中的命令，核对 Pod UID、重启次数、业务响应和 libvgpu.so 校验和。

已有业务 Pod 的检查完成后，继续验证重建后的 Pod。检查新 Pod 的调度结果和运行库版本，确认其已使用目标商业版运行库。

分批重建业务 Pod

先选择一个可在维护窗口内重建的工作负载，按其控制器和业务发布流程重建 Pod。对于 Deployment，可以执行：

kubectl rollout restart deployment/<deployment-name> -n <workload-namespace>
kubectl rollout status deployment/<deployment-name> -n <workload-namespace> --timeout=10m

等待新 Pod 就绪后，检查新 Pod 的运行库校验和，并与目标商业版交付物核对。校验和变化本身不能证明版本正确；还需确认实际使用的运行库与目标版本一致。

完成一次实际 GPU 任务或推理请求，验证资源申请、调度及业务响应。验证通过后，再按业务发布计划逐步重建其他工作负载。

验收清单

Helm release 状态为 deployed，HAMi 组件已更新到目标版本。
许可证校验成功，授权范围和到期时间符合预期。
升级期间保留的业务 Pod 状态与业务响应符合预期。
新建业务 Pod 能够完成 GPU 调度，且使用目标商业版运行库。
业务自身的健康检查和实际请求验证通过。

升级失败处理

若升级命令失败，先通过 helm history 和组件状态确认自动回退结果。不要仅凭命令退出就假定环境已恢复。

如果需要手动回退，在确认升级前成功 revision 和业务影响后执行：

helm rollback "$RELEASE" <previous-revision> \
  -n "$NAMESPACE" \
  --wait \
  --timeout 10m

Helm 回退后，仍需重新检查组件状态和业务响应。若业务 Pod 已在升级后重建，还需单独核对其运行库版本，并按回退方案安排业务 Pod 重建；不能将 Helm release 回退视为业务运行库已经恢复。

遇到资源归属冲突、资源意外重建、许可证校验失败或 GPU 业务异常时，保留 Helm 历史、values、Pod 事件和日志，通过客户专属支持渠道联系密瓜智能技术支持。

升级对业务的影响​

升级前准备​

采集信息并申请许可证​

升级前导入许可证​

记录版本并备份配置​

记录升级前的业务状态​

准备商业版配置​

需要保持一致的配置​

检查渲染结果​

执行升级​

升级后验证许可证​

验证业务并更新运行库​

检查已有业务 Pod​

分批重建业务 Pod​

验收清单​

升级失败处理​