Apache YuniKorn 1.10.0 配置参数详解

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
YuniKorn 版本	1.10.0（官方最新稳定版）
Kubernetes 版本	v1.36.5+k3s1（k3s stable 通道）
Helm 版本	v3.22.0
部署形态	k3s 单节点集群 + Helm Chart 安装 YuniKorn
组件实现语言	Go（1.10.0 调度器、准入控制器与 Web UI 均为 Go 二进制，非 JVM 组件）
配置载体	ConfigMap `yunikorn-defaults`（命名空间 `yunikorn`）
主要端口	9889（Web UI）、9080（REST 与 UI 代理）
执行账号	root

YuniKorn 1.10.0 的全部配置围绕一个名为 yunikorn-defaults 的 ConfigMap 展开：调度器与准入控制器监听该 ConfigMap 的变化，绝大多数参数修改后自动热加载生效，无需重启组件。本文所有参数说明与示例均在该真实环境中逐项实测。

二、前置条件

已按安装指南完成 YuniKorn 1.10.0 部署，三个组件均处于 Running 状态。
kubectl 与 curl 已可用，且 kubeconfig 已就绪。
确认组件状态：

kubectl -n yunikorn get pods

实测回显：

NAME                                             READY   STATUS    RESTARTS   AGE
yunikorn-admission-controller-7794654984-6kc5h   1/1     Running   0          16m
yunikorn-scheduler-5fdd9bf495-fxrv2              2/2     Running   0          16m

调度器 Pod 内含两个进程实例：调度器核心（yunikorn-scheduler-k8s）与 Web UI（yunikorn-scheduler-web），确认方式：

kubectl -n yunikorn exec deploy/yunikorn-scheduler -c yunikorn-scheduler-k8s -- ps -ef

实测回显（节选）：

UID          PID    PPID  C STIME TTY          TIME CMD
yunikorn       1       0  0 09:32 ?        00:00:48 /yunikorn-scheduler -clusterId mycluster -logEncode json

三、参数查看与修改方式

3.1 通过 kubectl 查看 ConfigMap

YuniKorn 的全量配置保存在 ConfigMap yunikorn-defaults 中，查看该 ConfigMap 即可获取当前下发的配置：

kubectl -n yunikorn get cm yunikorn-defaults -o yaml

实测回显（已添加队列配置后）：

apiVersion: v1
data:
  queues.yaml: |
    partitions:
      - name: default
        queues:
          - name: root
            parent: true
            submitacl: "*"
            queues:
              - name: dev
                resources:
                  guaranteed:
                    memory: 2G
                    vcore: 2
                  max:
                    memory: 4G
                    vcore: 4
              - name: prod
                resources:
                  guaranteed:
                    memory: 2G
                    vcore: 2
                  max:
                    memory: 4G
                    vcore: 4
              - name: default
        placementrules:
          - name: provided
            create: true
kind: ConfigMap
metadata:
  annotations:
    helm.sh/resource-policy: keep
  labels:
    app: yunikorn
    chart: yunikorn-1.10.0
  name: yunikorn-defaults
  namespace: yunikorn

两点重要说明（均为实测结论）：

该 ConfigMap 的 data 键集合由 Helm 参数 yunikornDefaults 在安装时渲染。Chart 默认未提供任何初始键，因此全新安装后 data 为空，此时调度器使用内置默认配置（可通过 REST 接口查看，见 3.3 节）。
ConfigMap 带有 helm.sh/resource-policy: keep 注解，执行 helm uninstall 时该 ConfigMap 会被保留，卸载重装前需手动清理，避免新旧配置冲突。

3.2 通过 helm 查看安装参数

组件资源限额、image 拉取策略等部署层参数通过 Helm values 设置，查看当前生效值：

helm get values yunikorn -n yunikorn

实测回显：

USER-SUPPLIED VALUES:
admissionController:
  image:
    pullPolicy: IfNotPresent
  resources:
    limits:
      memory: 256Mi
    requests:
      memory: 128Mi
image:
  pullPolicy: IfNotPresent
resources:
  limits:
    memory: 512Mi
  requests:
    memory: 256Mi
web:
  image:
    pullPolicy: IfNotPresent
  resources:
    limits:
      memory: 256Mi

3.3 通过 REST 接口查看当前生效配置

调度器在 9080 端口提供 REST 接口，/ws/v1/config 返回当前生效的完整配置与校验和，可先将端口转发到本机：

kubectl -n yunikorn port-forward --address=127.0.0.1 svc/yunikorn-service 9080:9080

实测回显：

Forwarding from 127.0.0.1:9080 -> 9080

另开终端执行（单节点环境也可直接访问 Service 的 ClusterIP）：

curl -s http://10.43.17.0:9080/ws/v1/config

实测回显（内置默认配置）：

partitions:
    - name: default
      queues:
        - name: root
          parent: true
          submitacl: '*'
      placementrules:
        - name: tag
          create: true
          value: namespace
checksum: FD5D3726DF0F02416E02F3919D78F61B15D14425A34142D93B24C137ED056946
deadlockdetectionenabled: false
deadlocktimeoutseconds: 60

可以看到默认配置只有一条 default 分区和 root 队列，放置规则为 tag 规则（详见 5.4 节），死锁检测关闭。

3.4 修改方式与热加载

绝大多数参数通过修改 ConfigMap 下发，调度器默认开启配置热刷新（service.enableConfigHotRefresh 默认 true），修改后数秒内自动生效。以调整日志级别为例：

kubectl -n yunikorn patch cm yunikorn-defaults -p '{"data":{"log.level":"DEBUG"}}'

实测回显：

configmap/yunikorn-defaults patched

配置热加载无需重启任何 Pod。但需要特别注意：并非全部参数都支持热加载，官方文档将参数按生效方式分为两类，详见第四章参数总览。属于「需重启」的参数组修改后，需要删除对应 Pod 触发重建（或执行 helm upgrade）才能生效：

kubectl -n yunikorn delete pod -l app=yunikorn

3.5 修改前预校验 validate-conf

在把 queues.yaml 写入 ConfigMap 之前，可先调用 validate-conf 接口预校验配置合法性，避免非法配置被下发。该接口的请求体是裸 YAML 文本（不是 JSON 包装，直接 POST 文件内容）：

curl -s -X POST -H "Content-Type: application/json" --data-binary @/tmp/queues.yaml http://10.43.17.0:9080/ws/v1/validate-conf

合法配置实测回显：

{"allowed":true,"checksum":"02B8A97502F06DA7EF46107D7AFA526198FA501C63E9121B157DD2F6AF767B95","checksumMatch":false}

非法配置（队列缩进错误）实测回显：

{"allowed":false,"reason":"yaml: line 3: mapping values are not allowed in this context","checksumMatch":false}

返回 allowed:true 才应将配置写入 ConfigMap；返回 allowed:false 时按 reason 提示修正 YAML。

四、参数总览

下表汇总 1.10.0 的核心配置键、默认值与生效方式。「热加载」表示修改 ConfigMap 后自动生效；「需重启」表示修改后必须重建对应组件的 Pod。

4.1 调度器服务参数（需重启）

参数键	默认值	说明
service.clusterId	mycluster	集群标识，与 REST 接口返回的 rmId 一致
service.schedulingInterval	1s	调度周期
service.volumeBindTimeout	10m	卷绑定超时时间
service.eventChannelCapacity	1048576	事件通道容量
service.dispatchTimeout	5m	事件分发超时时间
service.disableGangScheduling	false	是否禁用 gang 调度
service.enableConfigHotRefresh	true	是否开启配置热刷新
service.placeholderImage	registry.k8s.io/pause:3.7	gang 占位 Pod 使用的 image
service.placeholderRunAsUser	65535	占位 Pod 运行用户
service.placeholderRunAsGroup	65535	占位 Pod 运行组
service.placeholderFsGroup	65535	占位 Pod 文件系统组
service.instanceTypeNodeLabelKey	node.kubernetes.io/instance-type	节点实例类型标签键
service.generateUniqueAppId	false	是否自动生成唯一应用 ID

4.2 日志参数（热加载）

参数键	默认值	说明
log.level	INFO	全局日志级别，支持 DEBUG/INFO/WARN/ERROR

4.3 Kubernetes 对接参数（需重启）

调度器与 Kubernetes API 的对接参数（如事件处理相关配置）归入此组，修改后需重启调度器 Pod。

4.4 准入控制器参数

参数键	默认值	说明	生效方式
admissionController.accessControl.bypassAuth	false	是否绕过访问控制校验	热加载
admissionController.accessControl.trustControllers	true	是否信任内置控制器提交的 Pod	热加载
admissionController.accessControl.systemUsers	^system:serviceaccount:kube-system:	视为系统用户的匹配规则	热加载
admissionController.webhook 组	—	webhook 端口与证书等部署参数	需重启

4.5 死锁检测参数

/ws/v1/config 返回值中可见以下两个键（实测回显见 3.3 节）：

参数键	默认值	说明
deadlockdetectionenabled	false	是否开启死锁检测
deadlocktimeoutseconds	60	死锁检测超时时间，单位秒

4.6 部署层内存参数（helm values）

参数键	默认值	说明
goMemoryLimitPercentage	80（调度器）/ 60（准入控制器与 Web UI）	GOMEMLIMIT 取资源限额的百分比
goGC	100	Go 垃圾回收目标百分比（GOGC）
resources.requests.memory	1Gi（调度器）/ 500Mi（准入控制器）/ 100Mi（Web UI）	资源请求
resources.limits.memory	2Gi（调度器）/ 500Mi（准入控制器）/ 500Mi（Web UI）	资源限额

4.7 队列与分区参数（热加载）

queues.yaml 是使用频率最高的配置文件，包含分区、队列树、资源配额与放置规则，修改后热加载生效，详见第五章。

五、核心参数分类详解

5.1 服务基础参数

service. 前缀参数决定调度器的运行行为，全部属于「需重启」组。生产中最常调整的是 service.schedulingInterval：默认 1 秒的调度周期在超大规模集群可适当放宽（如 2s），以降低单次调度的 CPU 占用。service.placeholderImage 默认指向 registry.k8s.io/pause:3.7，启用 gang 调度的环境需确保该 image 在节点上可获取，离线环境可改为内部仓库地址。

5.2 日志参数

log.level 控制组件日志级别，属于「热加载」组。实测将级别调为 DEBUG 再恢复 INFO，均无需重启组件：

kubectl -n yunikorn patch cm yunikorn-defaults -p '{"data":{"log.level":"DEBUG"}}'

实测回显：

configmap/yunikorn-defaults patched

排查调度问题后建议恢复为 INFO，避免日志量过大：

kubectl -n yunikorn patch cm yunikorn-defaults -p '{"data":{"log.level":"INFO"}}'

实测回显：

configmap/yunikorn-defaults patched

5.3 队列与分区资源配额

queues.yaml 的完整结构如下（本文实测使用的配置）：

partitions:
  - name: default
    queues:
      - name: root
        parent: true
        submitacl: "*"
        queues:
          - name: dev
            resources:
              guaranteed:
                memory: 2G
                vcore: 2
              max:
                memory: 4G
                vcore: 4
          - name: prod
            resources:
              guaranteed:
                memory: 2G
                vcore: 2
              max:
                memory: 4G
                vcore: 4
          - name: default
    placementrules:
      - name: provided
        create: true

写入 ConfigMap 后数秒内热加载生效。通过 REST 接口确认配额已生效：

curl -s http://10.43.17.0:9080/ws/v1/partition/default/queue/root.prod

实测回显：

{"queuename":"root.prod","status":"Active","partition":"","maxResource":{"memory":4000000000,"vcore":4000},"guaranteedResource":{"memory":2000000000,"vcore":2000},"headroom":{"ephemeral-storage":801642773490,"memory":4000000000,"pods":109,"vcore":4000},"isLeaf":true,"isManaged":true,"parent":"root","currentPriority":-2147483648,"sortingPolicy":"fifo","prioritySorting":true,"preemptionEnabled":true,"isPreemptionFence":false,"preemptionDelay":"30s","quotaPreemptionDelay":"0s","isPriorityFence":false,"isQuotaPreemptionRunning":false,"askBackoffDelay":"30s"}

注意 REST 返回的资源单位与 YAML 写法的换算关系（实测确认）：YAML 中 memory: 4G 对应返回值 4000000000（字节）；YAML 中 vcore: 4 对应返回值 4000（毫核）。同时 /ws/v1/config 的 checksum 已从默认配置的 FD5D3726DF0F02416E02F3919D78F61B15D14425A34142D93B24C137ED056946 变为新配置的校验和，可作为热加载是否完成的判断依据。

配置文件中的其他常用队列级字段：

字段	说明
parent: true	声明为父队列，不直接接收应用
submitacl	提交控制列表，如 `"*"` 表示全部用户可提交
guaranteed	保证资源，空闲时也可被其他队列借用
max	资源上限，超过即排队等待
sortingPolicy	队列内应用排序策略，默认 fifo
preemptionEnabled	是否启用抢占

5.4 放置规则参数

放置规则决定应用进入哪个队列，是实测中最容易踩坑的配置。1.10.0 内置默认规则为：

placementrules:
  - name: tag
    create: true
    value: namespace

该规则的含义是：按 Pod 的 yunikorn.apache.org/queue 标签值匹配队列，匹配不到时回退为按命名空间命名（value: namespace），即应用总是进入 root.<命名空间> 队列。实测验证：在默认规则下，向 default 命名空间提交一个带 yunikorn.apache.org/queue: root.prod 标签的应用，实际进入的是 root.default：

"applicationID":"app-tag-0001","queueName":"root.default","applicationState":"Running"

标签值 root.prod 被忽略，命名空间优先。要让 yunikorn.apache.org/queue 标签真正生效，需将放置规则改为 provided 规则：

placementrules:
  - name: provided
    create: true

热加载后再次提交带 yunikorn.apache.org/queue: root.prod 标签的应用，实测回显：

"applicationID":"app-prod-0002","queueName":"root.prod","applicationState":"Running"

应用准确进入 root.prod 队列。create: true 表示队列不存在时自动创建。除 provided 与 tag 外，官方还支持 user、group、namespace 等规则类型，可组合多条规则形成回退链。

5.5 内存管控参数

YuniKorn 1.10.0 的三个组件均为 Go 实现，没有 JVM 的堆参数，内存管控通过「Kubernetes 资源限额 + GOMEMLIMIT」双层机制实现。Helm 模板的接线方式为：GOMEMLIMIT 环境变量取该组件 resources.limits.memory 乘以 goMemoryLimitPercentage 百分比，GOGC 环境变量取 goGC。

本文实测部署设定调度器限额 512Mi、goMemoryLimitPercentage 取默认值 80，实测确认进程环境变量：

GOMEMLIMIT=429496730
GOGC=100

429496730 字节即 512Mi 的 80%，与参数设定完全吻合。调大调度器内存限额时，GOMEMLIMIT 会按百分比同步放大；若希望精确控制 Go 运行时内存水位，调整 goMemoryLimitPercentage 即可，无需手工设置环境变量。

5.6 准入控制器参数

准入控制器负责在 Pod 创建时注入调度器所需标签（app-id、queue 等），其访问控制参数均为「热加载」组：

admissionController.accessControl.bypassAuth：默认 false，表示对提交者做访问控制校验。
admissionController.accessControl.trustControllers：默认 true，内置控制器（如 DaemonSet 控制器）提交的 Pod 不做拦截。
admissionController.accessControl.systemUsers：默认正则 ^system:serviceaccount:kube-system:，匹配的用户视为系统用户，跳过校验。

webhook 相关的部署参数（端口、证书等）属于「需重启」组，一般使用 Chart 默认值即可，不建议修改。

六、生产配置模板

6.1 场景与资源规划

场景	节点规模	调度器 resources.limits	goMemoryLimitPercentage	磁盘要求
小型（测试/POC）	20 节点以内	内存 512Mi、CPU 1	80	组件 image 与日志共 5GB 以内
中型	20 至 200 节点	内存 2Gi、CPU 4	80	20GB，日志独立分区
大型	200 节点以上	内存 4Gi、CPU 8	80	50GB 以上，日志独立分区并配置轮转

磁盘方面，YuniKorn 组件自身持久化数据极少，主要磁盘消耗为组件 image 与事件日志；单节点安装时与 Kubernetes 共用系统盘即可，中型以上规模建议为日志单独划分分区。

6.2 部署层模板（helm install）

helm install yunikorn yunikorn/yunikorn -n yunikorn --create-namespace \
  --set image.pullPolicy=IfNotPresent \
  --set resources.requests.memory=1Gi \
  --set resources.limits.memory=2Gi \
  --set admissionController.resources.requests.memory=500Mi \
  --set admissionController.resources.limits.memory=500Mi \
  --set web.resources.limits.memory=500Mi \
  --set goMemoryLimitPercentage=80 \
  --set goGC=100

说明：resources.requests 与 limits 必须成对设置且 requests 不大于 limits，否则 Chart 校验会报错拒绝安装。

6.3 队列配置模板（queues.yaml）

以下模板包含分区、队列树、提交控制与放置规则，可直接写入 yunikorn-defaults ConfigMap 的 queues.yaml 键：

partitions:
  - name: default
    queues:
      - name: root
        parent: true
        submitacl: "*"
        queues:
          - name: dev
            resources:
              guaranteed:
                memory: 20G
                vcore: 20
              max:
                memory: 40G
                vcore: 40
          - name: prod
            resources:
              guaranteed:
                memory: 40G
                vcore: 40
              max:
                memory: 80G
                vcore: 80
          - name: default
            resources:
              guaranteed:
                memory: 0
                vcore: 0
    placementrules:
      - name: provided
        create: true
      - name: tag
        create: false
        value: namespace

生产建议：

按业务线拆分队列并设置 guaranteed 与 max，保证基线资源同时防止单队列耗尽集群。
放置规则首条使用 provided，让应用通过 yunikorn.apache.org/queue 标签指定队列；未指定队列的应用按需增加回退规则。
写入前先经 validate-conf 预校验（见 3.5 节），确认 allowed:true 再下发。
下发后观察 /ws/v1/config 的 checksum 变化确认热加载完成。

七、常见问题

Q1：修改 ConfigMap 后配置一直没有生效？

先确认修改的是 yunikorn 命名空间下的 yunikorn-defaults（名称固定，不能是其他 ConfigMap）；再用 /ws/v1/config 的 checksum 判断调度器是否已加载新配置。若 checksum 未变化，检查 service.enableConfigHotRefresh 是否被改为 false；若该参数为 false，需删除调度器 Pod 重建后重新评估。另外注意部分参数组属于「需重启」类型，热加载对其无效。

Q2：应用带了 queue 标签却没有进入指定队列？

默认放置规则是 tag 规则且回退到命名空间（value: namespace），实测证明此时应用会进入 root.<命名空间>，标签被忽略。将放置规则改为 provided create: true 后标签才会生效，实测两种规则的对比回显见 5.4 节。

Q3：调用 validate-conf 报 field partitionsConf not found？

该接口的请求体是裸 YAML 文本。若把 YAML 内容包装进 JSON 字段后提交，实测会返回：

{"allowed":false,"reason":"yaml: unmarshal errors:\n  line 1: field partitionsConf not found in type configs.SchedulerConfig","checksumMatch":false}

直接使用 curl --data-binary @文件名 提交 YAML 文件内容即可。

Q4：误删或清空 yunikorn-defaults ConfigMap 有影响吗？

实测将 ConfigMap 清空后调度器回退到内置默认配置（单 default 分区、root 单队列、tag 放置规则），集群不会崩溃，但自定义队列与配额全部失效。重新写入 queues.yaml 即可恢复，无需重启组件。该 ConfigMap 带 helm.sh/resource-policy: keep 注解，卸载时不会被删除，重装前请先确认其内容是否需要保留。

八、参考链接

YuniKorn 官方文档（服务配置）：https://yunikorn.apache.org/docs/next/configuration/services
YuniKorn 官方文档（队列配置）：https://yunikorn.apache.org/docs/next/configuration/queues
YuniKorn 官方文档（放置规则）：https://yunikorn.apache.org/docs/next/design/placementrules
GitHub Release v1.10.0：https://github.com/apache/yunikorn-release/releases/tag/v1.10.0
官方 Helm 仓库：https://apache.github.io/yunikorn-release