DevFW-CICD/ingress-nginx-helm
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Deploy GitHub Pages

Browse source
This commit is contained in:
Travis Bot 2020-02-09 23:53:05 +00:00
parent ec2af1dbc3
commit 006cda8fee
62 changed files with 1885 additions and 1843 deletions
Download patch file Download diff file Expand all files Collapse all files

33
how-it-works/index.html
View file

@ -34,7 +34,7 @@
<meta name="lang:search.tokenizer" content="[\s\-]+">
<link rel="shortcut icon" href="../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.4.3">
<meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.6.2">
@ -42,7 +42,7 @@
<link rel="stylesheet" href="../assets/stylesheets/application.30686662.css">
<link rel="stylesheet" href="../assets/stylesheets/application.adb8469c.css">
<link rel="stylesheet" href="../assets/stylesheets/application-palette.a8b3c06d.css">
@ -53,12 +53,12 @@
<script src="../assets/javascripts/modernizr.74668098.js"></script>
<script src="../assets/javascripts/modernizr.86422ebf.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&display=fallback">
<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","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
@ -114,7 +114,7 @@
<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">
<a href="#how-it-works" tabindex="0" class="md-skip">
Skip to content
</a>
@ -123,7 +123,7 @@
<nav class="md-header-nav md-grid">
<div class="md-flex">
<div class="md-flex__cell md-flex__cell--shrink">
<a href="https://kubernetes.github.io/ingress-nginx" title="NGINX Ingress Controller" class="md-header-nav__button md-logo">
<a href="https://kubernetes.github.io/ingress-nginx" title="NGINX Ingress Controller" aria-label="NGINX Ingress Controller" class="md-header-nav__button md-logo">
<i class="md-icon">public</i>
@ -154,7 +154,7 @@
<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">
<input type="text" class="md-search__input" aria-label="search" 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;
@ -1292,10 +1292,10 @@
<h1 id="how-it-works">How it works<a class="headerlink" href="#how-it-works" title="Permanent link"></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"></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 <a href="https://github.com/openresty/lua-nginx-module">lua-nginx-module</a> to achieve this. Check <a href="#avoiding-reloads-on-endpoints-changes">below</a> to learn more about how it's done.</p>
<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"><span class="err">upstream</span></code> configuration (i.e Endpoints change when you deploy your app)</em>. We use <a href="https://github.com/openresty/lua-nginx-module">lua-nginx-module</a> 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"></a></h2>
<p>Usually, a Kubernetes Controller utilizes the <a href="https://coreos.com/kubernetes/docs/latest/replication-controller.html#the-reconciliation-loop-in-detail">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="https://godoc.org/k8s.io/client-go/informers#NewFilteredSharedInformerFactory">Kubernetes Informers</a>, in particular, <code class="codehilite">FilteredSharedInformer</code>. This informers allows reacting to changes in using <a href="https://godoc.org/k8s.io/client-go/tools/cache#ResourceEventHandlerFuncs">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>To get this object from the cluster, we use <a href="https://godoc.org/k8s.io/client-go/informers#NewFilteredSharedInformerFactory">Kubernetes Informers</a>, in particular, <code class="codehilite"><span class="err">FilteredSharedInformer</span></code>. This informers allows reacting to changes in using <a href="https://godoc.org/k8s.io/client-go/tools/cache#ResourceEventHandlerFuncs">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="https://github.com/kubernetes/ingress-nginx/blob/master/rootfs/etc/nginx/template/nginx.tmpl">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"></a></h2>
@ -1303,7 +1303,7 @@
<p>Operations to build the model:</p>
<ul>
<li>
<p>Order Ingress rules by <code class="codehilite">CreationTimestamp</code> field, i.e., old rules first.</p>
<p>Order Ingress rules by <code class="codehilite"><span class="err">CreationTimestamp</span></code> field, i.e., old rules first.</p>
</li>
<li>
<p>If the same path for the same host is defined in more than one Ingress, the oldest rule wins.</p>
@ -1325,7 +1325,7 @@
<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>Change in Ingress annotations that impacts more than just upstream configuration. For instance <code class="codehilite"><span class="err">load-balance</span></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>
@ -1334,15 +1334,16 @@
<h2 id="avoiding-reloads">Avoiding reloads<a class="headerlink" href="#avoiding-reloads" title="Permanent link"></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"></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>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"><span class="err">balancer_by_lua</span></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"><span class="err">upstream</span></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>
<h3 id="avoiding-outage-from-wrong-configuration">Avoiding outage from wrong configuration<a class="headerlink" href="#avoiding-outage-from-wrong-configuration" title="Permanent link"></a></h3>
<p>Because the ingress controller works using the <a href="https://coreos.com/kubernetes/docs/latest/replication-controller.html#the-reconciliation-loop-in-detail">synchronization loop pattern</a>, it is applying the configuration for all matching objects. In case some Ingress objects have a broken configuration, for example a syntax error in the <code class="codehilite">nginx.ingress.kubernetes.io/configuration-snippet</code> annotation, the generated configuration becomes invalid, does not reload and hence no more ingresses will be taken into account.</p>
<p>Because the ingress controller works using the <a href="https://coreos.com/kubernetes/docs/latest/replication-controller.html#the-reconciliation-loop-in-detail">synchronization loop pattern</a>, it is applying the configuration for all matching objects. In case some Ingress objects have a broken configuration, for example a syntax error in the <code class="codehilite"><span class="err">nginx.ingress.kubernetes.io/configuration-snippet</span></code> annotation, the generated configuration becomes invalid, does not reload and hence no more ingresses will be taken into account.</p>
<p>To prevent this situation to happen, the nginx ingress controller optionally exposes a <a href="https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook">validating admission webhook server</a> to ensure the validity of incoming ingress objects.
This webhook appends the incoming ingress objects to the list of ingresses, generates the configuration and calls nginx to ensure the configuration has no syntax errors.</p>
@ -1397,9 +1398,9 @@ This webhook appends the incoming ingress objects to the list of ingresses, gene
<div class="md-footer-copyright">
powered by
<a href="https://www.mkdocs.org">MkDocs</a>
<a href="https://www.mkdocs.org" target="_blank" rel="noopener">MkDocs</a>
and
<a href="https://squidfunk.github.io/mkdocs-material/">
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs</a>
</div>
@ -1409,7 +1410,7 @@ This webhook appends the incoming ingress objects to the list of ingresses, gene
</div>
<script src="../assets/javascripts/application.ac79c3b0.js"></script>
<script src="../assets/javascripts/application.c33a9706.js"></script>
<script>app.initialize({version:"1.0.4",url:{base:".."}})</script>