跳转到文档内容
版本：下一个

配置

本文按配置对象说明 HAMi 的常用配置和修改方式。完整参数、默认值和限制以 Chart values 参数表为准，配置示例见 values.yaml。

配置对象修改位置
调度器及配套组件Helm values 中的 scheduler.* 等
各厂商设备插件与设备参数Helm values 中的 devicePlugin.*、devices.<vendor>.*，以及独立部署的厂商插件配置
节点 ConfigMapdevicePlugin.nodeConfiguration
Pod 的 labels 与 annotations业务 Pod 的 metadata
容器环境变量业务容器的 env

本文对应 Next 开发版本，以上源码链接指向开发分支。使用已发布 Chart 时，选择匹配版本的文档，并查看该版本的默认值：

helm show values hami-charts/hami --version <chart-version>

将所需配置合并到 my-values.yaml，通过 --values my-values.yaml 传入 Helm。映射可以局部覆盖，列表会整体替换；合并示例时，同一顶层键只保留一份。首次部署见安装指南，已有部署的配置更新见升级指南。

调度器及配套组件的 Chart 配置​

调度器的常见调整包括部署位置、副本数和默认调度策略。例如，将两个副本部署到带有 hami.io/scheduler=true 标签的节点：

scheduler:
  nodeSelector:
    hami.io/scheduler: "true"
  leaderElect: true
  replicas: 2
  defaultSchedulerPolicy:
    nodeSchedulerPolicy: binpack
    gpuSchedulerPolicy: spread

多副本必须启用 leaderElect，并准备足够的匹配节点和资源。nodeSelector 控制调度器 Pod 的部署位置，不是业务 GPU Pod 的节点选择条件。

默认调度策略​

nodeSchedulerPolicy 控制节点选择，默认 binpack；gpuSchedulerPolicy 控制节点内的设备选择，默认 spread。binpack 倾向集中分配，spread 倾向分散分配。Pod 注解可以覆盖这些默认值，其他策略及组合方式见调度策略。

镜像、CPU 和内存资源、Webhook 范围、证书、服务端口和监控通常可以保留默认配置。需要调整时，在 Chart values 参数表中查找 global.*、scheduler.* 和 prometheus.*。

调度器性能分析​

需要排查性能问题时，将 --profiling 加入 scheduler.extender.extraArgs。该列表会整体替换，需保留部署中已有的其他参数：

scheduler:
  profilingBindAddress: "127.0.0.1:6060"
  extender:
    extraArgs:
      - --debug
      - -v=4
      - --profiling

配置生效后，调度器在 127.0.0.1:6060 提供独立的 HTTP pprof 服务。pprof 没有身份认证，应保持回环监听，通过端口转发访问。将 <namespace> 替换为 HAMi 所在命名空间，<scheduler-pod> 替换为目标调度器 Pod 名称：

kubectl -n <namespace> port-forward pod/<scheduler-pod> 6060:6060

保持端口转发运行，在已安装 Go的本地终端执行以下命令：

# 采集 120 秒的 CPU profile
go tool pprof 'http://127.0.0.1:6060/debug/pprof/profile?seconds=120'
# 查看最近一次 GC 后仍在使用的堆内存
go tool pprof http://127.0.0.1:6060/debug/pprof/heap
# 查看进程启动以来的累计内存分配
go tool pprof http://127.0.0.1:6060/debug/pprof/allocs

每条命令会进入 pprof 交互界面；使用 top 查看热点，使用 quit 退出。源码查看和分析示例见调度器性能分析。

各厂商设备插件与设备参数的 Chart 配置​

devicePlugin.* 管理 HAMi Chart 部署的 NVIDIA 设备插件和 vGPU monitor。devices.<vendor>.* 配置各厂商的调度支持和设备参数，不能据此认为 Chart 会部署对应厂商的插件。

NVIDIA​

常见调整是插件所在节点、RuntimeClass 和单卡共享数量。例如，使用已有的 nvidia RuntimeClass，在 gpu=on 的节点部署插件，并将每卡共享数量设为 20：

devicePlugin:
  enabled: true
  nvidiaNodeSelector:
    gpu: "on"
devices:
  nvidia:
    runtimeClassName: nvidia
    deviceSplitCount: 20

RuntimeClass 和驱动需先按前置条件准备。其他常见共享参数位于 devices.nvidia 下：

字段默认值用途
deviceSplitCount10每张物理 GPU 的共享数量上限；MIG 模式由实际实例容量限制。
deviceMemoryScaling1上报显存容量的倍率；大于 1 允许显存超分配，不增加物理显存，不适用于 MIG。
defaultMemory0未申请正值的绝对显存或显存百分比时，每卡默认分配的显存，单位 MiB；0 表示整卡显存。
defaultCores0未填写算力请求时的默认算力百分比；0 不预留算力。启用 Webhook 时，未指定显存或申请全部显存的整卡请求会将算力请求自动设为 100（即 100%）。

驱动路径、插件镜像、监控、缓存清理及其他共享参数，按需查阅 Chart values 参数表中的 devicePlugin.* 和 devices.nvidia.*。MIG 和 NUMA 配置分别见动态 MIG 支持与 NUMA 对齐。

vGPU 缓存清理​

Pod 删除后，NVIDIA 设备插件会自动清理对应的 vGPU 缓存。devicePlugin.vgpuCache.gracePeriod 默认为 5m，表示从缓存目录最后修改时间起，至少等待多久才允许清理；按需使用 30s、5m、1h 等时长。

0s 只取消等待期，删除前仍需向 API Server 确认 Pod 已不存在；它不会关闭清理，也不保证立即删除。此设置独立于 GC 扫描周期和 monitor 的 HAMI_RESYNC_INTERVAL，后者用于 Pod 缓存重同步和失效内存映射的清理等待期。完整约束见 Chart values 参数表。

其他厂商​

其他厂商插件通常需要独立部署。HAMi Chart 中的配置入口如下，字段含义以 Chart values 参数表为准；插件自身的镜像、启动参数和节点配置见对应设备指南。

厂商与设备指南HAMi Chart 配置入口
Ascenddevices.ascend.*
寒武纪 Cambricondevices.cambricon.*
海光 Hygondevices.hygon.*
摩尔线程 MThreadsdevices.mthreads.*
天数智芯 Iluvatardevices.iluvatar.*
沐曦 MetaXdevices.metax.*
燧原 Enflamedevices.enflame.*
昆仑芯 Kunlunxindevices.kunlun.*
AMDdevices.amd.*
AWS Neuron 前置条件devices.awsneuron.*
瀚博 Vastaidevices.vastai.*
壁仞 Birendevices.biren.*

例如，纯 Ascend 集群可以关闭 NVIDIA 插件，并启用 Ascend 调度支持：

devicePlugin:
  enabled: false
devices:
  ascend:
    enabled: true

此配置不会部署 Ascend 插件，仍需按设备指南单独安装。修改厂商资源名称或芯片配置时，还需核对 customresources，保证 HAMi、厂商插件与业务 Pod 使用的资源名一致。设备型号、模板等列表会整体替换，不会按型号合并。

设备 ConfigMap 的生成与生效​

默认 release 名称为 hami 时，Chart 将全局设备参数写入 hami-scheduler-device ConfigMap 的 device-config.yaml。

不要手动修改全局设备 ConfigMap

不要通过 kubectl edit、kubectl patch 或集群管理界面直接修改全局 device-config.yaml。应修改 Helm values 中的 devices.<vendor>.*，再通过 Helm 更新部署。

手工修改不会同步 Helm values，也不会触发 Chart 配置变更对应的组件滚动更新；后续 Helm 升级或回滚还可能覆盖这些修改。

如需替换完整文件，可使用 device-config.content，具体规则见 Chart values 参数表。它不与 devices.* 合并，且需保持资源名一致，因为 kube-scheduler 的 extender 资源列表仍由 values 生成。

通过 Helm 修改生成的设备配置会更新调度器和 NVIDIA 插件的 Pod 模板。默认 RollingUpdate 自动更新插件 Pod；使用 OnDelete 时需手动删除旧 Pod。独立部署的厂商插件按各自流程更新。

节点 ConfigMap 配置​

NVIDIA 节点配置用于覆盖特定节点的运行模式、共享参数和设备过滤。它与全局设备配置是两个不同的 ConfigMap：

ConfigMap（默认 release 名称）数据项配置来源
hami-scheduler-devicedevice-config.yamldevices.* 等全局 Chart 配置
hami-device-pluginconfig.jsondevicePlugin.nodeConfiguration.config

通过 values 配置节点​

以下是 values.yaml 中节点配置示例的简化版本，将 gpu-node-1 换成实际节点名称：

devicePlugin:
  nodeConfiguration:
    config: |
      {
        "nodeconfig": [
          {
            "name": "gpu-node-1",
            "operatingmode": "hami-core",
            "devicesplitcount": 20,
            "filterdevices": {
              "uuid": [],
              "index": []
            }
          }
        ]
      }

此示例让该节点使用 hami-core 模式，每卡最多共享 20 个容器。filterdevices.uuid 和 filterdevices.index 填写要排除的设备 UUID 或索引，命中任意列表的设备都不会注册到 HAMi。其他参数沿用全局设置。

config 会替换整个 config.json，多个节点应放在同一个 nodeconfig 列表中。匹配优先级是：节点名 name → 标签选择器 nodelabelselector → name: "*" → 全局配置。每项只能设置名称或标签选择器之一。同一级的多个匹配条目按顺序应用；资源字段的零值、false、null 不会清除已有非零值或 true。

更多节点字段、标签选择器示例和覆盖规则，见 Chart values 参数表中的 devicePlugin.nodeConfiguration.config 及其链接的源码示例。

外部 ConfigMap 与重新加载​

若由其他运维工具管理节点配置，可通过以下 values 引用已有 ConfigMap：

devicePlugin:
  nodeConfiguration:
    externalConfigName: hami-node-config

该对象必须与插件 Pod 位于同一命名空间，并包含 config.json 数据项。externalConfigName 优先于 config。

仅修改节点 JSON 或外部 ConfigMap 内容，不会自动更新插件 Pod。节点标签变化后也需要重启插件，以重新匹配配置。默认 RollingUpdate 策略下执行：

kubectl -n <namespace> rollout restart daemonset/hami-device-plugin
kubectl -n <namespace> rollout status daemonset/hami-device-plugin --timeout=5m

命令中的资源名和命名空间按实际部署替换。使用 OnDelete 时需按维护安排手动删除旧插件 Pod。重新加载节点配置不表示已有业务容器的资源限制也已改变。

Pod 配置：labels 与 annotations​

标签和注解写在 Pod 的 metadata 中。Deployment、StatefulSet、Job 等工作负载应写在 spec.template.metadata 下，注解值使用字符串。

位置键用途或示例
labelhami.io/webhook"ignore" 跳过 HAMi Webhook，不再自动填入调度器及设备默认值。
annotationhami.io/node-scheduler-policy"binpack" 或 "spread"，覆盖全局节点策略。
annotationhami.io/gpu-scheduler-policy覆盖节点内设备策略，如 "binpack"、"spread"。
annotationnvidia.com/use-gpuuuid / nvidia.com/nouse-gpuuuid指定允许或排除的 GPU UUID，多个值以逗号分隔。
annotationnvidia.com/use-gputype / nvidia.com/nouse-gputype指定允许或排除的 GPU 型号，如 "A100,Tesla V100"。
annotationnvidia.com/vgpu-mode选择 "hami-core" 或 "mig" 模式。
annotationhami.io/overwrite-env"true" 对未申请设备的容器隐藏 NVIDIA 或 Ascend 设备，覆盖全局默认行为。

例如，下面的 Deployment 片段让 Pod 优先分散到不同节点，并选择 A100 GPU：

spec:
  template:
    metadata:
      annotations:
        hami.io/node-scheduler-policy: "spread"
        nvidia.com/use-gputype: "A100"
    spec:
      containers:
        - name: worker
          image: ubuntu:22.04
          command: ["sleep", "infinity"]
          resources:
            limits:
              nvidia.com/gpu: 1
              nvidia.com/gpumem: 4096
              nvidia.com/gpucores: 50

示例假设使用默认资源名称、memoryFactor: 1，且 Webhook 已启用；镜像和命令按业务替换。资源数量仍需在容器 resources 中申请，注解不能代替资源请求。

更多策略见调度策略，厂商专用注解见各厂商设备指南。nvidia.com/* 注解不通用于其他厂商。HAMi 自动写入的设备分配和绑定状态注解由组件维护，不应复制到新 Pod 或手工修改。

容器配置：环境变量​

以下变量用于 NVIDIA HAMi-core 模式的业务容器，写在容器的 env 中，不是插件的 devicePlugin.extraEnvs。

环境变量用途
GPU_CORE_UTILIZATION_POLICYdefault 根据同卡竞争情况限制算力；force 始终执行申请的算力限制；disable 不执行运行时算力限制。0 和 100 算力不执行此限流。
CUDA_DISABLE_CONTROL"true" 关闭 HAMi-core 控制，失去对应的运行时资源隔离与限制，不应用于依赖隔离的共享任务。
LIBCUDA_LOG_LEVEL"0"、"1" 仅记录错误，"2" 增加警告和消息，"3" 增加 info，"4" 增加 debug。

例如，在业务容器中增加以下配置：

env:
  - name: GPU_CORE_UTILIZATION_POLICY
    value: "force"
  - name: LIBCUDA_LOG_LEVEL
    value: "3"

此示例假设全局 devices.nvidia.gpuCorePolicy 保持 default；若全局设为 force 或 disable，Webhook 会注入同名变量，应检查准入后的 Pod 配置。GPU 显存和算力仍通过 resources.limits 申请，手工修改运行时限制不会同步调度器的资源记账。

全局算力策略、日志级别、整卡容器的 hook 行为及限制传递方式，见 Chart values 参数表中的 devices.nvidia.* 和 devicePlugin.monitor.disableHAMiCoreForWholeGPU。通过 SSH、su - 等方式启动进程时，保留默认 limitDelivery: file，可让未继承容器环境变量的进程仍从只读文件读取限制。

CNCFHAMi 是 CNCF 孵化项目