</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 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-an
</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></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>
