Container Service for Kubernetes:Update the NGINX Ingress controller

Precheck table

Incompatibility issues

During development and maintenance, new versions of the NGINX Ingress controller may introduce new features, enhance existing features, or fix security issues. However, these updates may also lead to compatibility issues with previous versions due to changes in internal architecture or variations in dependency libraries. For more information about the release notes of the NGINX Ingress controller, see NGINX Ingress controller.

snippet annotations are disallowed by default

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

For security purposes, NGINX Ingress controller v1.9.3-aliyun.1 and later versions disallow snippet annotations.

• 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

To ensure security and stability, if you want to use specific features, we recommend that you use the corresponding annotations or settings instead of snippet annotations.

If you want to use snippet annotations, assess the risks and add allow-snippet-annotations: "true" to the kube-system/nginx-configuration ConfigMap to allow snippet annotations.

Incompatibility with earlier TLS versions

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

TLS 1.1 and earlier versions have security issues. The NGINX Ingress controller no longer supports the following TLS versions: TLS 1.1 and TLS 1.0. Before you update the NGINX Ingress controller, make sure that your service is not reliant on TLS 1.1 or earlier versions, and TLS 1.1 and earlier versions are removed from the TLS settings of your service. Changes to the ConfigMap take effect immediately.

The following content shows the sample TLS settings in the nginx-configuration ConfigMap of the NGINX Ingress controller in the kube-system namespace:

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

Make sure that your service is not reliant on TLS 1.1 or earlier versions. You can delete the command line to use the default TLS settings. You can also remove TLS 1.1, TLS 1.0, SSL 3.0, and SSL 2.0 from the TLS settings. Example:

ssl-protocols: TLSv1.2 TLSv1.3

If you want to use earlier TLS versions, complete the configurations by referring to the required documents. For more information, see the Which SSL or TLS protocol versions are supported by Ingresses? section of the "Nginx Ingress FAQ" topic.

Incompatibility issue related to the nginx.ingress.kubernetes.io/rewrite-target annotation

Affected versions: versions earlier than 0.22.0.

• NGINX Ingress controller 0.22.0 adds a change to the way in which the nginx.ingress.kubernetes.io/rewrite-target annotation is used. In NGINX Ingress controller 0.22.0 and later versions, you need to explicitly specify a capture group if you want to use the rewrite-target annotation.

• The rewrite-target annotation in NGINX Ingress controller versions earlier than 0.22.0 is incompatible with the rewrite-target annotation in the later versions. Before you update the NGINX Ingress controller, replace rewrite-target with configuration-snippet.

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 annotation. /something indicates the path, excluding the forward slash (/) at the end. 
    # If the Ingress includes multiple paths, add the same number of rewrite annotations. 
    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 value the same as the path of the Ingress in the earlier version. 
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      - path: /something123/ # Keep the value the same as the path of the Ingress in the earlier version. 
        pathType: Prefix
        backend:
          service:
            name: http-svc-1
            port:
              number: 80

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # Reference the matching 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

Verification

Verify the status of the NGINX Ingress controller and workloads

In addition to the monitoring capability of ACK, ACK also allows you to use Simple Log Service, Managed Service for Prometheus dashboards, and container logs to monitor the status of the NGINX Ingress controller. To activate the preceding services, see Analyze and monitor the access log of nginx-ingress-controller and Managed Service for Prometheus.

Update notes

When you update the NGINX Ingress controller, take note of changes in prefix matching. Make sure that the path configuration aligns with the request URL. Otherwise, the status code 404 will be returned for requests.

Known issues

Differences in prefix matching may exist across different versions of the NGINX Ingress controller, potentially leading to service access issues.

• In versions earlier than 0.44, the prefix matching rules are loose. For example, the prefix /aaa/bbb can match /aaa/bbbbb in a request URL.

• After the update, the prefix matching rules become stricter and match only exact request URLs. In the preceding example, /aaa/bbbbb in the request URL is not matched. Instead, the status code 404 is returned.

Scope of impacts

NGINX Ingress controller earlier than v0.44 are affected. For more information about release notes, see NGINX Ingress controller. For related pull request information, see kubernetes/ingress-nginx #6443.

Sample configuration

You can use the following YAML template to compare the NGINX configurations rendered by NGINX Ingress controllers of different versions, such as 0.22.0.5-552e0db-aliyun (earlier version) and 1.2.1-aliyun.1+ (later version).

  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

• In earlier versions

  In version such as 0.22.0.5-552e0db-aliyun, the NGINX configuration is:

  Location /api/resource   # The path does not end with a forward slash (/). 

  In the preceding configuration, the path /api/resource allows access from http://www.example.com/api/resources in earlier versions of NGINX.

  Note

  The actual request path is resources instead of resource.

• In later versions

  If the NGINX Ingress controller is updated to a later version such as 1.2.1-aliyun.1+, the NGINX configuration is:

  Location /api/resource/  # The path ends with a forward slash (/).
  {
  }
  ...
  Location = /api/resource  # Another location is added for precise matching.
  {
  }

  HTTP status code 404 is returned if you try to access http://www.example.com/api/resources.

FAQ

Can I update the NGINX Ingress controller to a specific version? After a successful update, can I roll back to a previous version?

You cannot update the NGINX Ingress controller to a specific version. The NGINX Ingress controller is updated progressively and can only be updated to the latest version. Once the update is complete, it cannot be rolled back.

What do I do if pods fail to be created during the verification and release phases?

What do I do if the Deployment template fails to pass the check?

If the Deployment template fails to pass the check, click the hyperlink to the right of Cause to go to the Component Comparison page. You can view the component parameters that failed to pass the check.

1. On the NGINX Ingress Controller Update page, click View Details below Precheck.

2. In the Cluster Components Result section of the Report page, click the result in the red box marked with ①. On the Result tab, click Deployment Template. Then, click the hyperlink to the right of Cause marked with ②.

   

3. On the Component Comparison page, you can view the component parameters that failed to pass the check.

   On the Component Comparison page, the standard component template is displayed on the left and the current component template is displayed on the right. The Component Comparison page displays the differences between the templates, including compatible and incompatible parameters, and lists the differences in the lower part of the page. The Component Comparison page also shows whether the component passes the check and displays the parameters that cause the differences.

   In the following figure, a difference is found between the templates and the parameter that causes the difference is .spec.template.spec.containers.(nginx-ingress-controller).args. nginx-ingress-controller is the name of the container to which the parameter belongs. The comparison result shows that the --v=2 is specified in the args parameter in the standard template, whereas --v=3 is specified in the args parameter in the current template. You must modify the args parameter before you update the component.

   

4. Modify the parameters that cause the differences.

   In the left-side navigation pane, choose Workloads > Deployments. On the Deployments page, find the NGINX Ingress controller and choose More > View in YAML in the Actions column. In the Edit YAML dialog box, change the value of the args parameter from --v=3 to --v=2.

5. After you modify the args parameter, you can refresh the Component Comparison page to check whether the difference is fixed. If The component passes the comparison check. is displayed in the lower part of the page, the Deployment template passes the check.

   Note

   The system restarts the pods of the NGINX Ingress controller to apply the modifications to the Deployment. We recommend that you perform the related operations during off-peak hours.