Upgrade from 1.x to 2.x

This guide describes the steps to perform an upgrade of the component from version 1.x to 2.x.

Version 2.x does use Ingress NGINX Controller >1.0.

Before upgrading to version 2.x, please ensure that your Kubernetes cluster is running the version 1.19 or later.


  • commodore

  • kubectl

  • shell


The component version 1.x did use Ingress NGINX Controller v0.x and component version 2.x is now using Ingress NGINX Controller v1.x.

The Ingress NGINX Controller v1.x now requires the use of an IngressClass.

With the upgrade the component is automatically deploying an IngressClass called nginx for the controller:

apiVersion: networking.k8s.io/v1
kind: IngressClass
    app.kubernetes.io/component: controller
  name: nginx
  controller: k8s.io/ingress-nginx

Step-by-step guide

  1. If the Ingress NGINX Controller should be the default IngressController, please add this to the configuration:

              default: true
  2. If not all Ingress resources have a .spec.ingressClassName configured, you must set watchIngressWithoutClass: true to still watch for such objects:

            watchIngressWithoutClass: true

Post upgrade

Since NGINX Controller v1.0 the .spec.ingressClassName field should be set in the Ingress resource. If the .spec.ingressClassName is omitted, a default Ingress class should be defined. If no customisation is done, the IngressClass is named nginx.

ArgoCD does ignore .spec.ingressClassName if not set in the original manifest.

For more information read the NGINX Ingress Controller documentation on the topic I have only one ingress controller in my cluster. What should I do?.

Existing Ingress objects don’t get the default IngressClass. They need to be recreated or patched.

Patch one Ingress resource:

kubectl patch ingress <ingressname> --patch '{"spec": {"ingressClassName": "nginx"}}' --namespace <namespace>

Patch all Ingress resources on a cluster (BE CAREFUL WITH IT, IF YOU HAVE MULTIPLE INGRESS CONTROLLERS!):

  1. Show all Ingress resources that will be patched:

    for ns in $(kubectl get ns -o jsonpath={.items[*].metadata.name}); do \
      for ing in $(kubectl get ingress -n $ns -o jsonpath={.items[*].metadata.name}); do \
        echo $ns/$ing; \
      done; \
  2. Patch all Ingress resouces on a cluster:

    for ns in $(kubectl get ns -o jsonpath={.items[*].metadata.name}); do \
      for ing in $(kubectl get ingress -n $ns -o jsonpath={.items[*].metadata.name}); do \
        echo Patching ingress $ns/$ing; \
        kubectl patch ingress $ing -n $ns --patch '{"spec": {"ingressClassName": "nginx"}}'; \
      done; \

Any kubernetes.io/ingress.class annotation on Ingress resources can be removed. See the Kubernetes documentation.

Check which Ingress resources do have a defined IngressClass:

$ kubectl get ing -A
NAMESPACE               NAME                        CLASS   HOSTS
ingress1                ingress1                    nginx   host.example.com

Once all Ingress resouces have been patched for ingressClassName the parameter .controller.watchIngressWithoutClass: true will no longer be required and can be removed from the configuration.