【kube-apiserver】运维与升级：HA、flags、graceful shutdown 与 etcd 联检

kube-apiserver 的运维有一个常见误区：把它当成 etcd 的配套组件一起「选主」。实际上 kube-apiserver 本身无 leader election——多实例并发运行，共享同一 etcd 集群，每个实例独立响应请求。这与 kube-controller-manager 和 kube-scheduler（需要 leader lease）不同，也与 etcd 本身（Raft 选主）不同。升级顺序、flag 语义和 graceful shutdown 都从这个前提出发。

本文钉 Kubernetes v1.30.3 的 kube-apiserver 运维路径，并提供与 etcd/14 的联合升级检查视角。

本篇在系列中的位置

篇目	核心内容
第 13 篇 · 扩展边界	CRD/APIService 停损线
第 14 篇 · 运维与升级	HA、flags、graceful shutdown、etcd 联检
第 15 篇 · 排障五轴	Storage/Watch/Admission/Auth/APF 口令表
系列目录	全部篇目

版本锚定：kube-apiserver v1.30.3（源码 tag v1.30.3）。etcd 后端对照 etcd v3.5.33。升级行为以 v1.30.3 CHANGELOG 与官方 skew policy 为准；v1.31+ 独有变化不写成 v1.30.3 事实。

一、高可用：多实例无 leader election

1.1 kube-apiserver HA 模型

多个 kube-apiserver 实例可以同时运行，每个都：

• 持有独立的 --etcd-servers 连接池；
• 通过 load balancer（云厂商 LB 或 HAProxy/keepalived）暴露统一 VIP；
• 互不感知——没有实例间的协调协议。

flowchart LR
  client["kubectl / controllers"]
  lb["Load Balancer / VIP"]
  api1["kube-apiserver :6443"]
  api2["kube-apiserver :6443"]
  etcd["etcd cluster (3/5 nodes)"]

  client --> lb
  lb --> api1
  lb --> api2
  api1 -->|"gRPC"| etcd
  api2 -->|"gRPC"| etcd

与 etcd 对比：etcd 必须通过 Raft 选出 Leader 才能接受写请求；kube-apiserver 不需要，写一致性由 etcd 保证（所有实例写同一 etcd 后端，MVCC 冲突由 GuaranteedUpdate compare-and-swap 处理）。

与 kube-controller-manager / kube-scheduler 对比：两者都用 Lease 资源做 leader election（通过 apiserver 写 etcd）。kube-apiserver 自身没有此类 Lease。多实例 apiserver 场景下，所有实例处于 active 状态，不存在 standby 等待选主。

1.2 无 leader election 的运维含义

• 滚动升级：逐实例替换二进制/镜像，其余实例继续服务，无选主等待；
• 实例崩溃：LB 健康检查摘除，其余实例接管，无 leader lease 超时；
• 反面：多实例并发写可能产生 409 冲突（乐观并发），客户端应处理 retry；
• 反面：APF（API Priority and Fairness）配置是每实例独立执行，总排队容量为各实例之和而非集中队列（第 12 篇）。

二、核心 flag 语义

以下只讲语义，不模拟输出。具体默认值以 kube-apiserver --help 或 v1.30.3 源码为准。

2.1 --etcd-servers

指定 etcd endpoint 列表，逗号分隔。kube-apiserver 对列表中所有 endpoint 做负载均衡（由 etcd client-go 库管理）。

--etcd-servers=https://etcd-0:2379,https://etcd-1:2379,https://etcd-2:2379

运维要点： - 列表与 etcd member 列表保持一致；member replace 后同步更新此 flag； - 不要填入未认证 endpoint（加密与证书见 --etcd-cafile、--etcd-certfile、--etcd-keyfile）。

2.2 --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

语义：命中该规则的资源读写走独立 endpoint，其余走 --etcd-servers。这是 Kubernetes 控制面最常见的「events 分集群」实现手段（见第 16 篇）。

运维要点： - 独立 etcd 集群须有自己的备份/升级窗口； - --etcd-servers-overrides 变更后需滚动重启 apiserver（无热加载）。

2.3 --request-timeout

请求级别超时，默认 60s（v1.30.3；以源码为准）。超过后 apiserver 返回 504。与 APF 排队时间叠加，不是独立计时——请求在 APF 队列里等待的时间计入此超时。

2.4 --shutdown-delay-duration（graceful shutdown）

在收到 SIGTERM 信号到真正停止接受新请求之间的延迟，默认值在 v1.28+ 稳定（以 v1.30.3 源码为准，常见值为 0 或若干秒）。

语义：

1. kube-apiserver 收到 SIGTERM；
2. --shutdown-delay-duration 期间仍继续服务请求（Readiness probe 可提前改为 failing，让 LB 摘除流量）；
3. 延迟结束后，进入 graceful drain——等待 in-flight 请求完成或超时；
4. 进程退出。

目的是让 LB 健康检查有足够时间把实例从 VIP 摘除，再停止接受新连接，避免 LB 摘除延迟与进程退出竞争导致少量请求 502。

工程判断：--shutdown-delay-duration 应 ≥ LB 健康检查间隔 × 失败阈值次数，确保 LB 先摘流量。具体值依 LB 配置而定，无通用常数。

2.5 --encryption-provider-config（语义边界）

指定 etcd 静态数据加密配置文件路径（EncryptionConfiguration）。启用后，apiserver 在写 etcd 前对指定资源加密，读时解密。

本篇只讲语义边界：

加密全书见 Kubernetes 官方文档 · Encrypting Confidential Data at Rest；本系列不写 KMS 全书。

2.6 Audit 相关 flag

--audit-log-path、--audit-policy-file 等控制审计日志；--audit-webhook-config-file 把审计事件发给外部 backend。audit webhook 失败可能阻塞请求（取决于 failurePolicy），排障见第 15 篇 Auth 轴。

三、graceful shutdown 与 etcd 联检要点

3.1 apiserver 升级前联检（与 etcd/14 对照）

[ ] etcd 集群健康（quorum 正常；`etcdctl endpoint health` 无 unhealthy）
[ ] etcd backend db size 在 quota 内（无 NOSPACE alarm）
[ ] etcd 已完成最近一次 snapshot（backup 有效期内）
[ ] apiserver 多实例：确认实例数量与 LB backend 配置
[ ] 确认 kube-controller-manager / kube-scheduler leader lease 持有者正常
[ ] 确认 --etcd-servers / --etcd-servers-overrides 与当前 etcd member 一致
[ ] 确认 encryption-provider-config（如启用）已与新版本兼容
[ ] 已阅读 v1.30.x CHANGELOG 与 release notes 中的 API 变化
[ ] 滚动替换第一个 apiserver 实例后，验证 /healthz / /readyz 返回 200

以上为操作员提示，不是自动化通过的绿标。每项均需人工核对，环境状态以实际观测为准。

3.2 apiserver 版本偏差策略（skew policy）

Kubernetes 官方 版本偏差策略（A 级）规定：

• kube-apiserver 不可比 kubelet 新超过 2 个 minor 版本（v1.30 apiserver 支持 kubelet v1.28/v1.29/v1.30）；
• kube-apiserver 不可比 kube-controller-manager / kube-scheduler 旧（升级时先升 apiserver）；
• HA 集群中多个 apiserver 实例版本差不超过 1 个 minor。

升级顺序：etcd → kube-apiserver（逐实例）→ kube-controller-manager → kube-scheduler → kubelet。

反方向（降级/rollback）：K8s 没有官方支持的原地 minor 降级路径；需要 restore etcd snapshot（来自升级前备份）+ 回退旧二进制。

3.3 etcd 版本矩阵

kube-apiserver v1.30.3 通常配套 etcd 3.5.x。具体的「K8s minor + etcd minor 支持矩阵」由各 K8s 发行版（Kubeadm、RKE、EKS、GKE 等）单独维护——升级前须核对你的发行版文档，不能只看 etcd 官方「可 rolling upgrade」。

etcd 侧升级门（3.5 → 3.6 → 3.7）见 etcd/14 第五、六节。

四、apiserver 日志与健康检查语义

4.1 健康检查 endpoint

graceful shutdown 期间 /readyz 会返回失败（触发 LB 摘除），/livez 仍返回成功（不触发 restart）。

4.2 与 etcd 健康检查分列

apiserver /healthz 不等价于 etcd 健康——etcd 集群不可写时，apiserver 仍可能返回 /healthz 200（部分只读请求走 watch cache 缓存）。故障时须分别检查：

apiserver: kubectl get --raw /healthz ; kubectl get --raw /readyz
etcd:      etcdctl endpoint health --write-out=table

两者同时红才能确认是 etcd 层问题；只有 apiserver 红时先走 apiserver 五轴（第 15 篇）。

五、边界

参考资料

规范 / 官方文档（A）

• Kubernetes · Version skew policy
• Kubernetes · Operating etcd clusters for Kubernetes
• Kubernetes · Encrypting Confidential Data at Rest
• Kubernetes v1.30 · API Priority and Fairness

源码（A）

• kubernetes/kubernetes tag v1.30.3：pkg/kubeapiserver/options/；staging/src/k8s.io/apiserver/pkg/server/（graceful shutdown）

站内

• etcd/14 · 运维与升级
• 第 12 篇 · APF
• 第 15 篇 · 排障五轴
• 第 16 篇 · 选型收束

实验台账

• apiserver flag / graceful shutdown / 升级：未在本环境执行；语义来自官方文档与 v1.30.3 源码。不粘贴伪造 kubectl 输出或 metrics 截图。

上一篇：CRD / aggregation / 扩展边界

下一篇：排障五轴