升级NGINX Ingress控制器的兼容性说明
升级兼容性说明
CCE的NGINX Ingress控制器插件基于Ingress NGINX Controller的社区版本进行演进,社区新版本可能会引入新的功能、改进现有功能或者修复安全问题,因此在升级NGINX Ingress控制器插件过程中可能会存在兼容性差异,例如版本间的配置变更、Kubernetes API 版本废弃、默认行为调整、依赖组件兼容性等原因。关于NGINX Ingress控制器的变更记录,请参见版本记录。
以下是CCE识别的升级兼容性问题,请您在升级前进行关注:
NGINX原生有效性检查默认关闭
影响版本: 3.0.34 以下(不包括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)
为了提高安全性和配置稳定性,自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注解仍不可用。

不支持较低版本的TLS
影响版本:2.3.3以下(不包括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。