K8s 排障利器:kubectl tree 实战与最佳实践
技术教程 · K8s · 排障 · 2026-09-16
K8s 排障利器:kubectl tree 实战与最佳实践
一、从一个凌晨的回滚说起
上个月帮朋友看一套自建 K8s 集群。发布回滚之后,kubectl get pods -n web 里躺着 6 个 Pod:2 个卡在 Terminating 超过 40 分钟,还有 5 个不同 hash 的 ReplicaSet 排在一起,肉眼根本分不清哪个属于当前 Deployment,哪个是上一版、哪一版是早该被回收的孤儿。
我当时的做法很原始:kubectl get deploy,rs,pods -n web -o yaml,然后在几千行 YAML 里一处处找 ownerReferences,对着 uid 做人工匹配。慢,而且容易看错——尤其在 Pod 名被截断的终端里。
后来我把 kubectl tree 装上了。同样的问题,一条命令:
kubectl tree deployment web -n web
输出的就是一棵按 ownerReferences 还原出来的血缘树,每个节点带着 READY、REASON、STATUS 和 AGE 四列。谁生了谁,谁卡在哪一步,一眼看完。
这个工具是 Ahmet Alp Balkan(@ahmetb)写的,Apache-2.0,GitHub 上 3.4k star,2019 年至今一直在维护,最新版本 v0.6.0(2026-03 发布)。它不是官方 Google 项目,但已经是 K8s 老手的标配 kubectl 插件之一。
二、核心能力:把 ownerReferences 画成树
kubectl tree KIND NAME 干的事情其实很直接:把目标 ns 里(默认同名 ns、只含 namespaced 资源)所有对象的 ownerReferences 拉出来,按 uid 匹配,重建父子关系,然后递归打印。
以一次典型的 Deployment 为例,输出大概长这样:
NAMESPACE NAME READY REASON STATUS AGE
web Deployment/web - Current 12d
web └─ReplicaSet/web-6b8f9c7d4f - Current 2d
web │ └─Pod/web-6b8f9c7d4f-4wpk9 True Current 2d
web │ └─Pod/web-6b8f9c7d4f-q7x2m True Current 2d
web └─ReplicaSet/web-5c4d8b9f77 - Current 12d
web │ └─Pod/web-5c4d8b9f77-hs8zl True Current 12d
web └─HorizontalPodAutoscaler/web True Current 12d
注意最后一行:HPA 也是挂在这棵树上的。这就是 kubectl tree 最容易被低估的价值——它不只画 Deployment→RS→Pod 这条主链,而是把所有以 ownerReferences 指向该对象的资源都接进来。StatefulSet 的 ControllerRevision、Knative 的 Revision/Route、Agones 的 Fleet→GameServerSet→GameServer、cert-manager 的 Certificate→CertificateRequest→Order→Challenge,全都是一棵树。
对 CNCF 生态里的 Operator 类产品尤其好用:CRD 一多,kubectl get 出来是平铺的一堆名字,kubectl tree 直接把 Operator 生成的对象链路摊开,不用再去翻 Operator 源码猜它创建了什么。
顺便把 ownerReferences 这件事说透,因为它解释了这个工具为什么能这么准。ownerReferences 是写在子对象上的一个字段,每条包含 apiVersion、kind、name、uid,以及两个关键开关:controller: true 表示“我是这个子对象的控制器”(K8s 保证一个对象最多一个 controller owner),blockOwnerDeletion: true 表示删除父对象时要先等这个子对象被清掉。垃圾回收器就是照着这两个字段做级联删除的(--cascade=foreground/background),kubectl tree 走的也是同一份数据——所以它显示的不是“猜测的依赖关系”,而是 K8s 自己认的那种所有权。这也是它能直接用来判断“这东西能不能删”的原因。
代价也要说清楚:kubectl tree 会把范围内的对象全量 LIST 到本地内存里再拼树,对 API Server 的负载跟你在一个几千 Pod 的集群上跑 kubectl get all -A 差不多量级。传统做法(get + -o yaml + 人工 grep uid)在单个 Deployment 上大概要 3~4 条命令、十来分钟,还容易看漏一个;换成 kubectl tree 就是一条命令、秒级出结果。省下的不是打字时间,是那种逐行比对 uid 的注意力。
三、READY / REASON / STATUS:卡在哪一环
这三列是它比 kubectl get -o yaml 强的第二个地方。
- READY / REASON:直接取对象的
status.conditions,默认找Ready这个 condition。所以你能看到False和具体 reason(比如ContainersNotReady、ImagePullBackOff背后的 condition reason),而不是只有0/1。 - STATUS:这一列来自
cli-utils/kstatus,取值是Current/InProgress/Failed/Terminating,是用一套统一逻辑从各种资源的 status 里推断出来的,跟 READY 相互独立。 默认只查Ready,但 condition 类型可以自己指定:
# Argo Workflow / CAPI Cluster / cert-manager 的 condition 名字各不相同
kubectl tree application my-app --condition-types=Ready,Synced,Healthy
kubectl tree cluster my-cluster --api-groups='*cluster.x-k8s.io' --condition-types=Ready,Processed
实战里最好用的场景是 cert-manager 证书签发卡住:Certificate → CertificateRequest → Order → Challenge 一路 tree 下来,哪一环 False、reason 是什么,比在四个资源之间来回 kubectl describe 快得多。
四、大集群上别裸跑:--resources 与 --api-groups
这一点必须讲清楚,因为它是这个工具唯一的“性能陷阱”。
kubectl tree 的实现是:并发地把目标范围内所有 API 组的所有资源都 LIST 一遍,分页 250 条一页,然后在本地内存里拼树。默认还不加 label selector。所以在一个几十个 CRD、几千个 Pod 的集群上,它一次会打出海量 list 请求——集群 API Server 和你的 RBAC 都会疼。
v0.5.0 之后加的两个过滤参数就是为这个准备的,支持 glob:
# 只看我关心的资源类型
kubectl tree deployment web -n web --resources=deployments,rs,pods
# 排除掉一堆吵的 API 组,保留核心 + 特定组
kubectl tree nodeclaim my-app --api-groups='core,*karpenter.sh,!*.cert-manager.io'
还有个 -l/--selector 可以直接把数据量砍下来,支持等值、集合、存在三种操作符:
kubectl tree deployment web -n prod -l "tier=frontend,env!=test"
kubectl tree deployment web -n prod -l "env in (prod,staging)"
坑来了:过滤参数会剪断中间节点。因为 kubectl tree 是递归往下走的,如果某个中间 owner 被过滤掉了,遍历就在那里停住。官方 README 里举的例子里最典型的一条:
kubectl tree deployment web --resources=deployments,pods
这条命令什么都出不来——因为 Pod 不是被 Deployment 直接拥有的,中间隔着一层 ReplicaSet,RS 被过滤掉之后,Pod 就永远走不到了。所以用 --resources 时一定要把链路里的每一层都写上。
五、安装(krew 一行搞定)
# 如果还没装 krew
(
set -x; cd "$(mktemp -d)" &&
OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/' -e 's/arm64/arm64/')" &&
curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/krew-${OS}_${ARCH}.tar.gz" &&
tar zxvf "krew-${OS}_${ARCH}.tar.gz" &&
./krew-"${OS}_${ARCH}" install krew
)
# 装 kubectl tree
kubectl krew install tree
kubectl tree --version
不想用 krew 也行,release 里直接给了 darwin/linux/windows × amd64/arm64 的二进制包,解开放到 PATH 里就能当 kubectl-tree 用(kubectl 会自动识别 kubectl-xxx 插件)。注意 krew index 里的版本号跟着 release 走,当前是 v0.6.0。
六、端到端实战:一次回滚后的“孤儿对象”排查
场景:生产 ns 一次 Helm 回滚之后,Pod 数量比期望值多,且有一个 Pod 一直 Terminating。我的排查流程是三步。
第一步,先看主链,确认当前 ReplicaSet 是谁:
kubectl tree deployment web -n prod -c never
-c never 关掉颜色,输出干净,方便贴到工单里。
第二步,看有没有“不该在树上的东西”。 如果 tree 输出里出现了一个 Pod,它的父 ReplicaSet 不是当前 Deployment 指向的那个(对比 kubectl get deploy web -o jsonpath='{.status.currentReplicaSet}' 之类的信息),那它就是上一版残留。这类孤儿往往是因为滚动更新过程中被打断、revisionHistoryLimit 设得太小或太大、或者 finalizer 卡住造成的。
第三步,看 Terminating 那个到底卡在哪:
kubectl tree pod web-6b8f9c7d4f-4wpk9 -n prod --condition-types=Ready,PodScheduled,Initialized
如果这棵“以 Pod 为根”的树是空的(只有 Pod 自己一行),基本可以确认它身上没有任何对象依赖它,可以直接 kubectl delete pod --grace-period=0 --force 收掉;如果它下面挂着东西,说明有对象以它为 owner,就得先处理下游。这个判断在以前要手动查好几处。
顺带一个跨 ns 的用法:某些集群级对象(比如 ClusterRoleBinding 这类 namespace-less 资源)默认不在扫描范围内,需要 -A:
kubectl tree clusterrole system:web -A --resources=clusterrolebindings,clusterroles
-A 会把所有 ns 的所有资源都 LIST 一遍,生产大集群慎用,务必配合 --resources。
七、三个容易踩的坑
-
树是空的,先怀疑 RBAC。 如果当前身份没有 list 权限,
kubectl tree不会报错退出,而是把那类资源静默省略,只在 stderr 留一行cannot query xxx (forbidden), omitting from the tree。所以看到“树怎么这么短”,先kubectl auth can-i --list确认一下。 -
它看不到 Helm / Argo CD 的“父级”。 Helm 的归属关系是靠 labels 和 annotations 记的,Argo CD 用的是 tracking label,都不是
ownerReferences。所以别指望kubectl tree deployment web上面能挂一个“Helm release”。要查 Helm 层面的关系得用helm status/list或helm get manifest。这个误判在新手排障里非常常见。 -
默认不跨 namespace、不含集群级对象。 默认行为是:找目标对象所在 ns 里的 namespaced 对象。跨 ns 或集群级必须显式
-A或-n。这也是它比kubectl get all“看起来漏东西”的原因。
八、适用场景与替代方案
最适合:
-
回滚 / 滚动更新后确认 RS、Pod 归属,清理孤儿对象
-
排查 Operator 生成的 CRD 链路(cert-manager、Karpenter、Knative、CAPI 这类)
-
面试或内部分享时讲清楚“K8s 对象之间的所有权”这件事,比画 PPT 直观
-
让新同学快速建立对一个陌生集群的心智模型 替代 / 互补方案:
-
kube-lineage(kubectl lineage 插件):不只看ownerReferences,还理解一部分逻辑关系(比如 Service→Endpoints→Pod),树的形状不完全一样,可以两个换着用 -
kubectl get -o yaml+jq手撸:能拿到完整字段,但没有任何树的语义,节点一多就崩 -
Lens / Headlamp 的图形视图:直观,但要点鼠标,而且不适合 SSH 到跳板机上干活
-
如果你的团队在往 AI Agent 方向走,
mcp-server-kubernetes这类 MCP Server 已经能把 kubectl 能力暴露给 Claude 之类的客户端,让 Agent 代你跑tree再解释结果——我最近在试这条路,对“不想记命令”的场景挺香
九、我的判断
kubectl tree 是一个典型的“小工具、高杠杆”选手:源码量不大(核心逻辑就是一个并发 LIST + 内存拼树 + 打印),但它把 K8s 里最反直觉的一件事——对象之间的所有权是隐式的,藏在 ownerReferences 里——变成了终端里的一棵树。
它不能替代 kubectl describe(细节还得看 describe 和 events),也不是性能工具(大集群上反而要小心)。但如果只能给 K8s 排障 checklist 加一条命令,我会加它:出问题先跑一遍 tree,30 秒建立层级认知,再决定往哪个方向 dive。
一个实操建议:把常用姿势写进团队 wiki——
alias kt='kubectl tree'
# 大集群上永远带上过滤
alias kt-safe='kubectl tree --resources=deployments,statefulsets,daemonsets,rs,jobs,pods'
省下来的时间不是几秒钟,而是“对着 YAML 找 uid”那种反复确认的注意力。