【kube-apiserver】排障五轴：Storage、Watch、Admission、Auth、APF

「apiserver 挂了」与「etcd 挂了」的修复动作完全不同——前者的可能原因包括 APF 队列打满、Admission webhook 超时、watch cache 未命中回 etcd，以及 Auth 拒绝；后者可能是 Raft quorum 丢失、quota 触顶、Watch ErrCompacted。混因最常见的结果是在 etcd 侧 defrag 而 apiserver APF 队列继续积压，或者在 apiserver 侧重启而 etcd 写超时持续。

本文是第 15 篇：症状 → 轴 映射与命令表。口诀不变：先点名轴，再下钻组件。etcd 生产排障见 etcd/15；运维动作见 第 14 篇。无 K8s 集群则不粘贴伪造 kubectl 输出或 metrics 截图。

本篇在系列中的位置

篇目	核心内容
第 14 篇 · 运维与升级	HA、flags、graceful shutdown
第 15 篇 · 排障五轴	Storage/Watch/Admission/Auth/APF 口令表
第 16 篇 · 选型收束	排除树、开放问题、边界关闭
系列目录	全部篇目

版本锚定：kube-apiserver v1.30.3（tag v1.30.3）。指标名以该版本 apiserver 为准（metrics 注册在 staging/src/k8s.io/apiserver/）。本篇坐标系仅指 kube-apiserver 五轴，不与 etcd 五轴混用；两轴分列见 §七。

一、口诀与总图

轴 1  Storage / etcd 耦合  — storage.Interface、etcd3 gRPC、rv 映射、compact revision
轴 2  Watch / cache       — cacher、bookmark、resourceVersion、reflector、ErrCompacted
轴 3  Admission           — webhook timeout/failurePolicy、CEL、内置插件
轴 4  Auth                — AuthN 401、AuthZ 403、Audit webhook 失败
轴 5  APF / 流控          — FlowSchema、PriorityLevel、排队 504、max-in-flight

flowchart TD
  symptom["Symptom"]
  symptom --> name["Name apiserver axis first"]
  name --> a1["Axis1 Storage/etcd"]
  name --> a2["Axis2 Watch/cache"]
  name --> a3["Axis3 Admission"]
  name --> a4["Axis4 Auth"]
  name --> a5["Axis5 APF"]
  a1 --> drill["Drill: metrics / logs / etcd/15?"]
  a2 --> drill
  a3 --> drill
  a4 --> drill
  a5 --> drill

默认顺序（无其他线索时）：轴 4 Auth → 轴 3 Admission → 轴 5 APF → 轴 1 Storage → 轴 2 Watch。实际应先看错误码和 audit log，用下一节的映射表直接定轴。

二、症状 → 轴（入口表）

原则：症状匹配多轴时，从最靠近客户端的轴（4 → 3 → 5 → 1 → 2）开始否证。

三、轴 1：Storage / etcd 耦合

表象：写操作返回 500 或超时；etcd request failed；rv 不一致；对象版本回退。

与 etcd/15 分列口诀：apiserver 日志报 etcd request failed + etcd_request_duration_seconds 持续高 → 穿透到 etcd/15 做 etcd 五轴；若 etcd 自身健康（endpoint health 全绿、wal_fsync 正常）但 apiserver Storage 仍报错 → 留在 apiserver 轴（codec、encrypt、prefix 路径）。

四、轴 2：Watch / cache

表象：Watch 断流；客户端收到 410 Gone；List 引发内存暴涨；controller 停更。

410 Gone 分列：410 来自 cacher bookmark 未推进 OR etcd compaction → 先查 apiserver cacher 日志（是否 cache miss）；再查 etcd compaction rev（etcdctl endpoint status RAFT APPLIED INDEX vs 客户端 rv）。

List 风暴关键点：consistent list（resourceVersion=""）每次都穿透 etcd Range；大量 consistent list 并发是 etcd 轴 3/4 的放大器——APF 轴（轴 5）应优先拦截，再处理 etcd 侧成本。

五、轴 3：Admission

表象：特定资源创建/更新返回 503；admission webhook denied；写慢但 etcd 健康。

Admission 不是 etcd 问题：Admission 链在 storage.Interface 调用之前执行。webhook 503 时 etcd 无写入记录，不要在 etcd 侧查原因。

六、轴 4：Auth

表象：所有/特定请求 401 或 403；audit log 中 decision: deny。

401 vs 403 分列：401 = 身份未确认（AuthN 层）；403 = 身份确认但无权限（AuthZ 层）。两者都在 Admission 链之前——收到 403 不意味着 webhook 或 etcd 有问题。

七、轴 5：APF / 流控

表象：请求被 429 拒绝；504 超时（排队超时）；apiserver_current_inflight_requests 高位震荡；OOM。

504 归因分列：

flowchart TD
  t504["504 Gateway Timeout"]
  t504 --> apf{"APF queue\nfull / timeout?"}
  apf -->|"Yes: apiserver_flowcontrol\n_current_inqueue_requests 高"| fix_apf["调 FlowSchema/PriorityLevel\nor 降低请求速率"]
  apf -->|"No"| etcd_lat{"etcd_request_duration\n_seconds 高?"}
  etcd_lat -->|"Yes"| etcd15["穿透 etcd/15\n轴 1–3"]
  etcd_lat -->|"No"| adm{"Admission\nwebhook 慢?"}
  adm -->|"Yes"| fix_adm["检查 webhook 延迟"]
  adm -->|"No"| other["apiserver 进程本身：\ncpu/memory；gc 压力"]

APF 与 etcd lag 不互斥：etcd 写慢 → apiserver 请求挂起 → APF 席位被占满 → 后续请求 504。故障序列可能两轴同时亮——从客户端时间戳倒推，先到的轴是根因。

八、命令表（语义；无伪造输出）

以下命令均基于 v1.30.3 apiserver 与标准 kubectl，未在本环境执行。命令格式以 kubectl --help 与官方文档为准。

实验台账：上述命令未在本环境执行，输出未展示；数字阈值以你的环境 baseline 为准，本篇不固化告警值。

九、关键 metrics 语义（名称；无截图）

使用原则：这些指标名以 v1.30.3 apiserver metrics 注册（staging/src/k8s.io/apiserver/pkg/endpoints/metrics/）为准；不写告警阈值（依赖环境 baseline 与 SLO，不在此硬编码）。

十、与 etcd/15 五轴的分列

穿透判定：若 etcd_request_duration_seconds 高位（Storage 轴有信号）→ 穿透到 etcd/15；否则留在 apiserver 五轴。一次 incident 优先在一层否证，不要同时跑两套排障流程。

与 etcd 五轴的互补分工口诀：

轴 1 Storage/etcd  ← etcd_request_duration_seconds → 穿透 etcd/15 轴 1–3
轴 2 Watch/cache   ← ErrCompacted              → 穿透 etcd/15 轴 4
轴 3 Admission     ← webhook 504/timeout        → 留 apiserver 轴 3
轴 4 Auth          ← 401/403                   → 留 apiserver 轴 4
轴 5 APF           ← 排队/429                  → 留 apiserver 轴 5；间接驱动 etcd 负载

十一、证据包写法

工单或 postmortem 建议按轴贴证据：

Axis1 Storage: etcd_request_duration_seconds p99; apiserver etcd connection errors
Axis2 Watch:   apiserver_longrunning_requests; cacher logs; ErrCompacted events
Axis3 Admission: webhook admission_duration_seconds; webhook endpoint health
Axis4 Auth:    audit log decision=deny; AuthN provider health
Axis5 APF:     flowcontrol_current_inqueue_requests; rejected_requests_total; inflight

一次 incident 只验证一轴假设；否证后再换轴。

参考资料

规范 / 官方文档（A）

• Kubernetes v1.30 · API Priority and Fairness
• Kubernetes v1.30 · Auditing
• Kubernetes v1.30 · Admission Controllers

源码（A）

• kubernetes/kubernetes tag v1.30.3：staging/src/k8s.io/apiserver/pkg/endpoints/metrics/；staging/src/k8s.io/apiserver/pkg/util/flowcontrol/；staging/src/k8s.io/apiserver/plugin/pkg/admission/

站内

• etcd/15 · 排障五轴
• 第 3 篇 · storage.Interface
• 第 5 篇 · Watch cache
• 第 9 篇 · Webhook
• 第 12 篇 · APF
• 第 16 篇 · 选型收束

实验台账

• 命令与 metrics 名：未在本环境执行；名称与语义来自 v1.30.3 源码与官方文档。不粘贴伪造输出。

上一篇：运维与升级

下一篇：选型收束与开放问题