Apache YuniKorn 1.10.0 常用 CLI 命令与工具详解
汇总 Apache YuniKorn 1.10.0 的常用工具,覆盖 Helm 全生命周期、kubectl 资源与日志操作、REST API 调用示例及 queueconfigchecker 配置校验工具,命令输出均经真实环境实测。
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 |
本文在上述真实环境中逐条执行并采集回显,所有命令均为单实例环境一次执行一条,可直接复制使用。
二、工具概览
| 工具 | 用途 | 来源 |
|---|---|---|
| helm | YuniKorn 的安装、升级、回滚、卸载全生命周期管理 | 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 接口预校验。
三、前置条件
- YuniKorn 1.10.0 已部署且组件处于 Running 状态。
- kubectl 可直接使用(k3s 安装时已自动配置 kubeconfig),helm 需指定 KUBECONFIG 环境变量。
- 确认工具版本:
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 表示配置校验失败。
五、注意事项
- 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。 - kubectl 查看调度器日志必须使用正确的进程实例名:调度器核心为
yunikorn-scheduler-k8s,Web UI 为yunikorn-scheduler-web;名称错误时 kubectl 会提示实际可选列表。 - 9080 端口同时提供 REST API 与 Web UI 反向代理,9889 是 Web UI 独立端口;REST 调用统一走 9080。
- port-forward 建议始终加
--address=127.0.0.1,避免只绑定 IPv6 回环导致本机访问失败(实测踩坑)。 - 修改
queues.yaml前先用 validate-conf 接口或 queueconfigchecker 工具预校验,非法配置写入 ConfigMap 会被调度器拒绝加载。 - 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 节说明)。
七、参考链接
- YuniKorn 官方文档(REST 接口):
https://yunikorn.apache.org/docs/next/api/scheduler - YuniKorn 官方文档(服务配置):
https://yunikorn.apache.org/docs/next/configuration/services - Apache 下载页(源码包):
https://downloads.apache.org/yunikorn/ - GitHub Release v1.10.0:
https://github.com/apache/yunikorn-release/releases/tag/v1.10.0 - 官方 Helm 仓库:
https://apache.github.io/yunikorn-release