Upgrade the NGINX Ingress Controller

Maximum number of request headers

Affected versions: earlier than v1.14.5-release.4 (excluding v1.14.5-release.4).

To fix CVE-2026-49975, the max_headers directive was added in v1.14.5-release.4. By default, it limits a single request to no more than 1,000 HTTP headers. Requests that exceed the limit return 400 and the connection is closed. Before you upgrade, make sure that a single request in your workload carries no more than 950 HTTP headers. This leaves capacity for HTTP headers inserted by other gateways along the path.

real_ip_header behavior changes

Affected versions: earlier than v1.13.8-release.1 (excluding v1.13.8-release.1).

v1.13.x changes how the actual client IP is obtained when both use-proxy-protocol and use-forwarded-headers are enabled. The behavior applies when you use PROXY protocol to obtain the actual client IP, use-forwarded-headers is also enabled, and proxy-real-ip-cidr retains its default value 0.0.0.0/0. All PROXY protocol addresses are then treated as trusted proxies. A client-provided X-Forwarded-For may then be trusted, which allows the client IP to be spoofed.

During the upgrade, carefully verify the nginx-ingress-controller configuration. To keep both use-proxy-protocol: "true" and use-forwarded-headers: "true", narrow proxy-real-ip-cidr from the default 0.0.0.0/0 to the CIDRs of actual trusted TCP peers and front-end L7 proxy egresses. Examples include the Local IP CIDR of a Network Load Balancer (NLB) or Classic Load Balancer (CLB) instance. Traffic that directly reaches the TCP load balancer then continues to use the PROXY protocol address, and only forwarded-for chains from trusted front-end proxies are parsed.

Default security configuration adjustments

Affected versions: earlier than v1.12.6-release.1 (excluding v1.12.6-release.1).

To improve the security of ingress-nginx, the default values of some security configurations were changed in v1.12.6-release.1. The affected configurations include:

• annotations-risk-level has a default level that is lowered from Critical to High. This change makes existing Critical-level Annotations on Ingress resources in the cluster unavailable, such as Annotations related to snippet.

• allow-cross-namespace-resources is changed from true to false. By default, this configuration prohibits cross-namespace references to resources such as ConfigMap and Secrets.

• strict-validate-path-type is changed from false to true. This configuration enables strict path address validation by default. This means that paths of the Exact and Prefix types must begin with / and can contain only letters, digits, -, _, ., and additional / characters.

If you have used or want to use features that these security configurations prohibit, fully assess the security risk. Then manually enable the features by adding configurations to the ConfigMap kube-system/nginx-configuration.

Native NGINX validation is disabled by default

Affected versions: earlier than v1.11.5-aliyun.1 (excluding v1.11.5-aliyun.1).

To fix CVE-2025-1974, NGINX Ingress Controller disables native NGINX validation (the nginx -t command logic) by default starting with v1.11.5-aliyun.1. Although the NGINX Ingress Controller add-on still enables the validation webhook, the validation webhook does not validate rules that use snippet configurations. By default, it validates only standard non-snippet Annotations. For rules configured with snippets, you can check configurations only through error logs generated at NGINX runtime. For more information about the vulnerability, see Security Advisory: NGINX Ingress Controller Vulnerabilities (CVE-2025-1974 and Related CVEs).

If you enable the snippet Annotation feature, check the NGINX Ingress Controller Pod logs for Error-related logs each time you change the corresponding Ingress rules:

kubectl logs -f <Nginx-ingress-pod-name> -n kube-system |grep Error

If you still need native NGINX validation, fully assess the risk and then manually enable it in the ConfigMap kube-system/nginx-configuration by adding enable-nginx-native-validation: "true".

Snippet Annotations are disabled by default

Affected versions: earlier than v1.9.3-aliyun.1 (excluding v1.9.3-aliyun.1).

For security reasons, NGINX Ingress Controller disables all snippet Annotations by default starting with v1.9.3-aliyun.1. These may 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

Because of security and stability risks, prioritize using related Annotations or configuration items to implement the required features.

If you still need the snippet Annotation feature, fully assess the risk and then manually enable the Annotation feature in the ConfigMap kube-system/nginx-configuration by adding allow-snippet-annotations: "true".

Earlier versions of TLS are not supported

Affected versions: earlier than v1.7.0-aliyun.1 (excluding v1.7.0-aliyun.1).

Because TLS 1.1 and earlier versions have security issues, new NGINX Ingress Controller versions no longer support the TLS 1.1 and TLS 1.0 encryption methods by default. Therefore, before you upgrade, make sure that your workload does not depend on TLS 1.1 or earlier, and remove these versions from the configuration. ConfigMap changes take effect immediately.

For example, if the ConfigMap (kube-system/nginx-configuration) of the NGINX Ingress Controller add-on is configured as follows:

ssl-protocols: SSLv3 SSLv2 TLSv1 TLSv1.1 TLSv1.2 TLSv1.3

After you confirm that your workload is unaffected, remove this line and use the default setting. Alternatively, remove the four entries SSLv3, SSLv2, TLSv1, and TLSv1.1, and change the line to:

ssl-protocols: TLSv1.2 TLSv1.3

If you need to force the use of earlier TLS encryption methods, see Which TLS versions are supported? for configuration instructions.

Incompatible usage of nginx.ingress.kubernetes.io/rewrite-target

Affected versions: earlier than 0.22.0 (excluding 0.22.0).

• Version 0.22.0 changed the usage of the nginx.ingress.kubernetes.io/rewrite-target Annotation. In 0.22.0 and later, you must explicitly specify the use of capturing groups when you use rewrite-target.

• The rewrite-target feature in versions earlier than 0.22.0 is incompatible with the rewrite-target feature in the latest version. Before the add-on upgrade, you can use configuration-snippet instead of the rewrite-target Annotation.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      - path: /something/
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      - path: /something123/
        pathType: Prefix
        backend:
          service:
            name: http-svc-1
            port:
              number: 80

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # Use the rewrite directive. /something is the path in the path field, without the trailing slash.
    # Ingress contains multiple paths, so add multiple rewrite directives.
    nginx.ingress.kubernetes.io/configuration-snippet: |
      rewrite "(?i)/something(/|$)(.*)" /$2 break;
      rewrite "(?i)/something123(/|$)(.*)" /$2 break;
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      - path: /something/ # Keep this path consistent with the path in the earlier Ingress resource.
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      - path: /something123/ # Keep this path consistent with the path in the earlier Ingress resource.
        pathType: Prefix
        backend:
          service:
            name: http-svc-1
            port:
              number: 80

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # Reference the matched content.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      # Use a capturing group.
      - path: /something(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      # Use a capturing group.
      - path: /something123(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: http-svc-1
            port:
              number: 80

  apiVersion: extensions/v1beta1
  kind: Ingress
  metadata:
    labels:
      ingress-controller: nginx
    name: test
    namespace: default
  spec:
    ingressClassName: nginx
    rules:
    - host: www.example.com
      http:
        paths:
        - backend:
            service:
              name: api-resources-svc
              port:
                number: 8080
          path: /api/resource

data:
  use-gzip: true

Verify add-on and workload status

In addition to your own workload monitoring capabilities, ACK provides SLS logs, Managed Service for Prometheus dashboards, and container logs to monitor the running status of NGINX Ingress Controller. To enable these services, see Analyze and monitor the access log of nginx-ingress-controller and Configure Managed Service for Prometheus.

Can NGINX Ingress Controller be upgraded to a specified version? After the upgrade succeeds, can it be rolled back to an earlier version?

NGINX Ingress Controller cannot be upgraded to a specified version. The add-on is upgraded in phases until it reaches the latest version. After the upgrade succeeds, it cannot be rolled back.

What do I do if Pod scaling fails during the verification or release phase?

What do I do if the Deployment template precheck fails?

If your Deployment template fails the precheck, click the link to the right of Cause of Error to open the add-on differences page and view the fields that failed the check.

1. On the NGINX Ingress Controller add-on upgrade page, below Precheck, click View Details.

2. On the Check Report page, in the Cluster Add-on Check Results section, view the check results. On the Check Result page, click Deployment Template, and then click the link to the right of Cause of Error.

3. Open the Add-on Differences page to view the fields that failed the check.

   The Add-on Differences page compares the standard template for that add-on version (left) with the add-on template in your cluster (right). The page marks all differences between the two, including compatible and incompatible fields. Below the comparison, it shows whether the add-on in your cluster passes the difference check and lists the specific paths of the incompatible fields.

4. Modify the fields that differ.

   Choose Workloads > Deployments, find the NGINX Ingress Controller add-on, and click More > View YAML. On the Edit YAML page, in the args field, change --v=3 to --v=2.

5. After you modify the differing fields, you can reopen or refresh the Add-on Differences page to view the latest comparison. When the bottom of the page shows Add-on can pass the difference check, the Deployment template precheck passes.

   Note

   NGINX Ingress Controller Pods restart while you modify the Deployment in the cluster, so perform this operation during off-peak hours.