1. 课程导论：集群升级背景、Gateway API 多版本路由切换的必要性与挑战

1.1 集群升级：从 Ingress 到 Gateway API 的演进背景

Kubernetes 集群的生命周期管理离不开版本升级。每一次集群版本跃迁，不仅带来控制面与数据面的功能增强，也往往伴随着 API 资源的废弃、替换或版本迭代。在服务网格与南北向流量管理领域，传统的 Ingress 资源因其功能边界模糊、多实现厂商扩展字段不统一、缺乏精细化路由能力等缺陷，已逐渐无法满足云原生网关的复杂需求。

Gateway API 作为 Kubernetes 社区推出的下一代流量管理标准，自 v1alpha2 起逐步成熟，并在 v1beta1 / v1.0 阶段进入生产就绪状态。集群升级后，原有基于 Ingress 或旧版 Gateway API（如 v1alpha2）的路由策略，必须平滑迁移至新版 API 版本（如 v1beta1 / v1.1），否则将面临资源废弃、控制器无法识别、流量中断等风险。

1.2 多版本路由切换的必要性

多版本路由切换并非简单的 API 字段重命名，它涉及资源模型、路由语义、控制器行为、TLS 配置、后端引用方式等多个维度的变更。下表总结了 Gateway API 主要版本之间的关键差异：

从必要性角度，可归纳为以下三点：

• API 生命周期终结： 集群升级后，旧版 API 版本不再被 kube-apiserver 识别，已存在的资源将无法读取或更新。
• 功能缺口： 新版 Gateway API 提供了流量拆分、跨命名空间路由、后端 TLS 等关键能力，旧版本无法支持。
• 生态对齐： 主流网关实现（如 Istio、Contour、Kong、Traefik）已全面转向 v1beta1/v1，旧版本实现逐渐停止维护。

1.3 多版本路由切换的核心挑战

尽管切换势在必行，但在生产环境中执行多版本路由切换仍面临以下挑战：

1. 资源共存与冲突： 同一组路由规则可能同时存在 v1alpha2 和 v1beta1 两份资源，控制器如何处理优先级？是否会重复转发？
2. 控制器兼容性： 部分旧版 Gateway Controller 可能尚未完全支持新版 API，升级后出现“资源已创建但路由不生效”的静默失败。
3. 流量中断风险： 切换过程中，若新旧路由规则未正确衔接，可能导致部分流量丢失、502 错误或灰度比例错乱。
4. CRD 版本迁移： Gateway API 的 CRD 本身存在版本存储迁移（Storage Version），需确保 etcd 中存储的旧版本对象能被正确转换。
5. 团队认知断层： 运维与开发团队对新版路由语义（如 HTTPRoute 的 matches、filters、backendRefs）不熟悉，容易配置错误。

1.4 多版本路由切换的整体流程

下图展示了从集群升级前准备到切换完成后的验证全流程：

1.5 课程目标与演练范围

本课程将围绕“集群升级后 Gateway API 多版本路由切换”这一核心场景，通过可实操的演练步骤，帮助学员掌握以下能力：

• 评估集群升级对现有 Gateway API 路由的影响范围。
• 安全执行 CRD 版本迁移，确保存储版本与 serving 版本一致。
• 使用新版 HTTPRoute / Gateway 资源替换旧版配置，并利用权重路由实现零中断切换。
• 通过 kubectl 命令与控制器日志验证切换结果，并制定回滚策略。