【kube-apiserver】APF 与 max-in-flight：公平排队、504 与 etcd lag 分列
内容提要
本文介绍Kubernetes v1.30中kube-apiserver的过载保护机制，包括旧的max-in-flight全局并发限制和新的API Priority and Fairness（APF）公平排队系统。APF通过FlowSchema和PriorityLevel配置，使用SFVR算法实现流量分类和公平调度。文章详细区分429、504等超载症状的排查路径，强调先检查APF等待指标，再排查etcd或Webhook，并提供默认配置和调参建议。
延伸解读
504 排查：先看 APF 等待，再查 etcd
当 kubectl 超时返回 504 时，不要立即怀疑 etcd。本文指出，若 etcd 响应时间正常（如 <10ms），根因可能是请求在 APF 队列中等待超时，未到达存储层。排查顺序应为：先检查 apiserver_flowcontrol_request_wait_duration_seconds 指标，若该指标高，则问题在 APF 排队；若正常，再检查 etcd_request_duration_seconds 和 Admission Webhook 延迟。这一分列思路可避免误判，快速定位过载源头。
APF 与 max-in-flight 的共存与取舍
v1.30 中 APF 是默认路径，但 max-in-flight 仍作为兜底存在。APF 通过 FlowSchema 和 PriorityLevel 实现流量分类与公平排队，能防止低优先级流量饿死高优先级请求（如 LIST 风暴影响 leader election），而 max-in-flight 是全局并发上限，无法区分流量类型。运维上，max-in-flight 配置简单，但 APF 调参复杂，需观察真实流量分布。官方建议不依赖 max-in-flight 作为主要限速，但保留默认值作为最后防线。
APF 调参要点：避免缓冲区膨胀
APF 的队列参数（queues、handSize、queueLengthLimit）需根据生产流量谨慎配置。过小的 queues 会加剧 hash 碰撞，过大的 queueLengthLimit 会导致请求排队时间过长，掩盖真实过载。调参时应优先检查 workload-low 等优先级是否有 LIST 风暴，而非直接调大 nominalConcurrencyShares。同时，exempt 和 leader-election 优先级不建议修改，以保证系统关键请求不受影响。
Q&A
Kubernetes 中 kube-apiserver 的过载保护机制有哪些？
kube-apiserver 有两套过载保护机制：旧的 max-in-flight 全局并发限制（通过 --max-requests-inflight 和 --max-mutating-requests-inflight 设置）和新的 API Priority and Fairness（APF）公平排队系统。两者在 v1.30 中同时存在，但 APF 是默认路径。
kubectl 超时返回 504 时，如何区分是 APF 排队超时还是 etcd 慢？
首先查看 apiserver_flowcontrol_request_wait_duration_seconds 指标。如果该指标 P99 高，说明请求在 APF 排队等待时间过长，导致超过客户端超时，此时 etcd 可能正常。如果 APF wait 指标正常，再查看 etcd_request_duration_seconds，若 etcd 延迟高，则是 etcd 慢导致。
APF 中的 FlowSchema 和 PriorityLevelConfiguration 分别有什么作用？
FlowSchema 用于将请求按规则匹配到对应的 PriorityLevel，通过 matchingPrecedence 决定匹配顺序。PriorityLevelConfiguration 定义并发配额和队列参数，如 nominalConcurrencyShares、队列数等，控制该优先级请求的调度。
APF 的公平排队算法（SFVR）是如何工作的？
APF 使用基于虚拟完成时间（VF）的加权公平排队（WFQ）算法。每个流维护虚拟时钟，新请求的 VF 计算后，调度器优先分发 VF 最小的请求。同时使用 Shuffle Sharding（SFVR）将请求分散到多个队列，防止单个流占满所有队列，保证公平性。
APF 和 max-in-flight 相比有哪些优缺点？
max-in-flight 优点是配置简单，单一旋钮；缺点是无法区分流量类型，高优先级请求可能被低优先级风暴饿死。APF 优点是可以按优先级公平调度，防止低优先级流量影响高优先级请求，减少 P99 突刺；缺点是配置复杂，需要理解 FlowSchema 和队列参数，调参需要生产流量观察。
APF 中默认的 PriorityLevel 有哪些？分别对应什么场景？
默认 PriorityLevel 包括：exempt（无限制，供 system:masters 使用）、leader-election（10，用于租约写操作）、node-high（40，kubelet 节点心跳）、system（30，系统服务账户）、workload-high（40，控制面控制器）、workload-low（100，普通工作负载控制器）、global-default（20，未匹配的请求）、catch-all（5，兜底）。
APF 队列满时返回什么错误？如何监控 APF 的健康状态？
APF 队列满时返回 429 Too Many Requests。监控 APF 健康状态的核心指标是 apiserver_flowcontrol_current_inqueue_requests，如果排队深度持续不为零，说明该优先级并发不足。
