Help Center/ Cloud Container Engine/ User Guide/ Networking/ Ingresses/ Nginx Ingresses/ NGINX Ingress Controller Upgrade Compatibility
Updated on 2025-08-19 GMT+08:00
View PDF
Share

NGINX Ingress Controller Upgrade Compatibility

Compatibility

CCE NGINX Ingress Controller is based on the community version of Ingress NGINX Controller. Upgrades to the community version may introduce new features, optimize existing ones, or address security issues. As a result, compatibility differences may occur after you upgrade CCE NGINX Ingress Controller. These differences can include configuration changes between versions, deprecated Kubernetes APIs, default actions, and compatibility with dependency components. For details about NGINX Ingress Controller changes, see Release History.

Before upgrading the NGINX Ingress Controller, pay attention to the following compatibility issues identified by CCE:

Native Nginx Validity Check Disabled by Default

Affected versions: earlier than 3.0.34

The NGINX Ingress Controller v3.0.34 corresponds to community version v1.11.5. In this community version, the security vulnerability CVE-2025-1974 has been fixed, and nginx -t (syntax check) has been removed from webhooks. In the community version v1.11.5, the format of ingress resources is still verified using admission webhooks. However, if you enable snippet annotations and the configuration contains syntax errors, invalid configurations may be directly injected into the nginx.conf file. Since there is no pre-check to validate the injected configuration, such errors may cause the Nginx configuration reload to fail. Therefore, if you enable snippet annotations, check NGINX Ingress Controller's pod logs for errors each time you modify the ingress rules. To do so, run the following command:

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

Snippet Annotations Disabled by Default

Affected versions: earlier than 2.4.6

Starting from version 2.4.6, the NGINX Ingress Controller has disabled snippet annotations by default to improve security and configuration stability. The snippet annotations include:

  • 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

If you still need to use snippet annotations, fully evaluate the associated risks and manually enable the annotation function. To do so, go to Settings, click YAML under Nginx Parameters and add the following annotations:

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

    In NGINX Ingress Controller 4.0.4 and later versions, you need to add annotations-risk-level.

    This is because the default value of annotations-risk-level is downgraded to High in these versions. For details, see Changelog. Snippet annotations are at the critical level. So, you need to change the value of annotations-risk-level to Critical, or snippet annotations are still unavailable.

Figure 1 Adding a parameter to enable snippet annotations

Earlier TLS Versions Not Supported

Affected versions: earlier than 2.3.3

TLS v1.1 and earlier versions have security issues. The NGINX Ingress Controller of v2.3.3 and later versions does not support TLS v1.1 and TLS v1.0 by default. Therefore, before upgrading the NGINX Ingress Controller, ensure your services do not rely on TLS v1.1 or earlier versions. Remove these versions from your configuration to maintain compatibility and security.

If you need to forcibly use TLS v1.1 or earlier versions, see Why TLS v1.0 or v1.1 Cannot Be Used After the NGINX Ingress Controller Add-on Is Upgraded?

Nginx Native root and alias Directives Not Supported

Affected versions: earlier than 2.1.1

To prevent sensitive file leakage or path conflicts caused by incorrect configurations, the NGINX Ingress Controller of v2.1.1 and later versions has removed support for the root and alias directives. Therefore, before upgrading the NGINX Ingress Controller, ensure your ingresses do not contain the Nginx native root or alias directives configured using snippets.

Graceful Upgrades Supported by NGINX Ingress Controller

To ensure a smooth upgrade and maintain service stability, pay attention to the following add-on versions:

  • 2.1.x: The NGINX Ingress Controller of v2.1.33 and later versions supports graceful shutdown and hitless upgrade.
  • 2.2.x: The NGINX Ingress Controller of v2.2.42 and later versions supports graceful shutdown and hitless upgrade.
  • 2.4.6 or later: The NGINX Ingress Controller supports graceful shutdown and hitless upgrade.

For versions beyond the preceding ranges, services may experience temporary downtime during upgrades. To ensure service continuity and stability, plan and conduct an upgrade during off-peak hours.

Parent Topic: Nginx Ingresses