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 强的第二个地方。

# 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。

七、三个容易踩的坑

  1. 树是空的,先怀疑 RBAC。 如果当前身份没有 list 权限,kubectl tree 不会报错退出,而是把那类资源静默省略,只在 stderr 留一行 cannot query xxx (forbidden), omitting from the tree。所以看到“树怎么这么短”,先 kubectl auth can-i --list 确认一下。

  2. 它看不到 Helm / Argo CD 的“父级”。 Helm 的归属关系是靠 labels 和 annotations 记的,Argo CD 用的是 tracking label,都不是 ownerReferences。所以别指望 kubectl tree deployment web 上面能挂一个“Helm release”。要查 Helm 层面的关系得用 helm status/list 或 helm get manifest。这个误判在新手排障里非常常见。

  3. 默认不跨 namespace、不含集群级对象。 默认行为是:找目标对象所在 ns 里的 namespaced 对象。跨 ns 或集群级必须显式 -A 或 -n。这也是它比 kubectl get all “看起来漏东西”的原因。

八、适用场景与替代方案

最适合:

九、我的判断

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”那种反复确认的注意力。