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

91 lines
38 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 Kubernetess 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. Its 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 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 messsage 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.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> </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