【kube-apiserver】运维与升级：HA、flags、graceful shutdown 与 etcd 联检
内容提要
kube-apiserver无leader选举，多实例并发运行共享etcd，与controller-manager等不同。运维要点包括：滚动升级逐实例替换、处理409冲突、APF容量为各实例之和。核心flag有--etcd-servers、--etcd-servers-overrides（分集群events）、--request-timeout、--shutdown-delay-duration（需≥LB健康检查间隔×失败阈值）、--encryption-provider-config。升级顺序：etcd→apiserver→controller-manager→scheduler→kubelet，版本偏差不超过2个minor。健康检查中/readyz反映etcd连通性，/healthz不等价于etcd健康。
延伸解读
无选主架构的运维启示
kube-apiserver 多实例并发运行、共享 etcd，无 leader election，这与 controller-manager 和 scheduler 不同。运维上，滚动升级可逐实例替换，无需等待选主；实例崩溃由 LB 摘除流量，无 lease 超时。但多实例并发写可能产生 409 冲突，客户端需处理重试；APF 容量为各实例之和，需注意总排队能力。
graceful shutdown 与 LB 摘除的配合
--shutdown-delay-duration 用于在 SIGTERM 后延迟停止接受新请求，期间 /readyz 可提前失败，让 LB 摘除流量。工程上，该值应不小于 LB 健康检查间隔乘以失败阈值，确保流量先被摘除，避免进程退出与 LB 摘除竞争导致 502。具体值需根据实际 LB 配置调整，无通用常数。
健康检查的语义差异
/healthz 仅反映进程健康，/readyz 包含 etcd 连通性检查，/livez 用于存活探针。graceful shutdown 期间 /readyz 失败而 /livez 仍成功。注意 /healthz 200 不代表 etcd 健康，etcd 不可写时 apiserver 可能仍返回 200（只读请求走缓存）。故障排查需分别检查 apiserver 和 etcd 健康，两者同时异常才能确认是 etcd 层问题。
升级顺序与版本偏差
升级顺序为 etcd → apiserver → controller-manager → scheduler → kubelet，且 apiserver 不可比 kubelet 新超过 2 个 minor，HA 中多实例版本差不超过 1 个 minor。降级无官方支持，需 restore etcd snapshot 并回退二进制。升级前需核对发行版文档中的 etcd 版本矩阵，不能仅依赖 etcd 官方滚动升级说明。
Q&A
kube-apiserver 是否需要进行 leader election？
不需要。kube-apiserver 本身没有 leader election，多个实例并发运行，共享同一 etcd 集群，每个实例独立响应请求。这与 kube-controller-manager 和 kube-scheduler 不同，它们需要 leader lease。
kube-apiserver 滚动升级时需要注意什么？
滚动升级时逐实例替换二进制或镜像，其余实例继续服务，无选主等待。升级顺序为：etcd → kube-apiserver → kube-controller-manager → kube-scheduler → kubelet。版本偏差策略要求 kube-apiserver 不可比 kubelet 新超过 2 个 minor 版本，且 HA 集群中多个 apiserver 实例版本差不超过 1 个 minor。
--etcd-servers-overrides 的作用是什么？
--etcd-servers-overrides 用于为特定 API group 指定独立的 etcd 集群，格式为 <group>/<resource>#<endpoint-list>。典型用法是将 events 分到独立 etcd，例如 --etcd-servers-overrides=/events#https://etcd-events-0:2379,https://etcd-events-1:2379。变更后需滚动重启 apiserver，无热加载。
--shutdown-delay-duration 的作用是什么？如何设置？
--shutdown-delay-duration 是 kube-apiserver 收到 SIGTERM 信号后到真正停止接受新请求之间的延迟。目的是让 LB 健康检查有足够时间把实例从 VIP 摘除，避免少量请求 502。设置建议：应 ≥ LB 健康检查间隔 × 失败阈值次数，具体值依 LB 配置而定。
kube-apiserver 的 /healthz 和 /readyz 有什么区别？
/healthz 表示进程健康（宽松），/readyz 表示是否可接受请求（包括 etcd 连通性检查等）。graceful shutdown 期间 /readyz 会返回失败（触发 LB 摘除），/livez 仍返回成功（不触发 restart）。
kube-apiserver 升级前需要检查哪些 etcd 相关事项？
升级前需检查：etcd 集群健康（quorum 正常）、etcd backend db size 在 quota 内（无 NOSPACE alarm）、etcd 已完成最近一次 snapshot、确认 --etcd-servers / --etcd-servers-overrides 与当前 etcd member 一致、确认 encryption-provider-config 已与新版本兼容等。
