蜷缩的蜗牛
蜷缩的蜗牛

Kubernetes故障排查实战手册

kbsonlong
  约 2700 字 预计阅读 6 分钟 - 次阅读  

Kubernetes故障排查实战手册

本文档适用于生产环境下Kubernetes集群常见故障的排查与优化，涵盖APIServer接口延时、etcd性能、Token失效、cacher超时、资源竞争等典型问题。建议结合实际监控与日志，按步骤定位和解决。 持续更新ing

1. APIServer接口请求延时排查

1.1 现象

  • kubectl、API调用响应慢，监控显示apiserver延时高。
  • 日志中出现 Listing from storage done xxxms，耗时较高。

1.2 排查步骤

  1. 查看apiserver trace日志
    1

    grep "Listing from storage done" /var/log/kube-apiserver.log | sort -k6 -n | tail -20
  2. 分析慢点
    • 如果大部分耗时集中在Listing from storage done，说明etcd存储阶段慢。
    • 关注total time，如大于300ms需重点关注。
  3. 结合Prometheus监控
    • 关注apiserver_request_duration_seconds、etcd_request_duration_seconds等指标。
    • 示例PromQL：
      1

      histogram_quantile(0.99, sum(rate(apiserver_request_duration_seconds_bucket[5m])) by (le, verb, resource))

1.3 日志示例 

1
2
3

I0625 16:09:02.406986    6468 trace.go:205] Trace[816016811]: "List" url:/api/v1/pods,user-agent:kubectl/v1.20.10,client:127.0.0.1 (25-Jun-2025 16:09:01.186) (total time: 1220ms):
Trace[816016811]: ---"Listing from storage done" 1220ms (16:09:00.406)
Trace[816016811]: [1.220921602s] [1.220921602s] END

2. etcd性能与健康排查

2.1 现象

  • apiserver与etcd连接频繁切换，日志中有transport is closing。
  • etcd响应慢，apiserver接口延时高。

2.2 排查步骤

  1. 检查etcd健康
    1
2

    ETCDCTL_API=3 etcdctl --endpoints=<etcd-endpoints> endpoint health
ETCDCTL_API=3 etcdctl --endpoints=<etcd-endpoints> endpoint status --write-out=table
  2. 检查etcd资源
    • 重点关注磁盘IO、延迟、CPU、内存。
    • 检查etcd节点是否与apiserver共用宿主机和磁盘（不推荐）。
  3. 查看etcd慢日志
    • 检查etcd日志中snapshot、apply、fsync等关键字。

2.3 日志示例 

1
2
3
4
5
6

I0625 16:09:09.842736   60187 client.go:360] parsed scheme: "passthrough"
I0625 16:09:09.842757   60187 passthrough.go:48] ccResolverWrapper: sending update to cc: {[{https://<etcd-x>.com:2379  <nil> 0 <nil>}] <nil> <nil>}
I0625 16:09:09.842764   60187 clientconn.go:948] ClientConn switching balancer to "pick_first"
I0625 16:09:09.842858   60187 balancer_conn_wrappers.go:78] pickfirstBalancer: HandleSubConnStateChange: ..., {CONNECTING <nil>}
I0625 16:09:09.847558   60187 balancer_conn_wrappers.go:78] pickfirstBalancer: HandleSubConnStateChange: ..., {READY <nil>}
I0625 16:09:09.848203   60187 controlbuf.go:508] transport: loopyWriter.run returning. connection error: desc = "transport is closing"

3. Token失效与认证失败

3.1 现象

  • 日志中出现Unable to authenticate the request due to an error: [invalid bearer token, Token has been invalidated]
  • 业务组件、kubectl等频繁认证失败。

3.2 排查步骤

  1. 检查token是否过期或被撤销
  2. 检查kubeconfig配置，确保使用最新token。
  3. 如为ServiceAccount，尝试重建secret并分发。

3.3 日志示例 

1

E0625 18:10:07.332983   60187 authentication.go:53] Unable to authenticate the request due to an error: [invalid bearer token, Token has been invalidated]

4. cacher超时与watcher异常

4.1 现象

  • 日志中出现Forcing watcher close due to unresponsiveness。
  • 业务组件watch接口断流、重连频繁。

4.2 排查步骤

  1. 检查下游watcher处理能力，如自定义controller、kubectl watch等。
  2. 检查apiserver资源利用率，如CPU、内存、磁盘。
  3. 关注网络链路是否异常。

4.3 日志示例 

1

I0625 18:10:25.677715   60187 cacher.go:1238] Forcing watcher close due to unresponsiveness: *unstructured.Unstructured

5. 资源竞争与部署建议

5.1 现象

  • apiserver与etcd共用宿主机和磁盘，性能互相影响。
  • etcd写入延迟高，apiserver接口延时高。

5.2 优化建议

  • 物理隔离：apiserver与etcd分开部署，etcd独享高性能SSD。
  • 磁盘隔离：如必须同机，保证etcd使用独立物理磁盘。
  • 资源限制：通过cgroup、systemd、K8s requests/limits限制资源。
  • 监控与告警：重点监控磁盘延迟、IOPS、etcd fsync延迟等。

6. 常用排查命令与工具

  • 查看apiserver慢请求：
    1

    grep "Listing from storage done" /var/log/kube-apiserver.log | sort -k6 -n | tail -20
  • 检查etcd健康：
    1

    ETCDCTL_API=3 etcdctl --endpoints=<etcd-endpoints> endpoint health
  • 检查etcd慢日志：
    1

    grep slow /var/log/etcd.log
  • 查看apiserver、etcd资源：
    1

    top, iostat, vmstat, sar 等
  • Prometheus监控指标：
    • apiserver_request_duration_seconds
    • etcd_request_duration_seconds

7. 优化建议与最佳实践

  • apiserver与etcd物理隔离，etcd独享SSD。
  • 定期检查token有效性，及时轮换。
  • 监控慢请求，及时扩容或优化。
  • 业务watcher合理限流，避免拖垮apiserver。
  • 生产环境建议etcd节点奇数、独立部署、定期备份。

8. etcd快照备份导致的性能问题排查与优化

8.1 现象

  • etcd集群在整点或固定时间段出现请求延时高峰，表现为apiserver接口响应变慢，监控中etcd相关请求延时（如etcd_request_duration_seconds_bucket）突增。
  • 业务组件、Kubernetes控制面等依赖etcd的操作在高峰时段出现卡顿。
  • etcd磁盘写入延时（fsync/commit）指标正常，但整体请求处理延时大。

8.2 排查步骤

  1. 监控分析
    • 通过Prometheus等监控系统，重点关注etcd_request_duration_seconds_bucket，按instance、type维度分析延时高的节点和操作类型。
    • 观察延时高峰是否有明显的时间规律（如整点），结合业务和系统定时任务排查。
  2. 定时任务排查
    • 检查etcd节点本地crontab、Kubernetes CronJob、外部自动化脚本等，确认是否有定时执行etcd快照（snapshot）备份任务。
    • 常见备份命令示例：
      1

      etcdctl snapshot save /backup/etcd-$(date +%Y%m%d%H%M%S).db
  3. etcd慢日志分析
    • 启用etcd慢日志（如--experimental-warning-apply-duration=500ms），在高峰时段查看慢日志，定位慢请求内容和来源,3.6版本引入的实验性特性。
    • 日志关键字：snapshot save、took too long。
  4. 节点角色与备份影响分析
    • 通过etcdctl endpoint status或监控etcd_server_is_leader，识别leader和follower节点，分析备份任务对不同节点的影响。

8.3 日志与监控分析示例

  • 监控中etcd请求延时在整点出现规律性高峰： etcd延时高峰示意图
  • etcd慢日志示例：
    1
2

    apply request took too long [1200.123ms] to execute
snapshot save /backup/etcd-20240626100000.db
  • Prometheus查询示例：
    1

    histogram_quantile(0.99, sum(rate(etcd_request_duration_seconds_bucket[5m])) by (le, instance, type))

8.4 优化建议

  1. 备份节点选择
    • 优先在follower节点执行快照，避免影响leader写入性能。
    • 备份前自动判断节点角色，仅在follower上执行snapshot save。
  2. 备份方式优化
    • 可将本地crontab备份调整为Kubernetes CronJob远程备份，减少etcd节点本地IO压力，但需关注网络带宽消耗和安全性。
  3. 备份限速
    • 使用ionice和nice降低备份进程的IO和CPU优先级：
      1

      ionice -c2 -n7 nice -n 19 etcdctl snapshot save ...
    • 使用pv或trickle等工具限制备份速率：
      1

      etcdctl snapshot save /dev/stdout | pv -L 10m > /backup/etcd.db
  4. 错峰与频率调整
    • 多节点集群备份任务错开时间，避免同时高IO。
    • 合理设置备份频率，避免过于频繁。
  5. 备份存储优化
    • 备份文件优先存储到独立磁盘或远程存储，避免与etcd数据盘争抢IO。
    • 备份后异步上传到对象存储，定期清理本地旧快照。
  6. 监控与告警
    • 备份期间重点监控etcd延时、QPS、磁盘IO、网络带宽等指标。
    • 设置延时、磁盘空间等告警，及时发现异常。
  7. 安全与一致性
    • 远程备份需做好etcd访问权限和证书管理，防止泄露。
    • 备份完成后校验快照文件完整性。
更新于 2025-06-26 
CC BY-NC 4.0
阅读原始文档
LINE Myspace
返回 | 主页
0%