Apache YuniKorn 1.10.0 常用 CLI 命令与工具详解

汇总 Apache YuniKorn 1.10.0 的常用工具,覆盖 Helm 全生命周期、kubectl 资源与日志操作、REST API 调用示例及 queueconfigchecker 配置校验工具,命令输出均经真实环境实测。

Apache YuniKornApache YuniKorn2026/10/12

Apache YuniKorn 1.10.0 常用 CLI 命令与工具详解

一、环境信息

项目值
操作系统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
kubeconfig 路径/etc/rancher/k3s/k3s.yaml
调度器 REST 端口9080(Service ClusterIP 10.43.17.0,或 port-forward)
Web UI 端口9889
执行账号root

本文在上述真实环境中逐条执行并采集回显,所有命令均为单实例环境一次执行一条,可直接复制使用。

二、工具概览

工具用途来源
helmYuniKorn 的安装、升级、回滚、卸载全生命周期管理get.helm.sh 或系统包管理器安装
kubectl查看与管理集群资源、组件日志、配置下发k3s 自带(/usr/local/bin/kubectl)
curl调用调度器 REST API,查看队列、应用、节点、健康状态与指标系统自带或 apt/dnf 安装
queueconfigchecker离线校验 queues.yaml 配置文件合法性发行源码包 core/cmd/queueconfigchecker,需自行编译

四个工具覆盖了 YuniKorn 日常运维的全部场景:部署期用 helm,运行期用 kubectl 与 curl,配置变更前用 queueconfigchecker 或 validate-conf 接口预校验。

三、前置条件

  1. YuniKorn 1.10.0 已部署且组件处于 Running 状态。
  2. kubectl 可直接使用(k3s 安装时已自动配置 kubeconfig),helm 需指定 KUBECONFIG 环境变量。
  3. 确认工具版本:
helm version --short

实测回显:

v3.22.0+gc1d6bf0a
kubectl version --short 2>/dev/null | head -2

实测回显:

Client Version: v1.36.5
Kustomize Version: v5.7.0

四、工具详解

4.1 helm:部署全生命周期管理

4.1.1 添加并检索官方 Chart 仓库

helm repo add yunikorn https://apache.github.io/yunikorn-release

实测回显:

"yunikorn" has been added to your repositories
helm search repo yunikorn --versions | head -3

实测回显:

NAME                    CHART VERSION   APP VERSION     DESCRIPTION
yunikorn/yunikorn       1.10.0          1.10.0          YuniKorn scheduler for Kubernetes
yunikorn/yunikorn       1.9.0           1.9.0          YuniKorn scheduler for Kubernetes

离线拉取 Chart 包(在可访问网络的机器上执行,离线服务器可复用 helm 缓存目录 /root/.cache/helm/repository/ 下的 yunikorn-1.10.0.tgz,实测该包 8801 字节):

helm pull yunikorn/yunikorn --version 1.10.0

4.1.2 安装与查看

helm install yunikorn yunikorn/yunikorn -n yunikorn --create-namespace

安装后查看发布状态:

helm list -n yunikorn

实测回显:

NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
yunikorn        yunikorn        3               2026-10-12 11:06:34.033007758 +0000 UTC deployed        yunikorn-1.10.0
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

4.1.3 升级与历史

升级示例(调整 image 拉取策略为 IfNotPresent):

helm upgrade yunikorn yunikorn/yunikorn -n yunikorn --reuse-values --set image.pullPolicy=IfNotPresent

查看发布历史,REVISION 逐次递增:

helm history yunikorn -n yunikorn

实测回显:

REVISION        UPDATED                         STATUS          CHART           APP VERSION     DESCRIPTION
1               Mon Oct 12 09:32:08 2026        superseded      yunikorn-1.10.0                 Install complete
2               Mon Oct 12 09:41:16 2026        superseded      yunikorn-1.10.0                 Upgrade complete
3               Mon Oct 12 11:06:34 2026        deployed        yunikorn-1.10.0                 Upgrade complete

4.1.4 卸载

helm uninstall yunikorn -n yunikorn

实测卸载过程中会出现资源保留提示:

These resources were kept due to the resource policy:
[ConfigMap] yunikorn/yunikorn-defaults

注意:ConfigMap yunikorn-defaults 因 helm.sh/resource-policy: keep 注解被保留。实测在保留该 ConfigMap 的状态下重新安装会失败,提示 ConfigMap 与新发布不兼容(incompatible modifiable),重装前需先删除该 ConfigMap 或确认其内容可复用。

4.2 kubectl:集群资源与组件操作

4.2.1 查看节点与组件状态

kubectl get nodes

实测回显:

NAME           STATUS   ROLES           AGE    VERSION
b76ff320bc96   Ready    control-plane   113m   v1.36.5+k3s1
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
kubectl -n yunikorn get svc

实测回显:

NAME                                    TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)             AGE
yunikorn-admission-controller-service   ClusterIP   10.43.73.29   <none>        443/TCP             111m
yunikorn-service                        ClusterIP   10.43.17.0    <none>        9080/TCP,9889/TCP   111m

4.2.2 查看组件日志

调度器 Pod 内含两个进程实例,进程实例名分别为 yunikorn-scheduler-k8s(调度器核心)与 yunikorn-scheduler-web(Web UI),查看日志时必须用 -c 指定正确名称:

kubectl -n yunikorn logs deploy/yunikorn-scheduler -c yunikorn-scheduler-k8s --tail=3

实测回显:

2026-10-12T11:21:45.358Z        INFO    core.scheduler.queue    objects/queue.go:1097   Application completed and removed from queue    {"queueName": "root.default", "applicationID": "app-tag-0001"}
2026-10-12T11:21:45.358Z        INFO    core.scheduler.partition        scheduler/partition.go:1763     Removing terminated application from the application list       {"appID": "app-tag-0001", "app status": "Completed"}
2026-10-12T11:21:45.358Z        INFO    core.scheduler.application.usage        objects/application_summary.go:60       YK_APP_SUMMARY: {ApplicationID: app-tag-0001, SubmissionTime: 1791804028000, StartTime: 1791804031244, FinishTime: 1791804105358, User: system:admin, Queue: root.default, State: Completed, RmID: mycluster, ResourceUsage: TrackedResource{UNKNOWN:pods=44}, PreemptedResource: TrackedResource{}, PlaceholderResource: TrackedResource{}}

若指定的进程实例名不存在,kubectl 会报 not valid 错误并列出该 Pod 的实际名称列表,按列表修正 -c 参数即可。准入控制器为单实例进程,无需 -c 参数。

4.2.3 等待组件就绪

kubectl wait --for=condition=available deploy --all -n yunikorn --timeout=300s

实测回显:

deployment.apps/yunikorn-admission-controller condition met
deployment.apps/yunikorn-scheduler condition met

4.2.4 端口转发访问 UI 与 REST

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

实测回显:

Forwarding from 127.0.0.1:9889 -> 9889

另开终端验证:

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9889/

实测回显:

200
curl -s http://127.0.0.1:9889/ | grep -o "<title>[^<]*</title>"

实测回显:

<title>YuniKorn UI</title>

建议始终显式携带 --address=127.0.0.1:实测发现不指定 address 时端口可能只绑定 IPv6 回环地址,导致用 127.0.0.1 访问失败。

4.2.5 权限自检与资源删除

kubectl auth can-i create pods -n default

实测回显:

yes
kubectl -n default delete pod sleep-prod

实测回显:

pod "sleep-prod" deleted

4.3 kubectl:配置查看与热修改

4.3.1 查看配置 ConfigMap

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

实测回显(data 段节选,完整内容随队列配置而定):

apiVersion: v1
data:
  queues.yaml: |
    partitions:
      - name: default
        queues:
          - name: root
            parent: true
            submitacl: "*"
            queues:
              - name: dev
                resources:
                  guaranteed:
                    memory: 2G
                    vcore: 2
              - name: prod
                resources:
                  guaranteed:
                    memory: 2G
                    vcore: 2
                  max:
                    memory: 4G
                    vcore: 4
kind: ConfigMap
metadata:
  name: yunikorn-defaults
  namespace: yunikorn

4.3.2 热修改与回读

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

实测回显:

configmap/yunikorn-defaults patched

修改后数秒内热加载生效,回读确认:

kubectl -n yunikorn get cm yunikorn-defaults -o jsonpath="{.data.log\.level}"

实测回显:

DEBUG

排查结束后恢复默认级别:

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

实测回显:

configmap/yunikorn-defaults patched

4.4 curl:REST API 全端点实测

以下示例通过调度器 Service 的 ClusterIP 直接访问(单节点服务器在该网络内),端口为 9080。无法直接访问时先用 4.2.4 节的 port-forward 转到本机。

4.4.1 集群与构建信息

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

实测回显:

[{"startTime":1791803195706378423,"rmBuildInformation":[{"arch":"amd64","buildDate":"2026-09-29T00:36:22+00:00","buildVersion":"1.10.0","coreSHA":"d345f41c50c46e65d826413c7e8f166b5e88b469","goVersion":"1.26.7","rmId":"mycluster","shimSHA":"170fa4abc0f62761a331ba20571d6b314d2b727a","siSHA":"6778d0db6fb30ff0f9970785722a5e14f28794c9"}],"partition":"default","clusterName":"kubernetes"}]

该接口可确认部署的精确构建版本(buildVersion 1.10.0、构建日期 2026-09-29、Go 版本 1.26.7)。

4.4.2 分区信息

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

实测回显:

[{"clusterId":"mycluster","name":"default","capacity":{"capacity":{"ephemeral-storage":801642773490,"memory":33607266304,"pods":110,"vcore":12000}},"nodeSortingPolicy":{"type":"fair","resourceWeights":{"memory":1,"vcore":1}},"userGroupResolver":{},"preemptionEnabled":true,"quotaPreemptionEnabled":false,"totalNodes":1,"applications":{"total":0},"state":"Active","lastStateTransitionTime":1791803196724416502}]

4.4.3 队列树与队列详情

curl -s http://10.43.17.0:9080/ws/v1/partition/default/queues

实测回显(默认配置下的根队列):

{"queuename":"root","status":"Active","partition":"default","maxResource":{"ephemeral-storage":801642773490,"memory":33607266304,"pods":110,"vcore":12000},"headroom":{"ephemeral-storage":801642773490,"memory":33607266304,"pods":110,"vcore":12000},"isLeaf":false,"isManaged":true,"currentPriority":-2147483648,"sortingPolicy":"fair","prioritySorting":true,"preemptionEnabled":true,"isPreemptionFence":false,"preemptionDelay":"30s","quotaPreemptionDelay":"0s","isPriorityFence":false,"isQuotaPreemptionRunning":false,"askBackoffDelay":"30s"}

查看指定队列(已配置 4G/4vcore 配额的 root.prod):

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"}

注意返回值单位:memory 为字节,vcore 为毫核(YAML 中写 vcore: 4,接口返回 4000)。查询不存在的队列返回 404:

{"status_code":404,"message":"Queue not found","description":"Queue not found"}

4.4.4 活跃应用

curl -s http://10.43.17.0:9080/ws/v1/partition/default/applications/active

实测回显为 JSON 数组,用 grep 提取关键字段:

curl -s http://10.43.17.0:9080/ws/v1/partition/default/applications/active | grep -o "\"applicationID\":\"[^\"]*\"\|\"queueName\":\"[^\"]*\"\|\"applicationState\":\"[^\"]*\""

实测回显:

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

4.4.5 当前生效配置

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

修改 ConfigMap 后 checksum 随之变化,是判断热加载是否完成的最直接依据。

4.4.6 健康检查

curl -s http://10.43.17.0:9080/ws/v1/scheduler/healthcheck

实测回显:

{"Healthy":true,"HealthChecks":[{"Name":"Scheduling errors","Succeeded":true,"Description":"Check for scheduling error entries in metrics","DiagnosisMessage":"There were 0 scheduling errors logged in the metrics"},{"Name":"Failed nodes","Succeeded":true,"Description":"Check for failed nodes entries in metrics","DiagnosisMessage":"There were 0 failed nodes logged in the metrics"},{"Name":"Negative resources","Succeeded":true,"Description":"Check for negative resources in the partitions","DiagnosisMessage":"Partitions with negative resources: []"},{"Name":"Negative resources","Succeeded":true,"Description":"Check for negative resources in the nodes","DiagnosisMessage":"Nodes with negative resources: []"},{"Name":"Consistency of data","Succeeded":true,"Description":"Check if total partition resource == sum of the node resources from the partition","DiagnosisMessage":"Partitions with inconsistent data: []"},{"Name":"Consistency of data","Succeeded":true,"Description":"Check if node total resource = allocated resource + occupied resource + available resource","DiagnosisMessage":"Nodes with inconsistent data: []"},{"Name":"Reservation check","Succeeded":true,"Description":"Check the reservation nr compared to the number of nodes","DiagnosisMessage":"Reservation/node nr ratio: [0.000000]"},{"Name":"Orphan allocation on node check","Succeeded":true,"Description":"Check if there are orphan allocations on the nodes","DiagnosisMessage":"Orphan allocations: []"},{"Name":"Orphan allocation on app check","Succeeded":true,"Description":"Check if there are orphan allocations on the applications","DiagnosisMessage":"OrphanAllocations: []"}]}

Healthy 为 true 且各子项 Succeeded 均为 true 表示调度器内部状态一致。

4.4.7 节点利用率

curl -s http://10.43.17.0:9080/ws/v1/scheduler/node-utilizations

实测回显为 JSON 数组,按资源类型分段返回十档利用率桶。以下为其中 vcore 类型的完整片段:

{"type":"vcore","utilization":[{"bucketName":"0-10%","numOfNodes":1,"nodeNames":["b76ff320bc96"]},{"bucketName":"10-20%"},{"bucketName":"20-30%"},{"bucketName":"30-40%"},{"bucketName":"40-50%"},{"bucketName":"50-60%"},{"bucketName":"60-70%"},{"bucketName":"70-80%"},{"bucketName":"80-90%"},{"bucketName":"90-100%"}]}

memory、pods、ephemeral-storage 三种类型结构相同,可据此判断集群资源水位分布。

4.4.8 调度事件

curl -s "http://10.43.17.0:9080/ws/v1/events/batch" | head -c 500

实测回显(前 500 字节):

{"InstanceUUID":"7e02693c-5e31-427a-800d-a38a8601620e","LowestID":0,"HighestID":24,"EventRecords":[{"type":4,"objectID":"root","timestampNano":1791803196724581561,"eventChangeType":2,"resource":{}},{"type":3,"objectID":"b76ff320bc96","message":"schedulable: false","timestampNano":1791803196724822627,"eventChangeType":1,"eventChangeDetail":302,"resource":{}},{"type":4,"objectID":"root","timestampNano":1791803196724907818,"eventChangeType":1,"eventChangeDetail":403,"resource":{}},{"type":3,"object

4.4.9 Prometheus 指标

curl -s http://10.43.17.0:9080/ws/v1/metrics | head -12

实测回显(前 12 行):

# HELP go_gc_duration_seconds A summary of the wall-time pause (stop-the-world) duration in garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 4.4762e-05
go_gc_duration_seconds{quantile="0.25"} 6.5147e-05
go_gc_duration_seconds{quantile="0.5"} 9.7658e-05
go_gc_duration_seconds{quantile="0.75"} 0.000145859
go_gc_duration_seconds{quantile="1"} 0.005265189
go_gc_duration_seconds_sum 0.006362915
go_gc_duration_seconds_count 12
# HELP go_gc_gogc_percent Heap size target percentage configured by the user, otherwise 100. This value is set by the GOGC environment variable, and the runtime/debug.SetGCPercent function. Sourced from /gc/gogc:percent.
# TYPE go_gc_gogc_percent gauge
go_gc_gogc_percent 100

该端点输出 Prometheus 文本格式,可直接接入监控系统;其中 go_gc_gogc_percent 100 与配置参数 goGC 的默认值一致。

4.4.10 配置预校验

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}

请求体为裸 YAML 文本,不要包装成 JSON 对象,否则实测会报 field partitionsConf not found。

4.4.11 已移除的接口

curl -s -o /dev/null -w "%{http_code}" http://10.43.17.0:9080/ws/v1/scheduler

实测回显:

404

旧版本的调度器转储接口 /ws/v1/scheduler 在 1.10.0 已移除,改用 partitions、queues、applications 等细分接口。

4.5 queueconfigchecker:离线配置校验工具

该工具随发行源码包提供,位于 core/cmd/queueconfigchecker,用于在配置下发前离线校验 queues.yaml 的合法性,适合集成到配置管理的流水线中。

获取与编译(需 Go 1.26 及以上版本,与 1.10.0 构建版本一致):

tar -xzf apache-yunikorn-1.10.0-src.tar.gz
cd apache-yunikorn-1.10.0-src/core/cmd/queueconfigchecker
go build -o queueconfigchecker .
cp queueconfigchecker /usr/local/bin/

编译成功无任何输出。以下三个用例均为实测:

用例一:无参数调用,输出用法并退出码 1:

/usr/local/bin/queueconfigchecker

实测回显:

2026/10/12 11:21:16 Usage: /usr/local/bin/queueconfigchecker <queue-config-file>

退出码:

1

用例二:合法配置,静默通过并退出码 0:

/usr/local/bin/queueconfigchecker /tmp/queues.yaml

实测无任何输出,退出码:

0

用例三:非法配置(队列缩进错误),输出校验失败信息并退出码 3:

/usr/local/bin/queueconfigchecker /tmp/badq.yaml

实测回显:

2026-10-12T11:21:16.132Z        ERROR   core.config     configs/config.go:210   failed to parse queue configuration     {"error": "yaml: line 3: mapping values are not allowed in this context"}
github.com/apache/yunikorn-core/pkg/common/configs.ParseAndValidateConfig
        core/pkg/common/configs/config.go:210
github.com/apache/yunikorn-core/pkg/common/configs.LoadSchedulerConfigFromByteArray
        core/pkg/common/configs/config.go:174
main.main
        core/cmd/queueconfigchecker/queueconfigchecker.go:44
2026/10/12 11:21:16 Config validation failed: yaml: line 3: mapping values are not allowed in this context

退出码:

3

说明:回显中的 Go 调用栈行路径与编译环境相关,不同机器编译后路径前缀会不同,判断依据以 ERROR 行与 Config validation failed 行为准。退出码约定:0 表示校验通过,1 表示用法错误,3 表示配置校验失败。

五、注意事项

  1. helm 读取的是标准 kubeconfig 环境变量,k3s 环境执行 helm 命令前需设置 KUBECONFIG=/etc/rancher/k3s/k3s.yaml,否则实测报错:Error: Kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp [::1]:8080: connect: connection refused。
  2. kubectl 查看调度器日志必须使用正确的进程实例名:调度器核心为 yunikorn-scheduler-k8s,Web UI 为 yunikorn-scheduler-web;名称错误时 kubectl 会提示实际可选列表。
  3. 9080 端口同时提供 REST API 与 Web UI 反向代理,9889 是 Web UI 独立端口;REST 调用统一走 9080。
  4. port-forward 建议始终加 --address=127.0.0.1,避免只绑定 IPv6 回环导致本机访问失败(实测踩坑)。
  5. 修改 queues.yaml 前先用 validate-conf 接口或 queueconfigchecker 工具预校验,非法配置写入 ConfigMap 会被调度器拒绝加载。
  6. REST 返回的 vcore 一律为毫核,与 queues.yaml 中的 CPU 个数相差 1000 倍,做监控告警阈值时注意换算。

六、常见问题

Q1:执行 helm 命令报 Kubernetes cluster unreachable?

helm 未读取到 kubeconfig。k3s 的 kubeconfig 在 /etc/rancher/k3s/k3s.yaml,执行前设置环境变量:export KUBECONFIG=/etc/rancher/k3s/k3s.yaml。实测该问题在全新终端会话中最常见。

Q2:kubectl logs 指定 -c yunikorn-scheduler 报 not valid?

1.10.0 的调度器 Pod 内进程实例名已细化,实际名称为 yunikorn-scheduler-k8s 与 yunikorn-scheduler-web,按名称修正 -c 参数即可;kubectl 的错误提示会列出全部可选名称。

Q3:访问 /ws/v1/scheduler 返回 404?

该转储接口在 1.10.0 已移除。获取同类信息改用:分区用 /ws/v1/partitions、队列用 /ws/v1/partition/default/queues、应用用 /ws/v1/partition/default/applications/active,各接口完整回显见 4.4 节。

Q4:validate-conf 一直报 field partitionsConf not found?

请求体格式错误。1.10.0 的该接口直接接收裸 YAML 文本,使用 curl --data-binary @配置文件 提交;不要将 YAML 内容包装进 JSON 字段提交(实测报错回显见 4.4.10 节说明)。

七、参考链接

  1. YuniKorn 官方文档(REST 接口):https://yunikorn.apache.org/docs/next/api/scheduler
  2. YuniKorn 官方文档(服务配置):https://yunikorn.apache.org/docs/next/configuration/services
  3. Apache 下载页(源码包):https://downloads.apache.org/yunikorn/
  4. GitHub Release v1.10.0:https://github.com/apache/yunikorn-release/releases/tag/v1.10.0
  5. 官方 Helm 仓库:https://apache.github.io/yunikorn-release