升级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注解仍不可用。
不支持较低版本的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。
