# 升级NGINX Ingress控制器的兼容性说明
#### 升级兼容性说明
CCE的NGINX Ingress控制器插件基于[Ingress NGINX Controller](https://github.com/kubernetes/ingress-nginx)的社区版本进行演进，社区新版本可能会引入新的功能、改进现有功能或者修复安全问题，因此在升级NGINX Ingress控制器插件过程中可能会存在兼容性差异，例如版本间的配置变更、Kubernetes API 版本废弃、默认行为调整、依赖组件兼容性等原因。关于NGINX Ingress控制器的变更记录，请参见[版本记录](https://support.huaweicloud.com/usermanual-cce/cce_10_0034.html#cce_10_0034__section183121449435)。
以下是CCE识别的升级兼容性问题，请您在升级前进行关注：
- [NGINX原生有效性检查默认关闭]
- [默认禁用snippet注解]
- [不支持较低版本的TLS]
- [NGINX原生的root及alias指令不再支持]
- [NGINX Ingress控制器支持优雅升级]
 
 #### NGINX原生有效性检查默认关闭
**影响版本：3.0.34及以上版本**
![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png)
升级后插件的默认行为将进行调整，请注意排查此变更是否会影响您的业务。
NGINX Ingress控制器插件3.0.34对应的社区版本为[v1.11.5](https://github.com/kubernetes/ingress-nginx/releases/tag/controller-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及以上** **版本**
![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png)
插件升级后，已存在的不兼容配置不会被刷新，但在新版本中默认不再生效，需要进行额外配置。
为了提高安全性和配置稳定性，自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"*
  ![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/note_3.0-zh-cn.png)
  在4.0.4及以上NGINX Ingress控制器插件版本需同时添加annotations-risk-level配置。
  这是因为在该版本中annotations-risk-level默认值降级为High，详情请参见[社区ChangeLog](https://github.com/kubernetes/ingress-nginx/releases/tag/controller-v1.12.0)。由于snippet注解为Critical级别，需要同时调整annotations-risk-level的参数值为Critical，否则snippet注解仍不可用。
  
图1添加NGINX配置参数启用snippet注解   
![](https://support.huaweicloud.com/usermanual-cce/zh-cn_image_0000002265467609.png "点击放大")
 #### 不支持较低版本的TLS
**影响版本：2.3.3及以上** **版本**
![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png)
升级后插件的默认行为将进行调整，请注意排查此变更是否会影响您的业务。
由于TLS v1.1及以下版本存在安全问题，NGINX Ingress控制器插件新版本不再默认支持TLS v1.1和TLS v1.0的加密方式。因此，在升级前，请确保您的业务不依赖v1.1及以下版本的TLS，并且在配置中将其移除。
如果您需要强制使用旧版本的TLS加密方式，请参见[NGINX Ingress控制器插件升级后无法使用TLS v1.0和v1.1](https://support.huaweicloud.com/cce_faq/cce_faq_00442.html)。
 #### NGINX原生的root及alias指令不再支持
**影响版本：2.1.1及以上** **版本**
![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png)
插件升级后，已存在的不兼容配置不会被刷新，但在新版本中不再生效。
为了防止用户错误配置导致敏感文件泄露或路径冲突，NGINX Ingress控制器插件2.1.1及以上版本不再支持*root* 、*alias* 指令。因此，在升级前，请确保您的Ingress不包含通过snippet方式配置的NGINX的原生*root* 或*alias*指令。
 #### NGINX Ingress控制器支持优雅升级
为确保升级过程的平滑过渡和服务稳定性，请注意以下插件版本的支持情况：
- **2.1.x版本**：2.1.33及以上版本的NGINX Ingress控制器插件支持优雅退出和无损升级。
- **2.2.x版本**：2.2.42及以上版本的NGINX Ingress控制器插件支持优雅退出和无损升级 。
- **2.4.6及以上版本**：均支持优雅退出和无损升级。
对于不在以上版本范围内的插件版本，在升级过程中可能会出现服务短暂不可用的情况。为确保服务的连续性和稳定性，请提前做好升级规划，并在**业务低峰期**进行升级。