ingress-nginx
/
index.html

<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><link href=https://kubernetes.github.io/ingress-nginx/ rel=canonical><link rel="shortcut icon" href=assets/images/favicon.png><meta name=generator content="mkdocs-1.1.2, mkdocs-material-6.2.4"><title>Welcome - NGINX Ingress Controller</title><link rel=stylesheet href=assets/stylesheets/main.15aa0b43.min.css><link rel=stylesheet href=assets/stylesheets/palette.75751829.min.css><meta name=theme-color content=#009485><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700%7CRoboto+Mono&display=fallback"><style>body,input{font-family:"Roboto",-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono",SFMono-Regular,Consolas,Menlo,monospace}</style><link rel=stylesheet href=extra.css><script>window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)},ga.l=+new Date,ga("create","UA-118407822-1","kubernetes.github.io"),ga("set","anonymizeIp",!0),ga("send","pageview"),document.addEventListener("DOMContentLoaded",function(){document.forms.search&&document.forms.search.query.addEventListener("blur",function(){if(this.value){var e=document.location.pathname;ga("send","pageview",e+"?q="+this.value)}})}),document.addEventListener("DOMContentSwitch",function(){ga("send","pageview",document.location.pathname)})</script><script async src=https://www.google-analytics.com/analytics.js></script></head> <body dir=ltr data-md-color-scheme data-md-color-primary=teal data-md-color-accent=green> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#welcome class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header-nav md-grid" aria-label=Header> <a href=https://kubernetes.github.io/ingress-nginx title="NGINX Ingress Controller" class="md-header-nav__button md-logo" aria-label="NGINX Ingress Controller"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 003-3 3 3 0 00-3-3 3 3 0 00-3 3 3 3 0 003 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54z"/></svg> </a> <label class="md-header-nav__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg> </label> <div class=md-header-nav__title data-md-component=header-title> <div class=md-header-nav__ellipsis> <div class=md-header-nav__topic> <span class=md-ellipsis> NGINX Ingress Controller </span> </div> <div class=md-header-nav__topic> <span class=md-ellipsis> Welcome </span> </div> </div> </div> <label class="md-header-nav__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0116 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 019.5 16 6.5 6.5 0 013 9.5 6.5 6.5 0 019.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__inner role=search> <form class=md-search__form name=search> <input type=text class=md-search__input name=query aria-label=Search placeholder=Search autocapitalize=off autocorrect=off autocomplete=off spellcheck=false data-md-component=search-query data-md-state=active required> <label class="md-search__icon md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0116 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 019.5 16 6.5 6.5 0 013 9.5 6.5 6.5 0 019.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg> </label> <button type=reset class="md-search__icon md-icon" aria-label=Clear data-md-component=search-reset tabindex=-1> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg> </button> </form> <div class=md-search__output> <div class=md-search__scrollwrap data-md-scrollfix> <div class=md-search-result data-md-component=search-result> <div class=md-search-result__meta> Initializing search </div> <ol class=md-search-result__list></ol> </div> </div> </div> </div> </div> <div class=md-header-nav__source> <a href=https://github.com/kubernetes/ingress-nginx/ title="Go to repository" class=md-source> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><path d="M439.55 236.05L244 40.45a28.87 28.87 0 00-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 01-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 000 40.81l195.61 195.6a28.86 28.86 0 0040.8 0l194.69-194.69a28.86 28.86 0 000-40.81z"/></svg> </div> <div class=md-source__repository> kubernetes/ingress-nginx </div> </a> </div> </nav> </header> <div class=md-container data-md-component=container> <nav class=md-tabs aria-label=Tabs data-md-component=tabs> <div class="md-tabs__inner md-grid"> <ul class=md-tabs__list> <li class=md-tabs__item> <a href=. class="md-tabs__link md-tabs__link--active"> Welcome </a> </li> <li class=md-tabs__item> <a href=deploy/ class=md-tabs__link> Deployment </a> </li> <li class=md-tabs__item> <a href=user-guide/nginx-configuration/ class=md-tabs__link> User guide </a> </li> <li class=md-tabs__item> <a href=examples/ class=md-tabs__link> Examples </a> </li> <li class=md-tabs__item> <a href=developer-guide/getting-started/ class=md-tabs__link> Developer Guide </a> </li> </ul> </div> </nav> <main class=md-main data-md-component=main> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component=navigation> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--primary md-nav--lifted" aria-label=Navigation data-md-level=0> <label class=md-nav__title for=__drawer> <a href=https://kubernetes.github.io/ingress-nginx title="NGINX Ingress Controller" class="md-nav__button md-logo" aria-label="NGINX Ingress Controller"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 003-3 3 3 0 00-3-3 3 3 0 00-3 3 3 3 0 003 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54z"/></svg> </a> NGINX Ingress Controller </label> <div class=md-nav__source> <a href=https://github.com/kubernetes/ingress-nginx/ title="Go to repository" class=md-source> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 512"><path d="M439.55 236.05L244 40.45a28.87 28.87 0 00-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 01-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 000 40.81l195.61 195.6a28.86 28.86 0 0040.8 0l194.69-194.69a28.86 28.86 0 000-40.81z"/></svg> </div> <div class=md-source__repository> kubernetes/ingress-nginx </div> </a> </div> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-1 type=checkbox id=nav-1 checked> <label class=md-nav__link for=nav-1> Welcome <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label=Welcome data-md-level=1> <label class=md-nav__title for=nav-1> <span class="md-nav__icon md-icon"></span> Welcome </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" data-md-toggle=toc type=checkbox id=__toc> <label class="md-nav__link md-nav__link--active" for=__toc> Welcome <span class="md-nav__icon md-icon"></span> </label> <a href=. class="md-nav__link md-nav__link--active"> Welcome </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class=md-nav__title for=__toc> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=#getting-started class=md-nav__link> Getting Started </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=how-it-works/ class=md-nav__link> How it works </a> </li> <li class=md-nav__item> <a href=troubleshooting/ class=md-nav__link> Troubleshooting </a> </li> <li class=md-nav__item> <a href=kubectl-plugin/ class=md-nav__link> kubectl plugin </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-2 type=checkbox id=nav-2> <label class=md-nav__link for=nav-2> Deployment <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label=Deployment data-md-level=1> <label class=md-nav__title for=nav-2> <span class="md-nav__icon md-icon"></span> Deployment </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=deploy/ class=md-nav__link> Installation Guide </a> </li> <li class=md-nav__item> <a href=deploy/baremetal/ class=md-nav__link> Bare-metal considerations </a> </li> <li class=md-nav__item> <a href=deploy/rbac/ class=md-nav__link> Role Based Access Control (RBAC) </a> </li> <li class=md-nav__item> <a href=deploy/upgrade/ class=md-nav__link> Upgrade </a> </li> <li class=md-nav__item> <a href=deploy/hardening-guide/ class=md-nav__link> Hardening guide </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-3 type=checkbox id=nav-3> <label class=md-nav__link for=nav-3> User guide <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label="User guide" data-md-level=1> <label class=md-nav__title for=nav-3> <span class="md-nav__icon md-icon"></span> User guide </label> <ul class=md-nav__list data-md-scrollfix> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-3-1 type=checkbox id=nav-3-1> <label class=md-nav__link for=nav-3-1> NGINX Configuration <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label="NGINX Configuration" data-md-level=2> <label class=md-nav__title for=nav-3-1> <span class="md-nav__icon md-icon"></span> NGINX Configuration </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=user-guide/nginx-configuration/ class=md-nav__link> Introduction </a> </li> <li class=md-nav__item> <a href=user-guide/basic-usage/ class=md-nav__link> Basic usage </a> </li> <li class=md-nav__item> <a href=user-guide/nginx-configuration/annotations/ class=md-nav__link> Annotations </a> </li> <li class=md-nav__item> <a href=user-guide/nginx-configuration/configmap/ class=md-nav__link> ConfigMap </a> </li> <li class=md-nav__item> <a href=user-guide/nginx-configuration/custom-template/ class=md-nav__link> Custom NGINX template </a> </li> <li class=md-nav__item> <a href=user-guide/nginx-configuration/log-format/ class=md-nav__link> Log format </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=user-guide/cli-arguments/ class=md-nav__link> Command line arguments </a> </li> <li class=md-nav__item> <a href=user-guide/custom-errors/ class=md-nav__link> Custom errors </a> </li> <li class=md-nav__item> <a href=user-guide/default-backend/ class=md-nav__link> Default backend </a> </li> <li class=md-nav__item> <a href=user-guide/exposing-tcp-udp-services/ class=md-nav__link> Exposing TCP and UDP services </a> </li> <li class=md-nav__item> <a href=user-guide/fcgi-services/ class=md-nav__link> Exposing FCGI services </a> </li> <li class=md-nav__item> <a href=user-guide/ingress-path-matching/ class=md-nav__link> Regular expressions in paths </a> </li> <li class=md-nav__item> <a href=user-guide/external-articles/ class=md-nav__link> External Articles </a> </li> <li class=md-nav__item> <a href=user-guide/miscellaneous/ class=md-nav__link> Miscellaneous </a> </li> <li class=md-nav__item> <a href=user-guide/monitoring/ class=md-nav__link> Prometheus and Grafana installation </a> </li> <li class=md-nav__item> <a href=user-guide/multiple-ingress/ class=md-nav__link> Multiple Ingress controllers </a> </li> <li class=md-nav__item> <a href=user-guide/tls/ class=md-nav__link> TLS/HTTPS </a> </li> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-3-13 type=checkbox id=nav-3-13> <label class=md-nav__link for=nav-3-13> Third party addons <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label="Third party addons" data-md-level=2> <label class=md-nav__title for=nav-3-13> <span class="md-nav__icon md-icon"></span> Third party addons </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=user-guide/third-party-addons/modsecurity/ class=md-nav__link> ModSecurity Web Application Firewall </a> </li> <li class=md-nav__item> <a href=user-guide/third-party-addons/opentracing/ class=md-nav__link> OpenTracing </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-4 type=checkbox id=nav-4> <label class=md-nav__link for=nav-4> Examples <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label=Examples data-md-level=1> <label class=md-nav__title for=nav-4> <span class="md-nav__icon md-icon"></span> Examples </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=examples/ class=md-nav__link> Introduction </a> </li> <li class=md-nav__item> <a href=examples/PREREQUISITES/ class=md-nav__link> Prerequisites </a> </li> <li class=md-nav__item> <a href=examples/affinity/cookie/ class=md-nav__link> Sticky Sessions </a> </li> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-4-4 type=checkbox id=nav-4-4> <label class=md-nav__link for=nav-4-4> Auth <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label=Auth data-md-level=2> <label class=md-nav__title for=nav-4-4> <span class="md-nav__icon md-icon"></span> Auth </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=examples/auth/basic/ class=md-nav__link> Basic Authentication </a> </li> <li class=md-nav__item> <a href=examples/auth/client-certs/ class=md-nav__link> Client Certificate Authentication </a> </li> <li class=md-nav__item> <a href=examples/auth/external-auth/ class=md-nav__link> External Basic Authentication </a> </li> <li class=md-nav__item> <a href=examples/auth/oauth-external-auth/ class=md-nav__link> External OAUTH Authentication </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-4-5 type=checkbox id=nav-4-5> <label class=md-nav__link for=nav-4-5> Customization <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label=Customization data-md-level=2> <label class=md-nav__title for=nav-4-5> <span class="md-nav__icon md-icon"></span> Customization </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=examples/customization/configuration-snippets/ class=md-nav__link> Configuration Snippets </a> </li> <li class=md-nav__item> <a href=examples/customization/custom-configuration/ class=md-nav__link> Custom Configuration </a> </li> <li class=md-nav__item> <a href=examples/customization/custom-errors/ class=md-nav__link> Custom Errors </a> </li> <li class=md-nav__item> <a href=examples/customization/custom-headers/ class=md-nav__link> Custom Headers </a> </li> <li class=md-nav__item> <a href=examples/customization/external-auth-headers/ class=md-nav__link> External authentication </a> </li> <li class=md-nav__item> <a href=examples/customization/ssl-dh-param/ class=md-nav__link> Custom DH parameters for perfect forward secrecy </a> </li> <li class=md-nav__item> <a href=examples/customization/sysctl/ class=md-nav__link> Sysctl tuning </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=examples/docker-registry/ class=md-nav__link> Docker registry </a> </li> <li class=md-nav__item> <a href=examples/grpc/ class=md-nav__link> gRPC </a> </li> <li class=md-nav__item> <a href=examples/multi-tls/ class=md-nav__link> Multi TLS certificate termination </a> </li> <li class=md-nav__item> <a href=examples/rewrite/ class=md-nav__link> Rewrite </a> </li> <li class=md-nav__item> <a href=examples/static-ip/ class=md-nav__link> Static IPs </a> </li> <li class=md-nav__item> <a href=examples/tls-termination/ class=md-nav__link> TLS termination </a> </li> <li class=md-nav__item> <a href=examples/psp/ class=md-nav__link> Pod Security Policy (PSP) </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle=nav-5 type=checkbox id=nav-5> <label class=md-nav__link for=nav-5> Developer Guide <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav aria-label="Developer Guide" data-md-level=1> <label class=md-nav__title for=nav-5> <span class="md-nav__icon md-icon"></span> Developer Guide </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=developer-guide/getting-started/ class=md-nav__link> Getting Started </a> </li> <li class=md-nav__item> <a href=developer-guide/code-overview/ class=md-nav__link> Code Overview </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component=toc> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class=md-nav__title for=__toc> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=#getting-started class=md-nav__link> Getting Started </a> </li> </ul> </nav> </div> </div> </div> <div class=md-content> <article class="md-content__inner md-typeset"> <a href=https://github.com/kubernetes/ingress-nginx/edit/master/docs/index.md title="Edit this page" class="md-content__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z"/></svg> </a> <h1 id=welcome>Welcome<a class=headerlink href=#welcome title="Permanent link"> ¶</a></h1> <p>This is the documentation for the NGINX Ingress Controller.</p> <p>It is built around the <a href=http://kubernetes.io/docs/user-guide/ingress/ >Kubernetes Ingress resource</a>, using a <a href=https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#understanding-configmaps-and-pods>ConfigMap</a> to store the NGINX configuration.</p> <p>Learn more about using Ingress on <a href=http://kubernetes.io/docs/user-guide/ingress/ >k8s.io</a>.</p> <h2 id=getting-started>Getting Started<a class=headerlink href=#getting-started title="Permanent link"> ¶</a></h2> <p>See <a href=./deploy/ >Deployment</a> for a whirlwind tour that will get you started.</p> <h1 id=faq-migration-to-apiversion-networkingk8siov1>FAQ - Migration to apiVersion networking.k8s.io/v1<a class=headerlink href=#faq-migration-to-apiversion-networkingk8siov1 title="Permanent link"> ¶</a></h1> <ul> <li> <p>Please read this <a href=https://kubernetes.io/blog/2021/07/26/update-with-ingress-nginx/ >official blog on deprecated ingress api versions</a> If you are using ingress objects in your pre K8s v1.22 cluster, and you upgrade to K8s v1.22, then this document may be relevant to you.</p> </li> <li> <p>Please read this <a href=https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class>official documentation on the IngressClass object</a></p> </li> </ul> <h2 id=what-is-an-ingressclass-and-why-is-it-important-for-users-of-ingress-nginx-controller-now>What is an ingressClass and why is it important for users of Ingress-NGINX controller now ?<a class=headerlink href=#what-is-an-ingressclass-and-why-is-it-important-for-users-of-ingress-nginx-controller-now title="Permanent link"> ¶</a></h2> <p>IngressClass is a Kubernetes resource. See the description below. Its important because until now, a default install of the Ingress-NGINX controller did not require a ingressClass object. But from version 1.0.0 of the Ingress-NGINX Controller, a ingressclass object is required.</p> <p>On clusters with more than one instance of the Ingress-NGINX controller, all instances of the controllers must be aware of which Ingress object they must serve. The ingressClass field of a ingress object is the way to let the controller know about that. </p> <div class=highlight><pre><span></span><code>_$ k explain ingressClass
KIND:     IngressClass
VERSION:  networking.k8s.io/v1

DESCRIPTION:
     IngressClass represents the class of the Ingress, referenced by the Ingress
     Spec. The `ingressclass.kubernetes.io/is-default-class` annotation can be
     used to indicate that an IngressClass should be considered default. When a
     single IngressClass resource has this annotation set to true, new Ingress
     resources without a class specified will be assigned this default class.

FIELDS:
   apiVersion   &lt;string&gt;
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

   kind &lt;string&gt;
     Kind is a string value representing the REST resource this object
     represents. Servers may infer this from the endpoint the client submits
     requests to. Cannot be updated. In CamelCase. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

   metadata     &lt;Object&gt;
     Standard object&#39;s metadata. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

   spec &lt;Object&gt;
     Spec is the desired state of the IngressClass. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status`
</code></pre></div> <h2 id=what-has-caused-this-change-in-behaviour>What has caused this change in behaviour ?<a class=headerlink href=#what-has-caused-this-change-in-behaviour title="Permanent link"> ¶</a></h2> <p>There are 2 reasons primarily.</p> <p>(Reason #1) Until K8s version 1.21, it was was possible to create a ingress resource, with the "apiVersion:" field set to a value like ; - extensions/v1beta1 - networking.k8s.io/v1beta1</p> <div class=highlight><pre><span></span><code>(You would get a message about deprecation but the ingress resource would get created.)
</code></pre></div> <p>From K8s version 1.22 onwards, you can ONLY set the "apiVersion:" field of a ingress resource, to the value "networking.k8s.io/v1". The reason is <a href=https://kubernetes.io/blog/2021/07/26/update-with-ingress-nginx/ >official blog on deprecated ingress api versions</a>.</p> <p>(Reason #2) When you upgrade to K8s version v1.22, while you are already using the Ingress-NGINX controller, there are several scenarios where the old existing ingress objects will not work. Read this FAQ to check which scenario matches your use case.</p> <h2 id=what-is-ingressclassname-field>What is ingressClassName field ?<a class=headerlink href=#what-is-ingressclassname-field title="Permanent link"> ¶</a></h2> <p>ingressClassName is a field in the specs of a ingress object.</p> <p><div class=highlight><pre><span></span><code>% k explain ingress.spec.ingressClassName
KIND:     Ingress
VERSION:  networking.k8s.io/v1

FIELD:    ingressClassName &lt;string&gt;

DESCRIPTION:
     IngressClassName is the name of the IngressClass cluster resource. The
     associated IngressClass defines which controller will implement the
     resource. This replaces the deprecated `kubernetes.io/ingress.class`
     annotation. For backwards compatibility, when that annotation is set, it
     must be given precedence over this field. The controller may emit a warning
     if the field and annotation have different values. Implementations of this
     API should ignore Ingresses without a class specified. An IngressClass
     resource may be marked as default, which can be used to set a default value
     for this field. For more information, refer to the IngressClass
     documentation.
</code></pre></div> the spec.ingressClassName behavior has precedence over the annotation.</p> <h2 id=i-have-only-one-instance-of-the-ingresss-nginx-controller-in-my-cluster-what-should-i-do>I have only one instance of the Ingresss-NGINX controller in my cluster. What should I do ?<a class=headerlink href=#i-have-only-one-instance-of-the-ingresss-nginx-controller-in-my-cluster-what-should-i-do title="Permanent link"> ¶</a></h2> <ul> <li>If you have only one instance of the Ingress-NGINX controller running in your cluster, and you still want to use ingressclass, you should add the annotation "ingressclass.kubernetes.io/is-default-class" in your ingress class, so any new Ingress objects will have this one as default ingressClass.</li> </ul> <p>In this case, you need to make your Controller aware of the objects. If you have several Ingress objects and they don't yet have the <a href=https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#ingress-v1-networking-k8s-io>ingressClassName</a> field, or the ingress annotation (<code>kubernetes.io/ingress.class</code>), then you should start your ingress-controller with the flag <a href="## What is the flag '--watch-ingress-without-class' ?">--watch-ingress-without-class=true</a> .</p> <p>You can configure your helm chart installation's values file with <code>.controller.watchIngressWithoutClass: true</code>. </p> <p>We highly recommend that you create the ingressClass as shown below: <div class=highlight><pre><span></span><code>apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  labels:
    app.kubernetes.io/component: controller
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: &quot;true&quot;
spec:
  controller: k8s.io/ingress-nginx
</code></pre></div> And add the value "spec.ingressClassName=nginx" in your Ingress objects</p> <h2 id=i-have-multiple-ingress-objects-in-my-cluster-what-should-i-do>I have multiple ingress objects in my cluster. What should I do ?<a class=headerlink href=#i-have-multiple-ingress-objects-in-my-cluster-what-should-i-do title="Permanent link"> ¶</a></h2> <ul> <li>If you don't care about ingressClass, or you have a 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> <h2 id=what-is-the-flag-watch-ingress-without-class>What is the flag '--watch-ingress-without-class' ?<a class=headerlink href=#what-is-the-flag-watch-ingress-without-class title="Permanent link"> ¶</a></h2> <ul> <li>Its a flag that is passed,as an argument, to the ingress-controller executable, in the pod spec. It looks like this ; <div class=highlight><pre><span></span><code>...
...
args:
  - /nginx-ingress-controller
  - --publish-service=$(POD_NAMESPACE)/ingress-nginx-dev-v1-test-controller
  - --election-id=ingress-controller-leader
  - --controller-class=k8s.io/ingress-nginx
  - --configmap=$(POD_NAMESPACE)/ingress-nginx-dev-v1-test-controller
  - --validating-webhook=:8443
  - --validating-webhook-certificate=/usr/local/certificates/cert
  - --validating-webhook-key=/usr/local/certificates/key
  - --watch-ingress-without-class=true
...
...
</code></pre></div></li> </ul> <h2 id=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 ?<a class=headerlink href=#i-have-more-than-one-controller-in-my-cluster-and-already-use-the-annotation title="Permanent link"> ¶</a></h2> <p>No problem. This should still keep working, but we highly recommend you to test!</p> <h2 id=i-have-more-than-one-controller-running-in-my-cluster-and-i-want-to-use-the-new-spec>I have more than one controller running in my cluster, and I want to use the new spec ?<a class=headerlink href=#i-have-more-than-one-controller-running-in-my-cluster-and-i-want-to-use-the-new-spec title="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 .spec.controller value in your IngressClass and point the controller to the relevant ingressClass. Let's see some example, supposing that you have two Ingress Classes:</p> <ul> <li>Ingress-Nginx-IngressClass-1 with .spec.controller equals to "k8s.io/ingress-nginx1"</li> <li>Ingress-Nginx-IngressClass-2 with .spec.controller equals to "k8s.io/ingress-nginx2" When deploying your ingress controllers, you will have to change the <code>--controller-class</code> field as follows:</li> </ul> <p>Ingress-Nginx-Controller-nginx1 with <code>k8s.io/ingress-nginx1</code> Ingress-Nginx-Controller-nginx2 with <code>k8s.io/ingress-nginx2</code> Then, when you create an Ingress Object with IngressClassName = <code>ingress-nginx2</code>, it will look for controllers with <code>controller-class=k8s.io/ingress-nginx2</code> and as <code>Ingress-Nginx-Controller-nginx2</code> is watching objects that points to <code>ingressClass="k8s.io/ingress-nginx2</code>, it will serve that object, while <code>Ingress-Nginx-Controller-nginx1</code> will ignore the ingress object.</p> <p>Bear in mind that, if your <code>Ingress-Nginx-Controller-nginx2</code> is started with the flag <code>--watch-ingress-without-class=true</code>, then it will serve ; - objects without ingress-class - objects with the annotation configured in flag <code>--ingress-class</code> and same class value - and also objects pointing to the ingressClass that have the same .spec.controller as configured in <code>--controller-class</code></p> <h2 id=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 ?<a class=headerlink href=#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 title="Permanent link"> ¶</a></h2> <ul> <li>It is highly likely that you will also see the name of the ingress resource in the same error message. This error messsage has been observed on use the deprecated annotation, to spec the ingressClass, in a ingress resource manifest. It is recommended to use the ingress.spec.ingressClassName field, of the ingress resource, to spec the name of the ingressClass of the ingress resource being configured.</li> </ul> <h2 id=how-to-easily-install-multiple-instances-of-the-ingress-nginx-controller-in-the-same-cluster>How to easily install multiple instances of the ingress-NGINX controller in the same cluster ?<a class=headerlink href=#how-to-easily-install-multiple-instances-of-the-ingress-nginx-controller-in-the-same-cluster title="Permanent link"> ¶</a></h2> <ul> <li>Create a new namespace <div class=highlight><pre><span></span><code>kubectl create namespace ingress-controller-2
</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 helm documentation)</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; <div class=highlight><pre><span></span><code>helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx`
</code></pre></div></li> <li>Make sure you have updated the helm repo data; <div class=highlight><pre><span></span><code>helm repo update
</code></pre></div></li> <li>Now you install the additional instance of the ingress-NGINX controller like this ; <div class=highlight><pre><span></span><code>helm --namespace ingress-controller-2 install ingcontroller-2 ingress-nginx/ingress-nginx  \
--set controller.ingressClass=ingress-class-2 \
--set controller.ingressClassResource.name=ingress-class-2 \
--set controller.ingressClassResource.controllerValue= &quot;k8s.io/ingress-controller-2&quot;
</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 like names &amp; namespaces (for example from "-2" to "-3"), or anything else that meets your needs.</li> </ul> </article> </div> </div> </main> <footer class=md-footer> <div class=md-footer-nav> <nav class="md-footer-nav__inner md-grid" aria-label=Footer> <a href=how-it-works/ class="md-footer-nav__link md-footer-nav__link--next" rel=next> <div class=md-footer-nav__title> <div class=md-ellipsis> <span class=md-footer-nav__direction> Next </span> How it works </div> </div> <div class="md-footer-nav__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="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> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-footer-copyright> Made with <a href=https://squidfunk.github.io/mkdocs-material/ target=_blank rel=noopener> Material for MkDocs </a> </div> </div> </div> </footer> </div> <script src=assets/javascripts/vendor.93c04032.min.js></script> <script src=assets/javascripts/bundle.83e5331e.min.js></script><script id=__lang type=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>
        app = initialize({
          base: ".",
          features: ['navigation.tabs', 'navigation.tabs.sticky', 'navigation.instant', 'navigation.sections'],
          search: Object.assign({
            worker: "assets/javascripts/worker/search.8c7e0a7e.min.js"
          }, typeof search !== "undefined" && search)
        })
      </script> </body> </html>