文档首页/ 云容器引擎 CCE/ 用户指南/ 网络/ 路由(Ingress)/ Nginx Ingress管理/ 升级NGINX Ingress控制器的兼容性说明
更新时间:2025-08-27 GMT+08:00

升级NGINX Ingress控制器的兼容性说明

升级兼容性说明

CCE的NGINX Ingress控制器插件基于Ingress NGINX Controller的社区版本进行演进,社区新版本可能会引入新的功能、改进现有功能或者修复安全问题,因此在升级NGINX Ingress控制器插件过程中可能会存在兼容性差异,例如版本间的配置变更、Kubernetes API 版本废弃、默认行为调整、依赖组件兼容性等原因。关于NGINX Ingress控制器的变更记录,请参见版本记录

以下是CCE识别的升级兼容性问题,请您在升级前进行关注:

NGINX原生有效性检查默认关闭

影响版本:3.0.34及以上版本

NGINX Ingress控制器插件3.0.34对应的社区版本为v1.11.5,该版本中修复了安全漏洞 CVE-2025-1974,并移除了Webhook中的nginx -t命令(配置语法检查功能)。当前版本仍保留对Ingress资源格式规范的校验,但若您启用了snippet注解且配置中存在语法错误,非法配置可能直接注入nginx.conf文件,由于缺少预检机制,此类错误可能引发reload nginx配置失败风险。因此在您启用snippet注解功能时,建议您在每次变更对应Ingress规则的同时,检查NGINX Ingress控制器Pod日志,确认是否有Error相关日志。相关命令:

kubectl logs -f {nginx-ingress-controller-pod-name} -n kube-system | grep Error

默认禁用snippet注解

影响版本:2.4.6及以上版本

为了提高安全性和配置稳定性,自2.4.6版本起,NGINX Ingress控制器插件将默认禁用所有snippet注解,可能包括:

  • nginx.ingress.kubernetes.io/configuration-snippet
  • nginx.ingress.kubernetes.io/server-snippet
  • nginx.ingress.kubernetes.io/stream-snippet
  • nginx.ingress.kubernetes.io/auth-snippet
  • nginx.ingress.kubernetes.io/modsecurity-snippet

如您仍需要使用snippet注解能力,请在充分评估风险后,可以在插件配置中的“nginx配置参数 > YAML配置”中添加以下配置,手动开启snippet注解的功能。

  • "allow-snippet-annotations": "true"
  • "annotations-risk-level": "Critical"

    在4.0.4及以上NGINX Ingress控制器插件版本需同时添加annotations-risk-level配置。

    这是因为在该版本中annotations-risk-level默认值降级为High,详情请参见社区ChangeLog。由于snippet注解为Critical级别,需要同时调整annotations-risk-level的参数值为Critical,否则snippet注解仍不可用。

图1 添加NGINX配置参数启用snippet注解

不支持较低版本的TLS

影响版本:2.3.3及以上版本

由于TLS v1.1及以下版本存在安全问题,NGINX Ingress控制器插件新版本不再默认支持TLS v1.1和TLS v1.0的加密方式。因此,在升级前,请确保您的业务不依赖v1.1及以下版本的TLS,并且在配置中将其移除。

如果您需要强制使用旧版本的TLS加密方式,请参见NGINX Ingress控制器插件升级后无法使用TLS v1.0和v1.1

NGINX原生的root及alias指令不再支持

影响版本:2.1.1及以上版本

为了防止用户错误配置导致敏感文件泄露或路径冲突,NGINX Ingress控制器插件2.1.1及以上版本不再支持rootalias指令。因此,在升级前,请确保您的Ingress不包含通过snippet方式配置的NGINX的原生rootalias指令。

NGINX Ingress控制器支持优雅升级

为确保升级过程的平滑过渡和服务稳定性,请注意以下插件版本的支持情况:

  • 2.1.x版本:2.1.33及以上版本的NGINX Ingress控制器插件支持优雅退出和无损升级。
  • 2.2.x版本:2.2.42及以上版本的NGINX Ingress控制器插件支持优雅退出和无损升级 。
  • 2.4.6及以上版本:均支持优雅退出和无损升级。

对于不在以上版本范围内的插件版本,在升级过程中可能会出现服务短暂不可用的情况。为确保服务的连续性和稳定性,请提前做好升级规划,并在业务低峰期进行升级。