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/how-it-works/index.html

1286 lines
35 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">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="lang:clipboard.copy" content="Copy to clipboard">
<meta name="lang:clipboard.copied" content="Copied to clipboard">
<meta name="lang:search.language" content="en">
<meta name="lang:search.pipeline.stopwords" content="True">
<meta name="lang:search.pipeline.trimmer" content="True">
<meta name="lang:search.result.none" content="No matching documents">
<meta name="lang:search.result.one" content="1 matching document">
<meta name="lang:search.result.other" content="# matching documents">
<meta name="lang:search.tokenizer" content="[\s\-]+">
<link rel="shortcut icon" href="../assets/images/favicon.png">
<meta name="generator" content="mkdocs-0.17.5, mkdocs-material-2.9.4">
<title>How it works - NGINX Ingress Controller</title>
<link rel="stylesheet" href="../assets/stylesheets/application.451f80e5.css">
<link rel="stylesheet" href="../assets/stylesheets/application-palette.22915126.css">
<meta name="theme-color" content="#009688">
<script src="../assets/javascripts/modernizr.1aa3b519.js"></script>
<link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono">
<style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
<link rel="stylesheet" href="../assets/fonts/material-icons.css">
<link rel="stylesheet" href="../extra.css">
</head>
<body dir="ltr" data-md-color-primary="teal" data-md-color-accent="green">
<svg class="md-svg">
<defs>
<svg xmlns="http://www.w3.org/2000/svg" width="416" height="448"
viewBox="0 0 416 448" id="__github">
<path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19-18.125
8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19 18.125-8.5
18.125 8.5 10.75 19 3.125 20.5zM320 304q0 10-3.125 20.5t-10.75
19-18.125 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19
18.125-8.5 18.125 8.5 10.75 19 3.125 20.5zM360
304q0-30-17.25-51t-46.75-21q-10.25 0-48.75 5.25-17.75 2.75-39.25
2.75t-39.25-2.75q-38-5.25-48.75-5.25-29.5 0-46.75 21t-17.25 51q0 22 8
38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0
37.25-1.75t35-7.375 30.5-15 20.25-25.75 8-38.375zM416 260q0 51.75-15.25
82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5-41.75
1.125q-19.5 0-35.5-0.75t-36.875-3.125-38.125-7.5-34.25-12.875-30.25-20.25-21.5-28.75q-15.5-30.75-15.5-82.75
0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25
30.875q36.75-8.75 77.25-8.75 37 0 70 8 26.25-20.5
46.75-30.25t47.25-9.75q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34
99.5z" />
</svg>
</defs>
</svg>
<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" data-md-component="overlay" for="__drawer"></label>
<a href="#how-it-works" tabindex="1" class="md-skip">
Skip to content
</a>
<header class="md-header" data-md-component="header">
<nav class="md-header-nav md-grid">
<div class="md-flex">
<div class="md-flex__cell md-flex__cell--shrink">
<a href=".." title="NGINX Ingress Controller" class="md-header-nav__button md-logo">
<i class="md-icon">public</i>
</a>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
</div>
<div class="md-flex__cell md-flex__cell--stretch">
<div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
<span class="md-header-nav__topic">
NGINX Ingress Controller
</span>
<span class="md-header-nav__topic">
How it works
</span>
</div>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<label class="md-icon md-icon--search md-header-nav__button" for="__search"></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" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
<label class="md-icon md-search__icon" for="__search"></label>
<button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
&#xE5CD;
</button>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" data-md-scrollfix>
<div class="md-search-result" data-md-component="result">
<div class="md-search-result__meta">
Type to start searching
</div>
<ol class="md-search-result__list"></ol>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<div class="md-header-nav__source">
<a href="https://github.com/kubernetes/ingress-nginx/" title="Go to repository" class="md-source" data-md-source="github">
<div class="md-source__icon">
<svg viewBox="0 0 24 24" width="24" height="24">
<use xlink:href="#__github" width="24" height="24"></use>
</svg>
</div>
<div class="md-source__repository">
kubernetes/ingress-nginx
</div>
</a>
</div>
</div>
</div>
</nav>
</header>
<div class="md-container">
<nav class="md-tabs" data-md-component="tabs">
<div class="md-tabs__inner md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href=".." title="Welcome" class="md-tabs__link md-tabs__link--active">
Welcome
</a>
</li>
<li class="md-tabs__item">
<a href="../deploy/" title="Deployment" class="md-tabs__link">
Deployment
</a>
</li>
<li class="md-tabs__item">
<a href="../user-guide/nginx-configuration/" title="User guide" class="md-tabs__link">
User guide
</a>
</li>
<li class="md-tabs__item">
<a href="../examples/" title="Examples" class="md-tabs__link">
Examples
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main">
<div class="md-main__inner md-grid" data-md-component="container">
<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" data-md-level="0">
<label class="md-nav__title md-nav__title--site" for="__drawer">
<a href=".." title="NGINX Ingress Controller" class="md-nav__button md-logo">
<i class="md-icon">public</i>
</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" data-md-source="github">
<div class="md-source__icon">
<svg viewBox="0 0 24 24" width="24" height="24">
<use xlink:href="#__github" width="24" height="24"></use>
</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">
<a href=".." title="Welcome" class="md-nav__link">
Welcome
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-2" type="checkbox" id="nav-2">
<label class="md-nav__link" for="nav-2">
Deployment
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
<label class="md-nav__title" for="nav-2">
Deployment
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../deploy/" title="Installation Guide" class="md-nav__link">
Installation Guide
</a>
</li>
<li class="md-nav__item">
<a href="../deploy/rbac/" title="Role Based Access Control (RBAC)" class="md-nav__link">
Role Based Access Control (RBAC)
</a>
</li>
<li class="md-nav__item">
<a href="../deploy/upgrade/" title="Upgrading" class="md-nav__link">
Upgrading
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-3" type="checkbox" id="nav-3">
<label class="md-nav__link" for="nav-3">
User guide
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
<label class="md-nav__title" for="nav-3">
User guide
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-3-1" type="checkbox" id="nav-3-1">
<label class="md-nav__link" for="nav-3-1">
NGINX Configuration
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
<label class="md-nav__title" for="nav-3-1">
NGINX Configuration
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../user-guide/nginx-configuration/" title="NGINX Configuration" class="md-nav__link">
NGINX Configuration
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/nginx-configuration/annotations/" title="Annotations" class="md-nav__link">
Annotations
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/nginx-configuration/configmap/" title="ConfigMaps" class="md-nav__link">
ConfigMaps
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/nginx-configuration/custom-template/" title="Custom NGINX template" class="md-nav__link">
Custom NGINX template
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/nginx-configuration/log-format/" title="Log format" class="md-nav__link">
Log format
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../user-guide/cli-arguments/" title="Command line arguments" class="md-nav__link">
Command line arguments
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/custom-errors/" title="Custom errors" class="md-nav__link">
Custom errors
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/default-backend/" title="Default backend" class="md-nav__link">
Default backend
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/exposing-tcp-udp-services/" title="Exposing TCP and UDP services" class="md-nav__link">
Exposing TCP and UDP services
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/external-articles/" title="External Articles" class="md-nav__link">
External Articles
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/miscellaneous/" title="Miscellaneous" class="md-nav__link">
Miscellaneous
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/multiple-ingress/" title="Multiple Ingress controllers" class="md-nav__link">
Multiple Ingress controllers
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/tls/" title="TLS/HTTPS" class="md-nav__link">
TLS/HTTPS
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-3-10" type="checkbox" id="nav-3-10">
<label class="md-nav__link" for="nav-3-10">
Third party addons
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
<label class="md-nav__title" for="nav-3-10">
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/" title="ModSecurity Web Application Firewall" class="md-nav__link">
ModSecurity Web Application Firewall
</a>
</li>
<li class="md-nav__item">
<a href="../user-guide/third-party-addons/opentracing/" title="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-toggle md-nav__toggle" data-md-toggle="nav-4" type="checkbox" id="nav-4">
<label class="md-nav__link" for="nav-4">
Examples
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
<label class="md-nav__title" for="nav-4">
Examples
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../examples/" title="Ingress examples" class="md-nav__link">
Ingress examples
</a>
</li>
<li class="md-nav__item">
<a href="../examples/PREREQUISITES/" title="Prerequisites" class="md-nav__link">
Prerequisites
</a>
</li>
<li class="md-nav__item">
<a href="../examples/affinity/cookie/README/" title="Sticky Session" class="md-nav__link">
Sticky Session
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-4-4" type="checkbox" id="nav-4-4">
<label class="md-nav__link" for="nav-4-4">
Auth
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
<label class="md-nav__title" for="nav-4-4">
Auth
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../examples/auth/basic/README/" title="Basic Authentication" class="md-nav__link">
Basic Authentication
</a>
</li>
<li class="md-nav__item">
<a href="../examples/auth/client-certs/README/" title="Client Certificate Authentication" class="md-nav__link">
Client Certificate Authentication
</a>
</li>
<li class="md-nav__item">
<a href="../examples/auth/external-auth/README/" title="External authentication" class="md-nav__link">
External authentication
</a>
</li>
<li class="md-nav__item">
<a href="../examples/auth/oauth-external-auth/README/" title="External Authentication" class="md-nav__link">
External Authentication
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-4-5" type="checkbox" id="nav-4-5">
<label class="md-nav__link" for="nav-4-5">
Customization
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
<label class="md-nav__title" for="nav-4-5">
Customization
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../examples/customization/configuration-snippets/README/" title="Configuration Snippets" class="md-nav__link">
Configuration Snippets
</a>
</li>
<li class="md-nav__item">
<a href="../examples/customization/custom-configuration/README/" title="Custom Configuration" class="md-nav__link">
Custom Configuration
</a>
</li>
<li class="md-nav__item">
<a href="../examples/customization/custom-errors/README/" title="Custom Errors" class="md-nav__link">
Custom Errors
</a>
</li>
<li class="md-nav__item">
<a href="../examples/customization/custom-headers/README/" title="Custom Headers" class="md-nav__link">
Custom Headers
</a>
</li>
<li class="md-nav__item">
<a href="../examples/customization/custom-upstream-check/README/" title="Custom Upstream server checks" class="md-nav__link">
Custom Upstream server checks
</a>
</li>
<li class="md-nav__item">
<a href="../examples/customization/external-auth-headers/README/" title="External authentication, authentication service response headers propagation" class="md-nav__link">
External authentication, authentication service response headers propagation
</a>
</li>
<li class="md-nav__item">
<a href="../examples/customization/ssl-dh-param/README/" title="Custom DH parameters for perfect forward secrecy" class="md-nav__link">
Custom DH parameters for perfect forward secrecy
</a>
</li>
<li class="md-nav__item">
<a href="../examples/customization/sysctl/README/" title="Sysctl tuning" class="md-nav__link">
Sysctl tuning
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../examples/docker-registry/README/" title="Docker registry" class="md-nav__link">
Docker registry
</a>
</li>
<li class="md-nav__item">
<a href="../examples/grpc/README/" title="gRPC" class="md-nav__link">
gRPC
</a>
</li>
<li class="md-nav__item">
<a href="../examples/multi-tls/README/" title="Multi TLS certificate termination" class="md-nav__link">
Multi TLS certificate termination
</a>
</li>
<li class="md-nav__item">
<a href="../examples/rewrite/README/" title="Rewrite" class="md-nav__link">
Rewrite
</a>
</li>
<li class="md-nav__item">
<a href="../examples/static-ip/README/" title="Static IPs" class="md-nav__link">
Static IPs
</a>
</li>
<li class="md-nav__item">
<a href="../examples/tls-termination/README/" title="TLS termination" class="md-nav__link">
TLS termination
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../development/" title="Developing for NGINX Ingress Controller" class="md-nav__link">
Developing for NGINX Ingress Controller
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
How it works
</label>
<a href="./" title="How it works" class="md-nav__link md-nav__link--active">
How it works
</a>
<nav class="md-nav md-nav--secondary">
<label class="md-nav__title" for="__toc">Table of contents</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="#nginx-configuration" title="NGINX configuration" class="md-nav__link">
NGINX configuration
</a>
</li>
<li class="md-nav__item">
<a href="#nginx-model" title="NGINX model" class="md-nav__link">
NGINX model
</a>
</li>
<li class="md-nav__item">
<a href="#building-the-nginx-model" title="Building the NGINX model" class="md-nav__link">
Building the NGINX model
</a>
</li>
<li class="md-nav__item">
<a href="#when-a-reload-is-required" title="When a reload is required" class="md-nav__link">
When a reload is required
</a>
</li>
<li class="md-nav__item">
<a href="#avoiding-reloads" title="Avoiding reloads" class="md-nav__link">
Avoiding reloads
</a>
<nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#avoiding-reloads-on-endpoints-changes" title="Avoiding reloads on Endpoints changes" class="md-nav__link">
Avoiding reloads on Endpoints changes
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../troubleshooting/" title="Debug & Troubleshooting" class="md-nav__link">
Debug & Troubleshooting
</a>
</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">
<label class="md-nav__title" for="__toc">Table of contents</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="#nginx-configuration" title="NGINX configuration" class="md-nav__link">
NGINX configuration
</a>
</li>
<li class="md-nav__item">
<a href="#nginx-model" title="NGINX model" class="md-nav__link">
NGINX model
</a>
</li>
<li class="md-nav__item">
<a href="#building-the-nginx-model" title="Building the NGINX model" class="md-nav__link">
Building the NGINX model
</a>
</li>
<li class="md-nav__item">
<a href="#when-a-reload-is-required" title="When a reload is required" class="md-nav__link">
When a reload is required
</a>
</li>
<li class="md-nav__item">
<a href="#avoiding-reloads" title="Avoiding reloads" class="md-nav__link">
Avoiding reloads
</a>
<nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#avoiding-reloads-on-endpoints-changes" title="Avoiding reloads on Endpoints changes" class="md-nav__link">
Avoiding reloads on Endpoints changes
</a>
</li>
</ul>
</nav>
</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/how-it-works.md" title="Edit this page" class="md-icon md-content__icon">&#xE3C9;</a>
<h1 id="how-it-works">How it works<a class="headerlink" href="#how-it-works" title="Permanent link">&para;</a></h1>
<p>The objective of this document is to explain how the NGINX Ingress controller works, in particular how the NGINX model is built and why we need one.</p>
<h2 id="nginx-configuration">NGINX configuration<a class="headerlink" href="#nginx-configuration" title="Permanent link">&para;</a></h2>
<p>The goal of this Ingress controller is the assembly of a configuration file (nginx.conf). The main implication of this requirement is the need to reload NGINX after any change in the configuration file. <em>Though it is important to note that we don't reload Nginx on changes that impact only an <code class="codehilite">upstream</code> configuration (i.e Endpoints change when you deploy your app)</em>. We use https://github.com/openresty/lua-nginx-module to achieve this. Check <a href="#avoiding-reloads-on-endpoints-changes">below</a> to learn more about how it's done.</p>
<h2 id="nginx-model">NGINX model<a class="headerlink" href="#nginx-model" title="Permanent link">&para;</a></h2>
<p>Usually, a Kubernetes Controller utilizes the <a href="../1">synchronization loop pattern</a> to check if the desired state in the controller is updated or a change is required. To this purpose, we need to build a model using different objects from the cluster, in particular (in no special order) Ingresses, Services, Endpoints, Secrets, and Configmaps to generate a point in time configuration file that reflects the state of the cluster.</p>
<p>To get this object from the cluster, we use <a href="../2">Kubernetes Informers</a>, in particular, <code class="codehilite">FilteredSharedInformer</code>. This informers allows reacting to changes in using <a href="../3">callbacks</a> to individual changes when a new object is added, modified or removed. Unfortunately, there is no way to know if a particular change is going to affect the final configuration file. Therefore on every change, we have to rebuild a new model from scratch based on the state of cluster and compare it to the current model. If the new model equals to the current one, then we avoid generating a new NGINX configuration and triggering a reload. Otherwise, we check if the difference is only about Endpoints. If so we then send the new list of Endpoints to a Lua handler running inside Nginx using HTTP POST request and again avoid generating a new NGINX configuration and triggering a reload. If the difference between running and new model is about more than just Endpoints we create a new NGINX configuration based on the new model, replace the current model and trigger a reload.</p>
<p>One of the uses of the model is to avoid unnecessary reloads when there's no change in the state and to detect conflicts in definitions.</p>
<p>The final representation of the NGINX configuration is generated from a <a href="../6">Go template</a> using the new model as input for the variables required by the template.</p>
<h2 id="building-the-nginx-model">Building the NGINX model<a class="headerlink" href="#building-the-nginx-model" title="Permanent link">&para;</a></h2>
<p>Building a model is an expensive operation, for this reason, the use of the synchronization loop is a must. By using a <a href="../4">work queue</a> it is possible to not lose changes and remove the use of <a href="../5">sync.Mutex</a> to force a single execution of the sync loop and additionally it is possible to create a time window between the start and end of the sync loop that allows us to discard unnecessary updates. It is important to understand that any change in the cluster could generate events that the informer will send to the controller and one of the reasons for the <a href="../4">work queue</a>.</p>
<p>Operations to build the model:</p>
<ul>
<li>Order Ingress rules by <code class="codehilite">ResourceVersion</code> field, i.e., old rules first.</li>
<li>If the same path for the same host is defined in more than one Ingress, the oldest rule wins.</li>
<li>If more than one Ingress contains a TLS section for the same host, the oldest rule wins.</li>
<li>
<p>If multiple Ingresses define an annotation that affects the configuration of the Server block, the oldest rule wins.</p>
</li>
<li>
<p>Create a list of NGINX Servers (per hostname)</p>
</li>
<li>Create a list of NGINX Upstreams</li>
<li>If multiple Ingresses define different paths for the same host, the ingress controller will merge the definitions.</li>
<li>Annotations are applied to all the paths in the Ingress.</li>
<li>Multiple Ingresses can define different annotations. These definitions are not shared between Ingresses.</li>
</ul>
<h2 id="when-a-reload-is-required">When a reload is required<a class="headerlink" href="#when-a-reload-is-required" title="Permanent link">&para;</a></h2>
<p>The next list describes the scenarios when a reload is required:</p>
<ul>
<li>New Ingress Resource Created.</li>
<li>TLS section is added to existing Ingress.</li>
<li>Change in Ingress annotations that impacts more than just upstream configuration. For instance <code class="codehilite">load-balance</code> annotation does not require a reload.</li>
<li>A path is added/removed from an Ingress.</li>
<li>An Ingress, Service, Secret is removed.</li>
<li>Some missing referenced object from the Ingress is available, like a Service or Secret.</li>
<li>A Secret is updated.</li>
</ul>
<h2 id="avoiding-reloads">Avoiding reloads<a class="headerlink" href="#avoiding-reloads" title="Permanent link">&para;</a></h2>
<p>In some cases, it is possible to avoid reloads, in particular when there is a change in the endpoints, i.e., a pod is started or replaced. It is out of the scope of this Ingress controller to remove reloads completely. This would require an incredible amount of work and at some point makes no sense. This can change only if NGINX changes the way new configurations are read, basically, new changes do not replace worker processes.</p>
<h3 id="avoiding-reloads-on-endpoints-changes">Avoiding reloads on Endpoints changes<a class="headerlink" href="#avoiding-reloads-on-endpoints-changes" title="Permanent link">&para;</a></h3>
<p>On every endpoint change the controller fetches endpoints from all the services it sees and generates corresponding Backend objects. It then sends these objects to a Lua handler running inside Nginx. The Lua code in turn stores those backends in a shared memory zone. Then for every request Lua code running in <a href="https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md"><code class="codehilite">balancer_by_lua</code></a> context detects what endpoints it should choose upstream peer from and applies the configured load balancing algorithm to choose the peer. Then Nginx takes care of the rest. This way we avoid reloading Nginx on endpoint changes. <em>Note</em> that this includes annotation changes that affects only <code class="codehilite">upstream</code> configuration in Nginx as well.</p>
<p>In a relatively big clusters with frequently deploying apps this feature saves significant number of Nginx reloads which can otherwise affect response latency, load balancing quality (after every reload Nginx resets the state of load balancing) and so on.</p>
</article>
</div>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-nav">
<nav class="md-footer-nav__inner md-grid">
<a href="../development/" title="Developing for NGINX Ingress Controller" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
<div class="md-flex__cell md-flex__cell--shrink">
<i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
</div>
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
<span class="md-flex__ellipsis">
<span class="md-footer-nav__direction">
Previous
</span>
Developing for NGINX Ingress Controller
</span>
</div>
</a>
<a href="../troubleshooting/" title="Debug & Troubleshooting" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
<span class="md-flex__ellipsis">
<span class="md-footer-nav__direction">
Next
</span>
Debug & Troubleshooting
</span>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
</div>
</a>
</nav>
</div>
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-footer-copyright">
powered by
<a href="https://www.mkdocs.org">MkDocs</a>
and
<a href="https://squidfunk.github.io/mkdocs-material/">
Material for MkDocs</a>
</div>
</div>
</div>
</footer>
</div>
<script src="../assets/javascripts/application.30f6b8b1.js"></script>
<script>app.initialize({version:"0.17.5",url:{base:".."}})</script>
<script>!function(e,a,t,n,o,c,i){e.GoogleAnalyticsObject=o,e.ga=e.ga||function(){(e.ga.q=e.ga.q||[]).push(arguments)},e.ga.l=1*new Date,c=a.createElement(t),i=a.getElementsByTagName(t)[0],c.async=1,c.src="https://www.google-analytics.com/analytics.js",i.parentNode.insertBefore(c,i)}(window,document,"script",0,"ga"),ga("create","UA-118407822-1","kubernetes.github.io"),ga("set","anonymizeIp",!0),ga("send","pageview");var links=document.getElementsByTagName("a");if(Array.prototype.map.call(links,function(e){e.host!=document.location.host&&e.addEventListener("click",function(){var a=e.getAttribute("data-md-action")||"follow";ga("send","event","outbound",a,e.href)})}),document.forms.search){var query=document.forms.search.query;query.addEventListener("blur",function(){if(this.value){var e=document.location.pathname;ga("send","pageview",e+"?q="+this.value)}})}</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink