Upgrading Nginx Ingress Controller

You must upgrade the NGINX Ingress Controller (nginx-ingress-controller) based on your Kubernetes and OpenShift versions. 

The certified versions of NGINX Ingress Controller with the Kubernetes and OpenShift orchestration platform are as follows:

Nginx Ingress Controller version

Supported Kubernetes version

OpenShift version

1.7.0

1.24 or 1.25

4.11 or 4.12

1.8.1

1.26

4.13

1.9.3 

1.27

4.14

1.9.5

1.28

4.14

1.9.6

1.29

NA

Important

You might experience downtime while upgrading the NGINX Ingress Controller.

Related topics

Preparing-for-upgrade

Best practice
Run the following command to check the version of nginx-ingress-controller:

kubectl -n ingress-nginx get ds -o yaml | grep -i image:

Sample output:

image: k8s.gcr.io/ingress-nginx/controller:v1.2.0@sha256:d8196e3bc1e72547c5dec66d6556c0ff92a23f6d0919b206be170bc90d5f9185

To upgrade the NGINX Ingress Controller

  1. To get the ingress-class used for the NGINX Ingress Controller, run the following command:

    kubectl get ds -n ingress-nginx -o yaml | grep -i "\-\-ingress-class"

    Look for --ingress-class in the command output.
    Example: --ingress-class=nginx

  2. Based on the version of your Kubernetes or OpenShift, run one of the following commands to get the deploy.yaml file for the NGINX Ingress Controller:

    • To get deploy.yaml file for Nginx Ingress Controller version 1.7.0:

      wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.7.0/deploy/static/provider/cloud/deploy.yaml

    • To get deploy.yaml file for Nginx Ingress Controller version 1.8.1:

      wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml

    • To get deploy.yaml file for Nginx Ingress Controller version 1.9.3:

      wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.3/deploy/static/provider/cloud/deploy.yaml

      Important

      If you are not able to download Nginx Ingress Controller version 1.9.3, use version 1.9.5 or 1.9.6.

    • To get deploy.yaml file for Nginx Ingress Controller version 1.9.5:

      wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.5/deploy/static/provider/cloud/deploy.yaml

    • To get deploy.yaml file for Nginx Ingress Controller version 1.9.6:

      wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.6/deploy/static/provider/cloud/deploy.yaml
  3. Make sure that the ingress class (which you verified in Step 1) is mentioned in the deploy.yaml file.

  4. To delete the jobs (ingress-nginx-admission-create and ingress-nginx-admission-patch), run the following command:

    kubectl delete job ingress-nginx-admission-create ingress-nginx-admission-patch -n ingress-nginx --ignore-not-found=true

    Important

    Ignore the errors or warnings if the ingress-nginx-admission-create and ingress-nginx-admission-patch jobs are absent. 

  5. Make the following changes in the deploy.yaml file:

    1. Change the kind field of the ingress-nginx-controller from Deployment to DaemonSet

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        labels:
          app.kubernetes.io/component: controller
          app.kubernetes.io/instance: ingress-nginx
          app.kubernetes.io/name: ingress-nginx
          app.kubernetes.io/part-of: ingress-nginx
          app.kubernetes.io/version: <version of the deploy.yaml>
        name: ingress-nginx-controller
       namespace: ingress-nginx


    2. (If upgrading to Ingress Controller 1.9.3 or later) Under Kind: Daemonset, change the spec.strategy field to spec.updateStrategy.

      spec:
        minReadySeconds: 0
        revisionHistoryLimit: 10
        selector:
          matchLabels:
            app.kubernetes.io/component: controller
            app.kubernetes.io/instance: ingress-nginx
            app.kubernetes.io/name: ingress-nginx
        updateStrategy:
          rollingUpdate:
            maxUnavailable: 1
          type: RollingUpdate


    3. In the args section, set the default certificate to my-tls-secret:

      spec:
            containers:
           - args:
             - /nginx-ingress-controller
             - --publish-service=$(POD_NAMESPACE)/ingress-nginx-controller
             - --election-id=ingress-controller-leader
             - --controller-class=k8s.io/ingress-nginx
             - --ingress-class=nginx
             - --configmap=$(POD_NAMESPACE)/ingress-nginx-controller
             - --validating-webhook=:8443
             - --validating-webhook-certificate=/usr/local/certificates/cert
             - --validating-webhook-key=/usr/local/certificates/key
             - --default-ssl-certificate=ingress-nginx/my-tls-secret           # <<<<<<<<<<<<<<

    4. (If deploying NGINX Ingress Controller 1.9.5 or later) Under kind: Daemonset, locate securityContext, and then set the value of the flag allowPrivilegeEscalation as true.

      securityContext:
                allowPrivilegeEscalation: true
  6. Apply the Security Context Constraints (SCC) to service accounts by running the following commands:

    1. If the version of your OpenShift cluster is lower than 4.14:

      oc adm policy add-scc-to-user ingress-scc -z default -n ingress-nginx
      oc adm policy add-scc-to-user ingress-scc -z ingress-nginx-admission -n ingress-nginx
      oc adm policy add-scc-to-user ingress-scc -z ingress-nginx -n ingress-nginx

    2. If the version of your OpenShift cluster is 4.14 or higher:

      oc -n ingress-nginx annotate job.batch/ingress-nginx-admission-patch openshift.io/required-scc="ingress-scc"
      oc -n ingress-nginx annotate job.batch/ingress-nginx-admission-create openshift.io/required-scc="ingress-scc"
      oc -n ingress-nginx annotate daemonset.apps/ingress-nginx-controller openshift.io/required-scc="ingress-scc"

  7. To apply the deploy.yaml, run the following command:

    kubectl apply -f deploy.yaml


  8. To verify that the NGINX Ingress Controller pods are running on all worker nodes, run the following command:

    kubectl -n ingress-nginx get pods

  9. To verify the version of the NGINX Ingress Controller from one of the pod logs, run the following command:

    kubectl logs <ingress controller pod> -n ingress-nginx | less

    Where -n ingress-nginx is the ingress namespace.
    The pod logs should have the same version of the NGINX Ingress Controller that you installed.

  10. To make sure that the same ports of the NGINX Ingress Controller service are configured in the load balancer, run the following command:

    kubectl -n ingress-nginx get service

  11. The Validating Webhook Configuration blocks the deployment of a few Ingress objects. To delete the Validating Webhook Configuration, run the following command:

    kubectl -n ingress-nginx delete  ValidatingWebhookConfiguration ingress-nginx-admission

Performing post upgrade task

Important

Perform this step if you are upgrading NGINX Ingress Controller to version 1.9.3 and higher.

  1. In the ingress-nginx namespace, open the nginx-configuration configmap and review the value of allow-snippet-annotations configuration parameter.
  2. If the value of allow-snippet-annotations is false, set it to true.
    allow-snippet-annotations: "true".

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*