Enterprise

This guide explains how to deploy HAMi commercial products with Helm on a Kubernetes cluster that can access the required Chart and image registries. It does not cover air-gapped installation.

💡 Installation does not equal activation. The components can run after Helm installation, but GPU virtualization and scheduling require license activation before they can be used.

Installation itself does not require a license. Complete the software deployment first, then apply for and import the license.

Without activation, vGPU partitioning and scheduling are unavailable, and functional verification will fail.

Why Choose Online Installation

Online installation is intended for teams that can operate Kubernetes, Helm, and image registries and need greater configuration flexibility. Component versions, deployment order, and values can be managed according to the organization infrastructure and change process.

The Zarf air-gapped package prepared by dynamia is better suited to network-isolated environments or deployments that require a single delivery artifact. Online Helm installation is more appropriate when the customer can operate the environment independently and needs to manage component versions, image sources, and configuration directly.

Deployment Scope and Prerequisites

Component Selection

Component	When to Install	Notes
HAMi Enterprise	Every cluster	Core scheduler and device plugin. Required.
NVIDIA GPU Operator	NVIDIA GPUs are used and the cluster does not already manage drivers and the container runtime	The default GPU Operator device plugin must not run together with the HAMi device plugin.
Ascend device plugin	Ascend nodes are used	Install after HAMi and reuse the HAMi device configuration ConfigMap.
Prometheus monitoring stack	HAMi or GPU metrics are required, or HAMi AI Platform will be installed	Do not install another stack if the cluster already has a compatible monitoring system.
HAMi AI Platform	A platform console, workload management, and monitoring views are required	Optional. Requires a Gateway API implementation and monitoring.

Prerequisite Checks

Kubernetes version 1.24 or later, with working kubectl and Helm on the administration host.
NVIDIA nodes already have the NVIDIA driver and NVIDIA Container Toolkit, or NVIDIA GPU Operator will install them.
Ascend nodes already have the vendor driver and runtime configured and are visible to Kubernetes. This guide installs only the HAMi Ascend device plugin.
When NVIDIA GPU Operator is used, its default device plugin must be disabled to avoid a conflict with HAMi.

kubectl cluster-info
kubectl get nodes -o wide
helm version

Online Installation

Before running the commands below, confirm that the current kubeconfig context points to the target cluster. Keep the values file for each Chart under version control. Contact Dynamia.ai technical support for access to commercial Charts, mainland China image registries, and production values.

Install NVIDIA GPU Operator (NVIDIA Nodes Only)

If GPU Operator is already installed, do not install it again, and confirm that devicePlugin.enabled=false. GPU Operator 25.10 and later enable CDI by default. The example below explicitly sets cdi.enabled=false to keep this deployment path in non-CDI mode. To use CDI, remove that setting and complete the HAMi-side configuration in Enable NVIDIA CDI support for HAMi before installing or upgrading HAMi. This guide does not duplicate those parameters or verification steps. cdi.default is deprecated and ignored in GPU Operator 25.10 and later.

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

Install the Monitoring Stack (When Needed)

If the cluster does not already have Prometheus or a compatible monitoring system and metrics collection is required, install 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

Install HAMi Enterprise

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

See the HAMi Helm Chart Values Reference for the complete configuration.

Install the Ascend Device Plugin (Ascend Nodes Only)

Complete the HAMi installation before this step. The following configuration reuses hami-scheduler-device so that multiple Charts do not manage the same device configuration.

nameOverride: "ascend-device-plugin"
fullnameOverride: "ascend-device-plugin"

image:
  repository: dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/dynamia-ai/ascend-device-plugin
  tag: "v1.3.0"
  pullPolicy: IfNotPresent

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.1.1 \
  --namespace hami-system \
  -f ascend-device-plugin.yaml

Enable GPU Nodes

HAMi device-plugin starts only on nodes labeled gpu=on. Run the following command for every GPU or Ascend node that HAMi should manage:

kubectl label nodes <node-name> gpu=on

Install HAMi AI Platform (Optional)

Run this section only when the platform console is required. Skip it for clusters that deploy only HAMi Enterprise.

Install Envoy Gateway

helm install eg \
  oci://docker.io/envoyproxy/gateway-helm \
  --version v1.6.2 \
  --namespace envoy-gateway-system \
  --create-namespace \
  --set global.images.envoyGateway.image=docker.io/envoyproxy/gateway:v1.6.2 \
  --set global.image.ratelimit.image=docker.io/envoyproxy/ratelimit:99d85510 \
  --set config.envoyGateway.gateway.controllerName=gateway.envoyproxy.io/gatewayclass-controller \
  --set config.envoyGateway.provider.type=Kubernetes

Install HAMi AI Platform

helm install kantaloupe \
  oci://dynamia-ai-registry.cn-hangzhou.cr.aliyuncs.com/public/charts/kantaloupe-chart \
  --version 0.18.3 \
  --namespace kantaloupe-system \
  --create-namespace \
  --set fullnameOverride=kantaloupe

See the kantaloupe Helm Chart Values Reference for service exposure, the platform administrator, authentication, and monitoring settings.

Post-Installation Checks

Core Components

kubectl -n hami-system get pods
kubectl -n gpu-operator get pods
kubectl -n monitoring get pods
kubectl -n kantaloupe-system get pods

A Namespace for an optional component may not exist if that component was not installed. Pods for installed components should be Running or Completed.

Nodes and Monitoring

kubectl describe node <node-name>
kubectl api-resources --api-group=monitoring.coreos.com

When Prometheus is used, the ServiceMonitor labels must match Prometheus.spec.serviceMonitorSelector. When VictoriaMetrics is used, the labels must match VMServiceScrape.spec.serviceScrapeSelector.

Query the following NVIDIA metrics in the monitoring system and confirm that the results are not empty:

DCGM_FI_DEV_GPU_UTIL
HostCoreUtilization
GPUDeviceCoreAllocated

HAMi AI Platform (Optional)

kubectl -n kantaloupe-system get pods
kubectl -n kantaloupe-system get svc

Open the platform through the service endpoint configured during deployment and confirm that the console loads successfully.

License Application and Activation

Obtain License Request Information

Run this step after all selected components have started. The environment requires kubectl and jq. Use either method below.

Download and Run the Script

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

Run a Local Copy

bash collect-hami-license-info.sh

The script outputs JSON in the following format:

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

Send the JSON output to Dynamia.ai sales or technical support to obtain the license.

Activate HAMi Enterprise

After receiving the license file, save it on an administration host that can access the target cluster, then create the license Secret:

kubectl create secret generic hami-license \
  --from-file=license=/path/to/license-file \
  -n hami-system

kubectl label secret hami-license \
  hami.io/license="true" \
  -n hami-system

kubectl get secret hami-license -n hami-system
kubectl get events --field-selector involvedObject.name=hami-license -n hami-system

A LicenseValid event indicates that license validation succeeded. For NVIDIA nodes, you can also inspect license registration:

kubectl get nodes -o custom-columns='NODE:.metadata.name,LICENSE:.metadata.annotations.hami\.io/nvidia-license'

Activate HAMi AI Platform (Optional)

Sign in to HAMi AI Platform with the platform administrator account.
Open License and System Information .
Follow the page instructions to obtain the license request information.
Send the request information to Dynamia.ai sales or technical support.
Complete activation according to the delivery instructions.

Post-Activation Verification

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'

A LicenseValid event indicates that license validation succeeded. Confirm that the selected component Pods are Running or Completed and that accelerator resources are registered on the managed nodes.

Online Sample Workload Verification

Before running this example, confirm that the target cluster can pull nvidia/cuda:12.4.0-base-ubuntu22.04. If the cluster uses a private registry, mirror the image first and update the image reference in the example.

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

If the Pod reaches Ready and the logs show GPU information, HAMi has scheduled the GPU and the NVIDIA runtime is available inside the container. Delete the test Pod after verification.

kubectl delete pod hami-smoke

Common Issues

Symptom	Checks and Resolution
`hami-device-plugin` is not running	Confirm that the node has the `gpu=on` label, then check `kubectl -n hami-system get pods`.
`hami-device-plugin` repeatedly restarts	Check whether NVIDIA GPU Operator still enables its default device plugin. Set `devicePlugin.enabled=false`.
Image pull fails	Check network access from the target cluster to the image registry, the image repository and tag, and any required `imagePullSecrets`.
HAMi metrics are unavailable	Check whether the Prometheus or VictoriaMetrics selector matches the labels on the monitoring object.
A workload remains `Pending`	Check license activation, the `gpu=on` node label, available accelerator resources, and events from `kubectl describe pod`.

Support

Email: info@dynamia.ai
Sales / technical support: 400-026-7800
Customers with active commercial agreements should submit support requests through their dedicated support channel.

Deployment Scope and Prerequisites

Component Selection​

Prerequisite Checks​

Online Installation

Install NVIDIA GPU Operator (NVIDIA Nodes Only)​

Install the Monitoring Stack (When Needed)​

Install HAMi Enterprise​

Install the Ascend Device Plugin (Ascend Nodes Only)​

Enable GPU Nodes​

Install HAMi AI Platform (Optional)​

Install Envoy Gateway​

Install HAMi AI Platform​