ingress-nginx 兼容性：K8s 版本适配与升级指南

ingress-nginx 兼容性：K8s 版本适配与升级指南

【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx

集群升完 1.33，ingress 集体 404 是怎么回事

上次我们把生产集群从 1.30 一把升到 1.33，控制器还停留在旧版本。结果升级完不到二十分钟，业务方就炸锅了：所有 ingress 全 404，控制器日志里刷着一屏 RBAC forbidden 报错。折腾半天才定位到根子——ingress-nginx 的版本适配矩阵没对上。下面这套流程，就是我们从那次事故里总结出来的：先对版本、再走升级、最后验证，跟着做基本不会翻车。

先看这张表，确定你的版本组合

仓库 README 里有一张 Supported Versions 表，列中的版本都跑过完整的 E2E 测试才算"支持"。挑三行最常用的：

用法很直白：先kubectl get nodes确认你的 K8s 版本，再找区间能覆盖它的那一行，控制器、Nginx、Helm chart 版本一并定了。比如 1.33 的集群，就得看 v1.13.3 及以上；v1.12 那行的区间最高只到 1.32，别拿来硬扛 1.33。

三条升级路径，各自的坑不一样

无 Helm 时只改镜像如何完成升级

yaml 裸装的场景，升级就是把 Deployment 里的镜像 tag 换掉，最短路径一条命令：

kubectl set image deployment/ingress-nginx-controller \ controller=registry.k8s.io/ingress-nginx/controller:v1.0.5@sha256:55a1fcda5b7657c372515fe402c3e39ad93aa59f6e4378e82acd99912fe6028d \ -n ingress-nginx

⚠️ 换 tag 前务必确认自定义模板和 ConfigMap 对新版本仍兼容，官方步骤详见 upgrade 文档。

Helm reuse-values 升级老 release

用 Helm 装的，升级时带上--reuse-values即可保留全部既有配置：

helm upgrade --reuse-values ingress-nginx ingress-nginx/ingress-nginx

⚠️ 跨大版本升级时部分 values 项已重命名，升完用helm get values对新一次 chart 默认值，别只盯着版本号。

从 stable/nginx-ingress 迁移过来怎么办

老 chart 已停止维护，两条路二选一：

• 非关键服务：直接卸载老 release，重新安装 ingress-nginx/ingress-nginx chart，五分钟搞定。
• 生产关键服务：先装第二套控制器，DNS 流量逐步切过去，两边同时观察日志，老控制器流量排空后再卸载。

⚠️ 两套 chart 的资源名和标签体系有变化，动手前先翻一遍 chart 的迁移说明。

IngressClass 缺失和 RBAC 报错的 30 秒速诊

症状：升级 K8s 后部分 ingress 404

• 现象：路由规则没删没改，访问却全 404。
• 验证：kubectl get ingressclass，再看各 ingress 是否设置了ingressClassName字段。
• 修复：补建 IngressClass 资源，字段名与 IngressClass 的 name 保持一致；高版本 K8s 下路径匹配语义也变了，改完用 curl 逐条验证。

症状：控制器日志刷 forbidden，配置不再生效

• 现象：新 ingress 建了，但 Nginx 配置里没有对应规则。
• 验证：kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx --tail=50，找cannot list resources "ingresses" ... forbidden这类报错。
• 修复：按当前版本重新应用 ClusterRole 与 ClusterRoleBinding，权限补齐后观察日志中 reload 是否恢复正常。

升级之后，盯这三个指标

rollout 完成不等于一切正常，Prometheus 里有三个指标值得先扫一眼：

• nginx_ingress_controller_config_last_reload_successful：应为 1，出现 0 说明配置重载失败过
• nginx_ingress_controller_response_duration_seconds：延迟分位是否出现尖刺
• nginx_ingress_controller_nginx_process_requests_total：请求总量是否在持续上涨

仓库的 deploy/prometheus 和 deploy/grafana 目录自带现成部署清单与看板模板，直接 apply 就能用。

延伸阅读出口

• changelog/：每个控制器版本的详细变更
• docs/deploy/：baremetal、各云厂商环境与升级说明
• docs/developer-guide/：控制器代码结构与二次开发
• docs/faq.md：版本适配相关的常见疑问

把升级当成一次版本适配而不是简单换镜像：升前对表、升中留回滚点、升后盯指标。✅ 下次集群再往前走一个大版本，你就有现成的清单可以照着跑了。

【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx