</code></pre></div></p><h2id=what-has-caused-this-change-in-behavior>What has caused this change in behavior?<aclass=headerlinkhref=#what-has-caused-this-change-in-behaviortitle="Permanent link"> ¶</a></h2><p>There are 2 reasons primarily.</p><h3id=reason-1>Reason #1<aclass=headerlinkhref=#reason-1title="Permanent link"> ¶</a></h3><p>Until K8s version 1.21, it was possible to create an Ingress resource using deprecated versions of the Ingress API, such as:</p><ul><li><code>extensions/v1beta1</code></li><li><code>networking.k8s.io/v1beta1</code></li></ul><p>You would get a message about deprecation, but the Ingress resource would get created.</p><p>From K8s version 1.22 onwards, you can <strong>only</strong> access the Ingress API via the stable, <code>networking.k8s.io/v1</code> API. The reason is explained in the <ahref=https://kubernetes.io/blog/2021/07/26/update-with-ingress-nginx/>official blog on deprecated ingress API versions</a>.</p><h3id=reason-2>Reason #2<aclass=headerlinkhref=#reason-2title="Permanent link"> ¶</a></h3><p>If you are already using the Ingress-NGINX controller and then upgrade to K8s version v1.22 , there are several scenarios where your existing Ingress objects will not work how you expect. Read this FAQ to check which scenario matches your use case.</p><h2id=what-is-ingressclassname-field>What is ingressClassName field ?<aclass=headerlinkhref=#what-is-ingressclassname-fieldtitle="Permanent link"> ¶</a></h2><p><code>ingressClassName</code> is a field in the specs of an Ingress object.</p><p><divclass=highlight><pre><span></span><code>kubectl explain ingress.spec.ingressClassName
</code></pre></div></p><p>The <code>.spec.ingressClassName</code> behavior has precedence over the deprecated <code>kubernetes.io/ingress.class</code> annotation.</p><h2id=i-have-only-one-ingress-controller-in-my-cluster-what-should-i-do>I have only one ingress controller in my cluster. What should I do?<aclass=headerlinkhref=#i-have-only-one-ingress-controller-in-my-cluster-what-should-i-dotitle="Permanent link"> ¶</a></h2><p>If a single instance of the Ingress-NGINX controller is the sole Ingress controller running in your cluster, you should add the annotation "ingressclass.kubernetes.io/is-default-class" in your IngressClass, so any new Ingress objects will have this one as default IngressClass.</p><p>When using Helm, you can enable this annotation by setting <code>.controller.ingressClassResource.default: true</code> in your Helm chart installation's values file.</p><p>If you have any old Ingress objects remaining without an IngressClass set, you can do one or more of the following to make the Ingress-NGINX controller aware of the old objects:</p><ul><li>You can manually set the <ahref=https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec><code>.spec.ingressClassName</code></a> field in the manifest of your own Ingress resources.</li><li>You can re-create them after setting the <code>ingressclass.kubernetes.io/is-default-class</code> annotation to <code>true</code> on the IngressClass</li><li>Alternatively you can make the Ingress-NGINX controller watch Ingress objects without the ingressClassName field set by starting your Ingress-NGINX with the flag <ahref=#what-is-the-flag-watch-ingress-without-class>--watch-ingress-without-class=true</a> . When using Helm, you can configure your Helm chart installation's values file with <code>.controller.watchIngressWithoutClass: true</code></li></ul><p>You can configure your Helm chart installation's values file with <code>.controller.watchIngressWithoutClass: true</code>. </p><p>We recommend that you create the IngressClass as shown below: <divclass=highlight><pre><span></span><code>---
</code></pre></div></p><p>And add the value <code>spec.ingressClassName=nginx</code> in your Ingress objects.</p><h2id=i-have-multiple-ingress-objects-in-my-cluster-what-should-i-do>I have multiple ingress objects in my cluster. What should I do ?<aclass=headerlinkhref=#i-have-multiple-ingress-objects-in-my-cluster-what-should-i-dotitle="Permanent link"> ¶</a></h2><ul><li>If you have lot of ingress objects without ingressClass configuration, you can run the ingress-controller with the flag <code>--watch-ingress-without-class=true</code>.</li></ul><h3id=what-is-the-flag-watch-ingress-without-class>What is the flag '--watch-ingress-without-class' ?<aclass=headerlinkhref=#what-is-the-flag-watch-ingress-without-classtitle="Permanent link"> ¶</a></h3><ul><li>Its a flag that is passed,as an argument, to the <code>nginx-ingress-controller</code> executable. In the configuration, it looks like this: <divclass=highlight><pre><span></span><code>...
</code></pre></div></li></ul><h2id=i-have-more-than-one-controller-in-my-cluster-and-already-use-the-annotation>I have more than one controller in my cluster and already use the annotation ?<aclass=headerlinkhref=#i-have-more-than-one-controller-in-my-cluster-and-already-use-the-annotationtitle="Permanent link"> ¶</a></h2><p>No problem. This should still keep working, but we highly recommend you to test!</p><p>Even though <code>kubernetes.io/ingress.class</code> is deprecated, the Ingress-NGINX controller still understands that annotation. If you want to follow good practice, you should consider migrating to use IngressClass and <code>.spec.ingressClassName</code>.</p><h2id=i-have-more-than-one-controller-running-in-my-cluster-and-i-want-to-use-the-new-api>I have more than one controller running in my cluster, and I want to use the new API ?<aclass=headerlinkhref=#i-have-more-than-one-controller-running-in-my-cluster-and-i-want-to-use-the-new-apititle="Permanent link"> ¶</a></h2><p>In this scenario, you need to create multiple IngressClasses (see example one). But be aware that IngressClass works in a very specific way: you will need to change the <code>.spec.controller</code> value in your IngressClass and configure the controller to expect the exact same value.</p><p>Let's see some example, supposing that you have three IngressClasses:</p><ul><li>IngressClass <code>ingress-nginx-one</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx1</code></li><li>IngressClass <code>ingress-nginx-two</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx2</code></li><li>IngressClass <code>ingress-nginx-three</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx1</code></li></ul><p>(for private use, you can also use a controller name that doesn't contain a <code>/</code>; for example: <code>ingress-nginx1</code>)</p><p>When deploying your ingress controllers, you will have to change the <code>--controller-class</code> field as follows:</p><ul><li>Ingress-Nginx A, configured to use controller class name <code>example.com/ingress-nginx1</code></li><li>Ingress-Nginx B, configured to use controller class name <code>example.com/ingress-nginx2</code></li></ul><p>Then, when you create an Ingress object with its <code>ingressClassName</code> set to <code>ingress-nginx-two</code>, only controllers looking for the <code>example.com/ingress-nginx2</code> controller class pay attention to the new object. Given that Ingress-Nginx B is set up that way, it will serve that object, whereas Ingress-Nginx A ignores the new Ingress.</p><p>Bear in mind that, if you start Ingress-Nginx B with the command line argument <code>--watch-ingress-without-class=true</code>, then it will serve:</p><ol><li>Ingresses without any <code>ingressClassName</code> set</li><li>Ingresses where the deprecated annotation (<code>kubernetes.io/ingress.class</code>) matches the value set in the command line argument <code>--ingress-class</code></li><li>Ingresses that refer to any IngressClass that has the same <code>spec.controller</code> as configured in <code>--controller-class</code></li></ol><p>If you start Ingress-Nginx B with the command line argument <code>--watch-ingress-without-class=true</code> and you run Ingress-Nginx A with the command line argument <code>--watch-ingress-without-class=false</code> then this is a supported configuration. If you have two Ingress-NGINX controllers for the same cluster, both running with <code>--watch-ingress-without-class=true</code> then there is likely to be a conflict.</p><h2id=i-am-seeing-this-error-message-in-the-logs-of-the-ingress-nginx-controller-ingress-class-annotation-is-not-equal-to-the-expected-by-ingress-controller-why>I am seeing this error message in the logs of the Ingress-NGINX controller: "ingress class annotation is not equal to the expected by Ingress Controller". Why ?<aclass=headerlinkhref=#i-am-seeing-this-error-message-in-the-logs-of-the-ingress-nginx-controller-ingress-class-annota
</code></pre></div></li><li>Use Helm to install the additional instance of the ingress controller</li><li>Ensure you have Helm working (refer to the <ahref=https://helm.sh/docs/>Helm documentation</a>)</li><li>We have to assume that you have the helm repo for the ingress-NGINX controller already added to your Helm config. But, if you have not added the helm repo then you can do this to add the repo to your helm config; <divclass=highlight><pre><span></span><code>helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
</code></pre></div></li><li>Now, install an additional instance of the ingress-NGINX controller like this: <divclass=highlight><pre><span></span><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx \
</code></pre></div></li><li>If you need to install yet another instance, then repeat the procedure to create a new namespace, change the values such as names & namespaces (for example from "-2" to "-3"), or anything else that meets your needs.</li><li>If you need to install all instances in the same namespace, then you need to specify a different <strong>election id</strong>, like this: <divclass=highlight><pre><span></span><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx \
</code></pre></div></li><li>Note, controller.ingressClassResource.name and controller.ingressClass have to be set with the value of the new class as the first is to create the IngressClass object and the other is to modify the deployment of the actuall ingress controller pod.</li></ul></article></div></div></main><footerclass=md-footer><divclass=md-footer-nav><navclass="md-footer-nav__inner md-grid"aria-label=Footer><ahref=how-it-works/class="md-footer-nav__link md-footer-nav__link--next"rel=next><divclass=md-footer-nav__title><divclass=md-ellipsis><spanclass=md-footer-nav__direction> Next </span> How it works </div></div><divclass="md-footer-nav__button md-icon"><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg></div></a></nav></div><divclass="md-footer-meta md-typeset"><divclass="md-footer-meta__inner md-grid"><divclass=md-footer-copyright> Made with <ahref=https://squidfunk.github.io/mkdocs-material/target=_blankrel=noopener> Material for MkDocs </a></div></div></div></footer></div><scriptsrc=assets/javascripts/vendor.93c04032.min.js></script><scriptsrc=assets/javascripts/bundle.83e5331e.min.js></script><scriptid=__langtype=application/json>{"clipboard.copy":"Copy to clipboard","clipboard.copied":"Copied to clipboard","search.config.lang":"en","search.config.pipeline":"trimmer, stopWordFilter","search.config.separator":"[\\s\\-]+","search.placeholder":"Search","search.result.placeholder":"Type to start searching","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.term.missing":"Missing"}</script><script>
