3. 集群升级对 Ingress 的影响：API 版本变更、注解兼容性与 Webhook 配置变化
Kubernetes 集群升级过程中，Ingress 控制器是受影响最直接的组件之一。API 版本废弃、注解语义调整以及 Webhook 配置的变更，都可能导致流量中断或路由规则失效。本章从三个核心维度分析升级风险与应对策略。
3.1 API 版本变更：从 networking.k8s.io/v1beta1 到 v1
Kubernetes 1.19 起，networking.k8s.io/v1beta1 版本的 Ingress 资源被标记为废弃，并在 1.22 版本中彻底移除。升级到 1.22+ 的集群必须使用 networking.k8s.io/v1 版本。两个版本在结构上存在关键差异，尤其是 spec.rules[].http.paths[].backend 字段的扁平化。
| 对比维度 |
v1beta1（旧版） |
v1（新版） |
| backend 结构 |
serviceName + servicePort（字符串/整数） |
service.name + service.port.number / service.port.name |
| pathType 要求 |
可选，默认实现因控制器而异 |
必填，取值 Prefix、Exact、ImplementationSpecific |
| IngressClassName |
通过 kubernetes.io/ingress.class 注解指定 |
推荐使用 spec.ingressClassName 字段，注解仍兼容但优先级低 |
| TLS 字段 |
tls[].hosts 与 tls[].secretName |
结构相同，但 secretName 必须指向同一命名空间的 Secret |
升级前必查：使用 kubectl convert -f ingress.yaml --output-version networking.k8s.io/v1 命令批量转换存量 YAML 文件，并检查 pathType 字段是否缺失。缺少 pathType 的 Ingress 在 v1 下会被 API Server 拒绝创建。
3.2 注解兼容性：控制器特有的迁移陷阱
Ingress 控制器（如 Nginx Ingress、Traefik、HAProxy Ingress）大量依赖注解来扩展功能。集群升级后，部分注解的语法或作用域可能发生变化。以下为 Nginx Ingress Controller 在升级过程中最常见的注解兼容性问题。
- 重定向注解变更：
nginx.ingress.kubernetes.io/rewrite-target 在 v1.0+ 中要求使用 $1、$2 捕获组，旧版 $1$2$3 格式不再支持。
- SSL 注解废弃：
nginx.ingress.kubernetes.io/ssl-redirect 被 nginx.ingress.kubernetes.io/force-ssl-redirect 替代，旧注解在升级后可能被忽略。
- 配置片段注解：
nginx.ingress.kubernetes.io/server-snippet 和 configuration-snippet 的生效顺序在 v1.2+ 中调整为全局配置后执行，可能导致自定义逻辑失效。
- 上游超时注解：
nginx.ingress.kubernetes.io/proxy-read-timeout 的单位从秒（s）变为毫秒（ms），未加单位的值会被视为毫秒，导致超时时间缩短。
最佳实践：在升级 Ingress Controller 之前，先查阅目标版本的 Changelog 和 Annotation Migration Guide。使用 kubectl annotate --list 导出当前集群中所有 Ingress 资源的注解，与新版文档逐条比对。
3.3 Webhook 配置变化：准入控制与证书轮换
Ingress 控制器通常通过 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 实现资源校验与默认值注入。集群升级时，Webhook 配置可能因以下原因导致故障：
- CA 证书过期或变更：Kubernetes 控制面升级后，API Server 的 CA 证书可能轮换。Webhook 配置中
clientConfig.caBundle 必须更新为新的 CA 证书，否则 API Server 无法验证 Webhook 服务端证书。
- Webhook 服务端口变更：部分 Ingress Controller 在升级后默认监听端口从 443 改为 8443，若 Webhook 配置中
url 或 service.port 未同步更新，请求将被拒绝。
- failurePolicy 默认值调整：Kubernetes 1.21+ 将
failurePolicy 的默认值从 Ignore 改为 Fail。升级后，未显式设置 failurePolicy: Ignore 的 Webhook 一旦不可用，将导致所有 Ingress 资源的创建/更新操作失败。
- matchPolicy 与对象选择器：升级后
matchPolicy 的默认行为可能从 Exact 变为 Equivalent，导致 Webhook 拦截到预期之外的资源版本。
验证命令：升级后执行 kubectl describe validatingwebhookconfiguration ingress-nginx 检查 caBundle 是否与控制面 CA 匹配。使用 kubectl create ingress test --rule="test.com/=:80" --dry-run=server 测试 Webhook 是否正常响应。
3.4 升级影响全景图
以下 SVG 图展示了集群升级过程中 Ingress 控制器各组件之间的依赖关系与风险传导路径。
3.5 升级前检查清单
为降低升级风险，建议在升级窗口前完成以下检查项：
| 检查项 |
验证方法 |
预期结果 |
| Ingress API 版本 |
kubectl get ingress -A -o jsonpath='{range .items[*]}{.apiVersion}{"\n"}{end}' | sort -u |
仅输出 networking.k8s.io/v1 |
| pathType 完整性 |
kubectl get ingress -A -o json | jq '.items[].spec.rules[].http.paths[].pathType' |
所有路径均有非空 pathType |
| Webhook CA 证书 |
kubectl get validatingwebhookconfiguration -o yaml | grep caBundle 对比控制面 CA |
caBundle 与控制面 CA 一致 |
| failurePolicy 显式设置 |
kubectl get validatingwebhookconfiguration -o json | jq '.items[].failurePolicy' |
明确为 Ignore 或 Fail，无空值 |
| 注解兼容性 |
对照 Ingress Controller 版本 Changelog 逐条检查 |
无已废弃或语法变更的注解 |
自动化检查脚本：将上述检查项封装为 pre-upgrade-check.sh，在升级前 CI/CD 流水线中自动执行。任何检查失败应阻断升级流程，直至问题修复。