视图命令行工具
更新时间：2024-06-07
背景介绍
cce-volcano-cli是一个集群资源视图分析与任务调度失败排查的工具。当集群中的pod出现调度pending的情况时，可以借助该工具对集群中的资源和配额的占用情况进行分析，同时也可以基于该命令对CCE AI Job Scheduler的调度日志进行分析，从而得到任务调度失败的原因。
功能与使用
使用前提
- AI Job Scheduler组件已更新至v1.7.6以上版本，推荐升级到v1.7.8以上
- 当前仅支持独占卡场景，暂不支持共享卡视图分析。
获取命令行
用户可以通过三种方式使用命令行工具：通过kubectl使用、通过webssh使用、本地下载。其中前两种方式要求AI Job Scheduler 更新到v1.7.8以上，本地下载使用要求AI Job Scheduler 更新到v1.7.6以上。
通过kubectl使用
在升级CCE AI Job Scheduler到1.7.8版本以后，用户可以获取集群的kubeconfig文件，通过执行kubectl -n volcano-system exec volcano-viewer-0 -ti bash命令直接进入容器使用命令行工具。
kubectl -n volcano-system exec volcano-viewer-0 -ti bash
kubectl exec [POD] [COMMAND] is DEPRECATED and will be removed in a future version. Use kubectl exec [POD] -- [COMMAND] instead.
root@volcano-viewer-0:/# cce-volcano-cli dump
2023/10/26 06:45:09 copy file volcano-scheduler-7fdc695ffb-7tmj7:/dump/volcano.1698302709.snapshot to ./volcano.1698302709.snapshot success!通过webssh使用
在升级CCE AI Job Scheduler到1.7.8版本以后，用户可以通过集群页面，在有状态部署页面中，找到volcano-viewer，使用webSSH进入到volcano-viewer-0容器中使用命令行工具
命令功能列表
命令行工具的命令列表如下
主命令 | 二级子命令 | 功能 |
cce-volcano-cli | dump | 导出CCE AI Job Scheduler当前资源视图，并将视图文件存储到本地。资源视图文件名称为volcano.{timestamp}.snapshot |
导出CCE AI Job Scheduler的日志到本地，json日志文件名称为volcano.{timestamp}.log | ||
log | 修改CCE AI Job Scheduler主pod的日志等级 | |
job子命令：根据CCE AI Job Scheduler日志文件，分析job调度失败原因，常见的原因如下
| ||
pod子命令：根据CCE AI Job Scheduler日志文件，分析pod调度失败原因，常见的原因如下
| ||
cluster | 查看集群资源视图，包含如下信息
| |
node | 查看节点资源视图，包含如下信息
| |
queue | 查看队列资源视图，包含如下信息
| |
job | 查看job资源视图，包含如下信息
|
快速使用
- 首先，cce-volcano-cli dump 命令可以将视图数据导出成本地文件，用于视图分析。
# cce-volcano-cli dump
copy file volcano-scheduler-6dbc77fff5-qjgql:/dump/volcano.1698837155.snapshot to ./volcano.1698837155.snapshot success!- 对于任务调度不上问题，一般可以基于视图文件查询集群总资源以及队列配额进行初步判断，也可以查看节点资源明细进行判断
- 使用cce-volcano-cli cluster命令查看集群资源是否有剩余
- 使用cce-volcano-cli queue命令查看队列配额是否有剩余
- 使用cce-volcano-cli node命令查看集群的节点资源占用明细
- 如果总体资源和配额层面没有发现明显的问题，也可以通过日志得到具体的错误信息再结合视图数据进行进一步分析。
命令行参数介绍
dump
功能描述
导出CCE AI Job Scheduler当前视图，并存储到本地。
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| -h | - | - | 显示帮助信息 |
| -n | string | volcano-system | 指定CCE AI Job Scheduler部署的namespace，一般无需指定 |
| -l | int | - | 指定dump到CCE AI Job Scheduler日志行数，默认为0，不dump日志 |
使用示例
默认将视图文件和日志，存储到当前路径下。其中，-l为volcano日志的保存行数。资源视图文件名称为volcano.{timestamp}.snapshot，日志文件名称为volcano.{timestamp}.log
# cce-volcano-cli dump -l 10000
copy file volcano-scheduler-6dbc77fff5-xt6pk:/dump/volcano.1698733321.snapshot to ./volcano.1698733321.snapshot success!
start dump volcano logfile volcano.1698733321.log
end dump volcano logfile volcano.1698733321.log
% ls
volcano.1698733321.log volcano.1698733321.snapshotlog
功能描述
- 动态修改CCE AI Job Scheduler的日志等级
- 日志关键信息分析
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| -h | - | - | 命令使用帮助 |
| -v | string | - | 指定volcano的日志等级 |
| job -j | string | - | job 子命令 分析CCE AI Job Scheduler的json日志 |
| pod -p | string | - | pod 子命令 分析CCE AI Job Scheduler的json日志 |
使用示例
进行日志分析前可以使用log命令调整日志等级，如果修改日志等级成功，输出结果为修改的日志level
# cce-volcano-cli log -k kubeconfig -v 4
4可以使用log job命令分析job异常日志：
# 其中f表示文件名字 j表示job的名字
cce-volcano-cli log job -f volcano.snapshot.1694421056.log -j nginx
{
"ts": 1694069307712.7,
"caller": "cceproportion/proportion.go:452",
"msg": "Reject job enqueue",
"v": 3,
"Session": "a612c39f-bb8b-454d-9b7b-b4c6ebc0a5b7",
"JobName": "nginx",
"Namespace": "default",
"PodGroupName": "podgroup-ec1926f8-1901-4c49-bd19-3653a5cd7064",
"Queue": "default",
"EventName": "ResouceCapcityOverUsed",
"Reason": "ExceedQueueResource"
}可以使用log pod命令分析pod异常信息：
# 其中f表示文件名字 p表示pod的名字
# cce-volcano-cli log pod -f volcano.snapshot.1694421056.log -p nginx-0
failure reason : Insufficient GPU Resources ,involved Nodes : [192.168.11.3 192.168.11.5 192.168.14.15]cluster
功能描述
输出集群资源视图
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| -h | - | - | 命令使用帮助 |
| -f | string | - | 视图文件路径 |
| -o | string | table | 输出格式：table或者json |
使用示例
node
功能描述
node的资源视图。
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| -h | - | - | 命令使用帮助 |
| -f | string | - | 视图文件路径 |
| -o | string | table | 输出格式：table或者json |
| -N | string | - | 指定node的名字，不指定默认显示集群全部node |
| -a | string | - | 是否展示全部的task，默认false不展示 |
使用示例
queue
功能描述
queue的资源视图。
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| -h | - | - | 命令使用帮助 |
| -f | string | - | 视图文件路径 |
| -o | string | table | 输出格式：table或者json |
| -q | string | - | 指定queue的名字，不指定默认显示全部queue |
使用示例
job
功能描述
job的资源视图。
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| -h | - | - | 命令使用帮助 |
| -f | string | - | 视图文件路径 |
| -o | string | table | 输出格式：table或者json |
| -j | string | - | job的名字，不指定，默认全部 |
使用示例
gpu
功能描述
判断集群中，是否有掉卡的node，判断标准是可用gpu个数<实际gpu个数。
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| -h | - | - | 命令使用帮助 |
| -f | string | - | 视图文件路径 |
| -o | string | table | 输出格式：table或者json |
使用示例
如果无掉卡输出为空。
有掉卡则输出节点列表
命令行高级功能
参数说明
命令行提供了一些高级功能，列表如下
功能 | 支持的二级子命令 | 参数 | 类型 | 默认值 | 说明 |
指定集群做视图dump | dump | -k | string | - | 指定kubeconfig文件路径，在非容器场景使用的时候，可以通过该选项指定操作的集群 |
分组汇聚 | job、node | -g | string | - | 选择字段进行group by， 对于node支持字段：Status、Taint 对于job支持字段：JobKind、Priority、Namespace、Queue、Status |
排序展示 | job、node | --asc | - | - | 默认降序，加入该选项支持升序 |
--sort-column | string | - | 指定排序的列 | ||
--sort-resource | string | - | 排序的列中的资源字段，不提供默认为cpu，包含totalGPU、memory、baidu.com/*_cgpu等，支持自定义资源描述符 | ||
筛选展示 | job、node | --filter-column | string | - | 选择需要筛选的列 支持所有字段 |
--filter-key | string | - | 对于资源列，key可以是具体的资源类型，包含totalGPU、memory、baidu.com/*_cgpu等，以及自定义资源。对于非资源列，忽略该字段。资源列：Capacity、Allocatable、Used、Idle、Releasing。非资源列：Name、Status、Taints | ||
--filter-operator | string | - | 对所选的column和key指定操作符，对于资源列支持eq、ne、gt、ge、lt、le。对于非资源列：支持ne、eq。 | ||
--filter-value | string | - | 对于cpu，使用核为单位，对于memory，使用Gi为单位，对于其他类型资源，使用原始值 | ||
精简展示 | cluster、node、job、queue | -r | string | - | -r 选择指定的资源类型展示，如cpu |
-e | string | - | -e 空格分隔的列表，用于排除指定列 |
使用案例
分组汇聚
- 使用job命令根据Status分组汇聚资源使用量
筛选
- 选择剩余gpu大于1的Job
排序
- 按照节点剩余gpu排升序
精简展示
- 只展示node的totalGPU信息
- 只展示指定的列
