1. 课程导论：升级窗口的概念、为什么需要日志与链路追踪、课程目标与前置知识
1.1 升级窗口：Ingress 控制器的“手术时间”
在 Kubernetes 生产环境中，Ingress 控制器作为南北流量的统一入口，其版本升级、配置变更或证书轮换等操作，通常被安排在预定义的 升级窗口（Upgrade Window） 内执行。升级窗口并非简单的“找个空闲时间”，而是一套包含时间约束、流量控制、回滚预案和观测指标的综合操作规范。
一个典型的升级窗口包含以下核心要素：
| 要素 | 说明 | 常见值/策略 |
|---|---|---|
| 时间窗口 | 允许执行变更的起止时间 | 凌晨 02:00 - 05:00（业务低峰期） |
| 灰度策略 | 流量从旧版本平滑迁移到新版本的方式 | 金丝雀发布（Canary）、蓝绿部署 |
| 观测基线 | 升级前必须确认的稳态指标 | P99 延迟 < 200ms，错误率 < 0.1% |
| 回滚条件 | 触发立即回滚的异常阈值 | 错误率突增 5 倍，或 5xx 比例 > 1% |
| 人工确认点 | 需要 SRE 手动确认的关键步骤 | 金丝雀验证通过后、全量切换前 |
核心认知： 升级窗口的本质是 受控的故障注入。即使是最完美的升级计划，也必然伴随短暂的连接中断、配置重载或路由抖动。日志与链路追踪的价值，就在于将这种“受控的混乱”转化为可观测、可量化、可追溯的数据流。
1.2 为什么需要日志与链路追踪？
在升级窗口期间，Ingress 控制器处于状态转换的临界区。仅依赖传统的“登录 Pod 看日志”或“检查端点健康”已远远不够。我们需要从三个维度构建观测能力：
- 日志（Logs）： 记录控制器内部的状态变更、配置重载事件、TLS 握手失败、后端端点摘除/加入等离散事件。日志是“发生了什么”的第一手证据。
- 指标（Metrics）： 聚合的数值型数据，如请求速率、延迟分布、活跃连接数、证书过期时间。指标是“系统是否健康”的量化仪表盘。
- 链路追踪（Traces）： 记录单个请求从客户端到达 Ingress，再到后端 Service，最后返回响应的完整路径。链路追踪是“哪个环节变慢或出错”的精确诊断工具。
下图展示了升级窗口期间，这三类数据如何协同工作：
实战经验： 在一次 Nginx Ingress 控制器从 1.5.x 升级到 1.6.x 的窗口演练中，指标面板显示错误率正常，但链路追踪发现部分请求的“ingress-connect”阶段耗时从 2ms 飙升到 800ms。最终定位到新版本默认启用了
proxy_protocol，而上游 NLB 未配置对应协议。如果没有链路追踪，这种“隐形劣化”极难被发现。
1.3 课程目标
完成本课程后，你将能够：
- 设计升级窗口的可观测性方案： 为 Ingress 控制器升级规划日志采集、指标聚合和链路追踪的完整数据管道。
- 熟练使用调试工具链： 掌握
kubectl logs、kubectl events、PromQL、Jaeger UI 等工具在升级场景中的组合用法。 - 快速定位典型故障： 能够通过日志中的“配置重载失败”、指标中的“连接数突降”、链路中的“span 缺失”等信号，在 5 分钟内确定根因。
- 编写可复用的调试脚本： 基于课程提供的模板，构建适用于自身环境的升级窗口检查清单和自动化诊断脚本。
1.4 前置知识
为了确保学习效果，建议你具备以下基础：
| 领域 | 具体要求 | 推荐资源 |
|---|---|---|
| Kubernetes 基础 | 理解 Pod、Service、Endpoint、Ingress 资源模型；能使用 kubectl 进行基本操作 | Kubernetes 官方文档：Concepts |
| Ingress 控制器 | 了解 Nginx Ingress 或 Contour 的基本架构；知道 IngressClass 和转发规则 | Ingress 控制器部署指南 |
| 可观测性工具 | 接触过 Prometheus/Grafana 指标面板；了解 Elasticsearch/Loki 日志查询语法 | Prometheus 官方文档：Querying |
| 网络基础 | 理解 HTTP/HTTPS 协议、TLS 握手、反向代理、负载均衡基本概念 | HTTP 权威指南（选读） |
注意： 本课程不涉及 Ingress 控制器的安装部署，也不讲解 Prometheus 或 Jaeger 的搭建细节。我们将聚焦于 升级窗口期间 的调试方法论和实战技巧。如果你对上述前置知识尚不熟悉，建议先花 2-3 小时补齐基础概念。
1.5 课程结构概览
全课程共 30 章，分为四个模块：
- 模块一（第 1-5 章）： 基础概念与观测体系搭建 —— 理解升级窗口、配置日志采集、部署指标监控、接入链路追踪。
- 模块二（第 6-15 章）： 日志调试实战 —— 从控制器日志、访问日志、事件日志中提取故障线索。
- 模块三（第 16-25 章）： 链路追踪深度分析 —— 使用 Jaeger 和 OpenTelemetry 追踪升级过程中的请求路径变化。
- 模块四（第 26-30 章）： 综合演练与自动化 —— 模拟三次典型升级故障，编写自动化诊断脚本，形成组织级升级 SOP。
下图展示了课程的知识体系与学习路径：