Container Service for Kubernetes:Update the NGINX Ingress controller

When you update the Kubernetes version of a cluster, you may also need to update the NGINX Ingress controller because some APIs in the new Kubernetes version are deprecated. To ensure stability and use the latest features, we recommend that you update the NGINX Ingress controller to the latest version at the earliest opportunity. Unlike other components, the NGINX Ingress controller is updated in a progressive way. You need to pay close attention to the status of the component and your business to ensure that no business interruptions occur during and after the update.

Procedure

You must ensure the stability of the NGINX Ingress controller because it is a key component of the data plane.

Take note that there may be incompatibility issues if you update the NGINX Ingress controller to the latest version. This is because the latest version is a major update that includes significant changes to the NGINX Ingress controller, including substantial custom changes. In addition, an in-place update imposes higher potential risks because the incompatibility issues may not be disclosed immediately after the NGINX Ingress controller is updated.

To ensure that the NGINX Ingress controller can run as expected and avoid business interruptions, we recommend that you update the NGINX Ingress controller in a progressive way. This allows you to check the status of your workloads and roll back the update if exceptions occur.

Phase 1: Precheck

A precheck is automatically performed to check whether the NGINX Ingress controller meets the prerequisites for updates. If the NGINX Ingress controller does not meet the prerequisites or the status of the component is unhealthy, you must manually fix the issues before you can update the component.

Phase 2: Verification

A pod is created for the new NGINX Ingress controller version. The pod is used to verify the status and the Ingress rules of the new version. After the pod is created, a proportion of user traffic is distributed to the pod. You can analyze the container logs or use Simple Log Service or Managed Service for Prometheus to check whether the user traffic is processed as normal.

After a pod is created for the new version, the update process is paused. After you confirm that no exceptions occur to the component and workloads, you can manually resume the update process. If you identify an exception, you can roll back the update and delete the pod for the new version.

To roll back an update, modify the spec.minReadySeconds and spec.strategy parameters in the Deployment.

Phase 3: Release

A rolling update is performed during the release phase to replace the old version of the NGINX Ingress controller with the new version. After all pods of the NGINX Ingress controller are updated, the update process is paused to allow you to check the status of the component and workloads. After you confirm that no exceptions occur, you can complete the update. If you identify an exception, you can roll back the NGINX Ingress controller in all pods to the old version and then end the update.

Phase 4: Rollback (optional)

The update process is automatically paused during the verification and release phases to allow you to identify exceptions that occur during the update. If you identify an exception, you can roll back the NGINX Ingress controller to the old version.

Prerequisites

• Before you update the NGINX Ingress controller, make sure that you have approaches to monitor the business traffic and identify exceptions. You can use Simple Log Service or Managed Service for Prometheus to monitor the business traffic. For more information, see Analyze and monitor the access log of nginx-ingress and Use Managed Service for Prometheus to monitor an ACK cluster.

• Make sure that the status of the NGINX Ingress controller is healthy, all pods of the NGINX Ingress controller are ready, and no error logs are generated.

• Make sure that no auto scaling rules, such as HorizontalPodAutoscaler (HPA), are used. If auto scaling rules exist, delete the auto scaling rules, complete the update, and then recreate the rules.

• Make sure that the LoadBalancer Service runs as expected.

• Do not modify the NGINX Ingress controller or Ingress rules during the update.

Procedure

1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

2. On the Clusters page, click the name of the cluster that you want to manage and choose Operations > Add-ons in the left-side navigation pane.

3. On the Add-ons page, find the NGINX Ingress controller and click Upgrade in the lower-right part.

4. On the update page that appears, confirm the information and click Start to initiate an update.

   Note

   You can return to the update page anytime during the update process, or click Progress on the Add-ons page to view the update progress.

5. A precheck is performed in Phase 1. After the precheck is completed, the update automatically proceeds to Phase 2.

   If the NGINX Ingress controller fails to pass the precheck, you can click View Details below Precheck to go to the View Report page. Then, troubleshoot the issues displayed on this page. For more information, see Precheck. After you resolve the issues, click Retry to reinitiate an update.

6. After the verification phase ends, the update process is paused. You can check the status of the NGINX Ingress controller and workloads. For more information, see Verification.

   • For more information about how to handle the issue that pods fail to be created, see What do I do if pods fail to be created during the verification and release phases? You can also analyze the pod error log to identify the cause of failure to launch the pod. After you resolve the issue, click Retry to perform a verification again.

   • If exceptions occur to your workloads, click Roll Back to roll back the update. After the rollback is completed, the update process ends. You can click Upgrade on the Add-ons page to reinitiate an update.

7. After the verification is passed, click Continue to proceed to the release phase. After the rolling update during the release phase is completed, the update process is paused. You can check the status of the NGINX Ingress controller and workloads. If exceptions occur to your workloads, click Roll Back to roll back the update. After the rollback is completed, the update process ends. You can click Upgrade on the Add-ons page to reinitiate an update.

8. If no exceptions occur, click Continue to complete the update.

   Note

   Make sure that the update process requires no more than one week.

Precheck

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

ssl-protocols: TLSv1.2 TLSv1.3

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 old 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 old 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

Related topics

• For more information about the release notes of the NGINX Ingress controller, see Nginx Ingress Controller.

• If problems such as network failures occur during the use of the Nginx Ingress controller, refer to the related topics first. For more information, see Configure security group rules to enforce access control on ACK clusters and Nginx Ingress FAQ.