kubernetes
/
ingress-nginx
mirror of https://github.com/kubernetes/ingress-nginx.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
ingress-nginx/index.html

100 lines
39 KiB
HTML
Raw Blame History

<!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=#overview 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/main/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=overview>Overview<a class=headerlink href=#overview title="Permanent link"></a></h1> <p>This is the documentation for the Ingress NGINX Controller.</p> <p>It is built around the <a href=https://kubernetes.io/docs/concepts/services-networking/ingress/ >Kubernetes Ingress resource</a>, using a <a href=https://kubernetes.io/docs/concepts/configuration/configmap/ >ConfigMap</a> to store the controller configuration.</p> <p>You can learn more about using <a href=http://kubernetes.io/docs/user-guide/ingress/ >Ingress</a> in the official <a href=https://docs.k8s.io>Kubernetes documentation</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 <code>networking.k8s.io/v1</code><a class=headerlink href=#faq-migration-to-apiversion-networkingk8siov1 title="Permanent link"></a></h1> <p>If you are using Ingress objects in your cluster (running Kubernetes older than v1.22), and you plan to upgrade to Kubernetes v1.22, this section is relevant to you.</p> <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> </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. It's important because until now, a default install of the Ingress-NGINX controller did not require any IngressClass object. From version 1.0.0 of the Ingress-NGINX Controller, an 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 objects they serve. The <code>ingressClassName</code> field of an Ingress is the way to let the controller know about that. </p> <p><div class=highlight><pre><span></span><code><span class=go>kubectl explain ingressclass </span>
</code></pre></div> <div class=highlight><pre><span></span><code>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></p> <h2 id=what-has-caused-this-change-in-behavior>What has caused this change in behavior?<a class=headerlink href=#what-has-caused-this-change-in-behavior title="Permanent link"></a></h2> <p>There are 2 reasons primarily.</p> <h3 id=reason-1>Reason #1<a class=headerlink href=#reason-1 title="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 <a href=https://kubernetes.io/blog/2021/07/26/update-with-ingress-nginx/ >official blog on deprecated ingress API versions</a>.</p> <h3 id=reason-2>Reason #2<a class=headerlink href=#reason-2 title="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> <h2 id=what-is-ingressclassname-field>What is ingressClassName field ?<a class=headerlink href=#what-is-ingressclassname-field title="Permanent link"></a></h2> <p><code>ingressClassName</code> is a field in the specs of an Ingress object.</p> <p><div class=highlight><pre><span></span><code>kubectl explain ingress.spec.ingressClassName
</code></pre></div> <div class=highlight><pre><span></span><code><span class=go>KIND: Ingress</span>
<span class=go>VERSION: networking.k8s.io/v1</span>
<span class=go>FIELD: ingressClassName &lt;string&gt;</span>
<span class=go>DESCRIPTION:</span>
<span class=go> IngressClassName is the name of the IngressClass cluster resource. The</span>
<span class=go> associated IngressClass defines which controller will implement the</span>
<span class=go> resource. This replaces the deprecated `kubernetes.io/ingress.class`</span>
<span class=go> annotation. For backwards compatibility, when that annotation is set, it</span>
<span class=go> must be given precedence over this field. The controller may emit a warning</span>
<span class=go> if the field and annotation have different values. Implementations of this</span>
<span class=go> API should ignore Ingresses without a class specified. An IngressClass</span>
<span class=go> resource may be marked as default, which can be used to set a default value</span>
<span class=go> for this field. For more information, refer to the IngressClass</span>
<span class=go> documentation.</span>
</code></pre></div></p> <p>The <code>.spec.ingressClassName</code> behavior has precedence over the deprecated <code>kubernetes.io/ingress.class</code> annotation.</p> <h2 id=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?<a class=headerlink href=#i-have-only-one-ingress-controller-in-my-cluster-what-should-i-do title="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 <a href=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 <a href=#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: <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></p> <p>And add the value <code>spec.ingressClassName=nginx</code> 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 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> <h3 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></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: <div class=highlight><pre><span></span><code>...
...
args:
- /nginx-ingress-controller
- --watch-ingress-without-class=true
- --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
...
...
</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> <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> <h2 id=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 ?<a class=headerlink href=#i-have-more-than-one-controller-running-in-my-cluster-and-i-want-to-use-the-new-api 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 <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> <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 message has been observed on use the deprecated annotation (<code>kubernetes.io/ingress.class</code>) in a Ingress resource manifest. It is recommended to use the <code>.spec.ingressClassName</code> field of the Ingress resource, to specify the name of the IngressClass of the Ingress you are defining.</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-nginx-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 the <a href=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; <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, install an additional instance of the ingress-NGINX controller like this: <div class=highlight><pre><span></span><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx \
--namespace ingress-nginx-2 \
--set controller.ingressClassResource.name=nginx-two \
--set controller.ingressClass=nginx-two \
--set controller.ingressClassResource.controllerValue=&quot;example.com/ingress-nginx-2&quot; \
--set controller.ingressClassResource.enabled=true \
--set controller.ingressClassByName=true
</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 &amp; 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: <div class=highlight><pre><span></span><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx \
--namespace kube-system \
--set controller.electionID=nginx-two-leader \
--set controller.ingressClassResource.name=nginx-two \
--set controller.ingressClass=nginx-two \
--set controller.ingressClassResource.controllerValue=&quot;example.com/ingress-nginx-2&quot; \
--set controller.ingressClassResource.enabled=true \
--set controller.ingressClassByName=true
</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> <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>
Reference in New Issue View Git Blame Copy Permalink