【kube-apiserver】排障五轴：Storage、Watch、Admission、Auth、APF
内容提要
本文介绍kube-apiserver排障方法，提出五轴坐标系：Storage/etcd、Watch/cache、Admission、Auth、APF。通过症状映射表快速定位问题轴，如401/403查Auth，503查Admission，504查APF，410查Watch。强调先定轴再下钻，避免误操作，并列出关键metrics和命令，区分apiserver与etcd问题，指导高效排障。
延伸解读
先定轴再下钻：避免误操作
文章强调排障时先根据症状确定问题轴，再深入排查，避免直接重启或 defrag 等操作。例如，401/403 应查 Auth 轴，503 查 Admission，504 查 APF，410 查 Watch。若症状匹配多轴，应从最靠近客户端的轴（4→3→5→1→2）开始否证，防止在错误层面浪费时间。
apiserver 与 etcd 问题易混淆
文章指出 apiserver 与 etcd 故障的修复动作完全不同，但症状可能相似。例如，etcd 写慢会导致 apiserver 请求挂起，进而 APF 队列打满，出现 504。此时需通过 etcd_request_duration_seconds 等指标判断根因，避免在 apiserver 侧重启而 etcd 问题未解决。
APF 与 etcd 延迟的联动关系
APF 流控与 etcd 延迟并非互斥：etcd 写慢会使请求挂起，占满 APF 席位，导致后续请求 504。排障时应从客户端时间戳倒推，先到的轴可能是根因。若 APF 队列深度高但 etcd 延迟正常，则问题在 apiserver 侧；反之则需穿透到 etcd 排查。
Q&A
kube-apiserver 排障时，如何根据错误码快速定位问题轴？
根据症状映射表：401/403 查 Auth 轴，503 查 Admission 轴，504 查 APF 轴，410 查 Watch 轴。若症状匹配多轴，从最靠近客户端的轴（4→3→5→1→2）开始否证。
kube-apiserver 的排障五轴分别是什么？
五轴分别是：Storage/etcd、Watch/cache、Admission、Auth、APF。Storage 轴关注 etcd 耦合，Watch 轴关注缓存与 watch 机制，Admission 轴关注 webhook 和内置插件，Auth 轴关注认证与授权，APF 轴关注流量控制。
kube-apiserver 返回 410 Gone 时，可能的原因有哪些？
可能原因包括：cacher bookmark 落后于客户端 resourceVersion，或 etcd compaction 清掉了 start_rev。需要先查 apiserver cacher 日志（是否 cache miss），再查 etcd compaction rev。
kube-apiserver 的 Admission 轴出现问题时，为什么不应该去查 etcd？
因为 Admission 链在 storage.Interface 调用之前执行，webhook 返回 503 时 etcd 无写入记录，所以不应在 etcd 侧查原因。
kube-apiserver 返回 401 和 403 分别代表什么？
401 表示身份未确认（AuthN 层），403 表示身份已确认但无权限（AuthZ 层）。两者都在 Admission 链之前，收到 403 不意味着 webhook 或 etcd 有问题。
kube-apiserver 出现 504 超时，如何判断是 APF 问题还是 etcd 问题？
先看 APF 队列是否满（apiserver_flowcontrol_current_inqueue_requests 高），若是则调 FlowSchema/PriorityLevel 或降低请求速率；若否，再看 etcd_request_duration_seconds 是否高，高则穿透到 etcd 排障；若否，再检查 Admission webhook 延迟；最后检查 apiserver 进程本身。
kube-apiserver 排障时，有哪些关键 metrics 可以用于定位问题？
关键 metrics 包括：apiserver_request_duration_seconds（全轴）、etcd_request_duration_seconds（轴1）、apiserver_current_inflight_requests（轴5）、apiserver_flowcontrol_current_inqueue_requests（轴5）、apiserver_admission_webhook_admission_duration_seconds（轴3）、apiserver_longrunning_requests（轴2）等。
kube-apiserver 排障时，如何区分是 apiserver 问题还是 etcd 问题？
若 apiserver 日志报 etcd request failed 且 etcd_request_duration_seconds 持续高，则穿透到 etcd 排障；若 etcd 自身健康（endpoint health 全绿、wal_fsync 正常）但 apiserver Storage 仍报错，则留在 apiserver 轴（codec、encrypt、prefix 路径）。
