Alauda Build of HAMi

Workload Controls

This page lists HAMi workload-side controls that are applied through pod annotations or container environment variables. Use them only with the backend and version that documents support for the control.

TOC

NVIDIA backend annotationsAscend backend annotationsNVIDIA backend environment variablesRelated pages

NVIDIA backend annotations

AnnotationPurposeExample
nvidia.com/use-gpuuuidRestricts scheduling to the listed GPU UUIDs."GPU-AAA,GPU-BBB"
nvidia.com/nouse-gpuuuidExcludes the listed GPU UUIDs from scheduling."GPU-AAA,GPU-BBB"
nvidia.com/use-gputypeRestricts scheduling to the listed GPU model names."A100,V100"
nvidia.com/nouse-gputypeExcludes the listed GPU model names."1080,2080"
hami.io/node-scheduler-policySelects the GPU node scheduling policy. Supported values are commonly binpack and spread."binpack"
hami.io/gpu-scheduler-policySelects the GPU device scheduling policy on the selected node. Supported values are commonly binpack and spread."spread"
nvidia.com/vgpu-modeSelects the NVIDIA HAMi device mode when the installed package documents multiple supported modes."hami-core"
WARNING

Do not use mode-specific annotations such as nvidia.com/vgpu-mode to enable experimental behavior unless the current Alauda Build of HAMi package and release notes explicitly support that behavior.

Pinning a workload to a GPU UUID also pins the workload to the node that hosts that GPU. Use this only when the workload really requires a specific device.

The following example restricts a HAMi workload to one of two NVIDIA GPU models while excluding a known device UUID:

metadata:
  annotations:
    nvidia.com/use-gputype: "A100,V100"
    nvidia.com/nouse-gpuuuid: "GPU-EXCLUDED"
spec:
  containers:
    - name: workload
      image: <your-gpu-image>
      resources:
        limits:
          nvidia.com/gpualloc: 1
          nvidia.com/gpucores: 50

Use comma-separated values when selecting multiple UUIDs or model names. The model string must match the value discovered by the installed NVIDIA stack.

Override the default node and GPU policies for a single workload only when it needs a different placement strategy:

metadata:
  annotations:
    hami.io/node-scheduler-policy: "spread"
    hami.io/gpu-scheduler-policy: "binpack"

Ascend backend annotations

HAMi generates Ascend UUID controls from the commonWord configured for the installed resource type:

Annotation patternPurpose
hami.io/use-<commonWord>-uuidRestricts allocation to the listed Ascend device UUIDs.
hami.io/no-use-<commonWord>-uuidExcludes the listed Ascend device UUIDs.

For example, replace the placeholders below with the commonWord and resource key from the installed device configuration:

metadata:
  annotations:
    "hami.io/use-<common-word>-uuid": "<device-uuid>"
spec:
  containers:
    - name: workload
      image: <your-ascend-image>
      resources:
        limits:
          "<ascend-resource-key>": 1

The annotation suffix must match the installed device configuration, and the resource key must match node allocatable resources. HAMi publishes registered device identifiers in node annotations such as hami.io/node-register-<commonWord>; do not assume they are identical to the identifiers displayed by every vendor tool.

NVIDIA backend environment variables

Environment variablePurposeDefault
GPU_CORE_UTILIZATION_POLICYControls how HAMi-Core applies the requested nvidia.com/gpucores limit. Common values are default, force, and disable.default
CUDA_DISABLE_CONTROLDisables HAMi-Core control inside the container for debugging. When enabled, resource isolation and limitation are not applied by HAMi-Core.false

Use CUDA_DISABLE_CONTROL only for diagnosis. It changes runtime enforcement behavior and should not be part of a normal production workload template.