Upgrade the NGINX Ingress controller

Default security configuration changes

Affected versions: Versions earlier than v1.12.6-release.1.

Starting in v1.12.6-release.1, ingress-nginx tightened default security settings, including:

• The default level of annotations-risk-level is lowered from Critical to High. This change makes existing Ingress resources with Critical level annotations, such as snippet-related annotations, unavailable.

• allow-cross-namespace-resources is changed from true to false. This configuration disables cross-namespace referencing of resources like ConfigMap and Secrets by default.

• strict-validate-path-type is changed from false to true. This configuration enables strict path validation by default. This means that for paths of type Exact and Prefix, only paths that start with / and contain only letters, numbers, -, _, ., and additional / are allowed.

If you use features blocked by these security settings, manually enable them in ConfigMap kube-system/nginx-configuration after assessing security risks.

Native NGINX validation is disabled by default

Affected versions: Versions earlier than v1.11.5-aliyun.1.

To fix CVE-2025-1974, NGINX Ingress controller disables native NGINX validation (the nginx -t logic) by default starting in v1.11.5-aliyun.1. The validation webhook remains enabled but does not validate snippet-based rules; only non-snippet annotations are validated by default. For snippet rules, check NGINX runtime error logs. See the Vulnerability CVE-2023-1097, CVE-2023-1098, CVE-2023-1974, CVE-2023-24513, CVE-2023-24514 Announcement.

If you use snippet annotations, check NGINX Ingress Pod logs for Error-related entries each time you change the corresponding Ingress rules:

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

To re-enable native NGINX validation, add enable-nginx-native-validation: "true" to ConfigMap kube-system/nginx-configuration after fully assessing the risks.

Snippet annotations are disabled by default

Affected versions: Versions earlier than v1.9.3-aliyun.1.

For security reasons, NGINX Ingress controller disables all snippet annotations by default starting in v1.9.3-aliyun.1, including:

• 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, prefer alternative annotations or configuration options.

To use snippet annotations, add allow-snippet-annotations: "true" to ConfigMap kube-system/nginx-configuration after fully assessing the risks.

Legacy TLS versions are not supported

Affected versions: Versions earlier than v1.7.0-aliyun.1.

Because of security issues in TLS 1.1 and earlier, new NGINX Ingress versions no longer support TLS v1.1 and TLS v1.0 by default. Before upgrading, verify your services do not rely on TLS v1.1 or earlier and remove them from your configuration. ConfigMap changes take effect immediately.

For example, if the ConfigMap (kube-system/nginx-configuration) for the NGINX Ingress controller is configured as follows:

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

After you confirm your services are unaffected, remove this line to use defaults, or remove SSLv3, SSLv2, TLSv1, and TLSv1.1 and change the line to:

ssl-protocols: TLSv1.2 TLSv1.3

To enforce older TLS encryption methods, see Which SSL/TLS versions are supported by Ingresses?.

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

Affected versions: Versions earlier than 0.22.0.

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

• rewrite-target behavior before 0.22.0 is incompatible with current versions. Before upgrading, use the configuration-snippet annotation instead of rewrite-target.

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, where /something is the path in the path field (without the trailing slash).
    # If the Ingress contains multiple paths, multiple rewrite directives are needed.
    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 the path consistent with the old Ingress resource.
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      - path: /something123/ # Keep the path consistent with the old 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 capture group.
      - path: /something(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      # Use a capture 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 component and service status

Besides your own monitoring tools, ACK provides Simple Log Service logs, Managed Service for Prometheus dashboards, and native container logs to monitor NGINX Ingress. To enable them, see Collect and analyze NGINX Ingress access logs and Connect to and configure Managed Service for Prometheus.

Can I upgrade the NGINX Ingress controller to a specific version? Can I roll back to a previous version after a successful upgrade?

NGINX Ingress controller does not support upgrading to a specific version. Upgrades proceed in phases to the latest version. You cannot roll back after a successful upgrade.

What do I do if a Pod fails to be created during the verification or release phase?

What do I do if the Deployment template check fails?

If the Deployment template fails precheck, click the link next to Cause of Error to open the component differences page and view failed fields.

1. On the NGINX Ingress Controller Upgrade page, under Precheck, click View Details.

2. On the Check Report page, in the Cluster Component Check Results section, click the red box at ① to view the check results. Then, on the Check Result page, click Deployment Template, and finally click the link next to Cause of Error at ②.

   

3. Go to the Component Differences page to view the fields that failed the check.

   The component differences page compares the standard template for this version (left) with the current cluster template (right), highlighting compatible and incompatible differences. It also shows whether the cluster component passed the difference check and lists incompatible field paths.

   In the example below, the differing field is .spec.template.spec.containers.(nginx-ingress-controller).args (parentheses show the array element name). The comparison shows --v=2 in args changed to --v=3, which must be corrected before upgrade.

   

4. Modify the differing field.

   Choose Workloads > Deployments, find the NGINX Ingress controller component, and choose More > View YAML. On the Edit YAML page, change --v=3 to --v=2 in the args field.

5. After you modify the field, refresh the component differences page. When the page shows The component can pass the difference check, the Deployment template check will pass.

   Note

   Modifying the cluster Deployment restarts NGINX Ingress Pods. Perform this during off-peak hours.