Deploy GitHub Pages

This commit is contained in:
Travis Bot 2018-09-13 23:54:10 +00:00
parent b3d5b69555
commit ca7aeec8ab
51 changed files with 5886 additions and 6747 deletions

View file

@ -32,7 +32,7 @@
<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">
<meta name="generator" content="mkdocs-1.0.4, mkdocs-material-3.0.4">
@ -54,8 +54,8 @@
<script src="../assets/javascripts/modernizr.1aa3b519.js"></script>
<link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
<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>
@ -100,7 +100,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="1" class="md-skip">
Skip to content
</a>
@ -198,18 +198,23 @@
<nav class="md-tabs" data-md-component="tabs">
<nav class="md-tabs md-tabs--active" 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=".." title="Welcome" class="md-tabs__link md-tabs__link--active">
Welcome
</a>
</li>
@ -257,12 +262,6 @@
</ul>
</div>
</nav>
@ -312,6 +311,27 @@
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-1" type="checkbox" id="nav-1" checked>
<label class="md-nav__link" for="nav-1">
Welcome
</label>
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
<label class="md-nav__title" for="nav-1">
Welcome
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." title="Welcome" class="md-nav__link">
@ -319,6 +339,126 @@
</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="Troubleshooting" class="md-nav__link">
Troubleshooting
</a>
</li>
<li class="md-nav__item">
<a href="../development/" title="Development" class="md-nav__link">
Development
</a>
</li>
</ul>
</nav>
</li>
@ -381,8 +521,8 @@
<li class="md-nav__item">
<a href="../deploy/upgrade/" title="Upgrading" class="md-nav__link">
Upgrading
<a href="../deploy/upgrade/" title="Upgrade" class="md-nav__link">
Upgrade
</a>
</li>
@ -436,8 +576,8 @@
<li class="md-nav__item">
<a href="../user-guide/nginx-configuration/" title="NGINX Configuration" class="md-nav__link">
NGINX Configuration
<a href="../user-guide/nginx-configuration/" title="Introduction" class="md-nav__link">
Introduction
</a>
</li>
@ -460,8 +600,8 @@
<li class="md-nav__item">
<a href="../user-guide/nginx-configuration/configmap/" title="ConfigMaps" class="md-nav__link">
ConfigMaps
<a href="../user-guide/nginx-configuration/configmap/" title="ConfigMap" class="md-nav__link">
ConfigMap
</a>
</li>
@ -681,8 +821,8 @@
<li class="md-nav__item">
<a href="../examples/" title="Ingress examples" class="md-nav__link">
Ingress examples
<a href="../examples/" title="Introduction" class="md-nav__link">
Introduction
</a>
</li>
@ -705,8 +845,8 @@
<li class="md-nav__item">
<a href="../examples/affinity/cookie/README/" title="Sticky Session" class="md-nav__link">
Sticky Session
<a href="../examples/affinity/cookie/" title="Sticky Sessions" class="md-nav__link">
Sticky Sessions
</a>
</li>
@ -736,7 +876,7 @@
<li class="md-nav__item">
<a href="../examples/auth/basic/README/" title="Basic Authentication" class="md-nav__link">
<a href="../examples/auth/basic/" title="Basic Authentication" class="md-nav__link">
Basic Authentication
</a>
</li>
@ -748,7 +888,7 @@
<li class="md-nav__item">
<a href="../examples/auth/client-certs/README/" title="Client Certificate Authentication" class="md-nav__link">
<a href="../examples/auth/client-certs/" title="Client Certificate Authentication" class="md-nav__link">
Client Certificate Authentication
</a>
</li>
@ -760,7 +900,7 @@
<li class="md-nav__item">
<a href="../examples/auth/external-auth/README/" title="External Basic Authentication" class="md-nav__link">
<a href="../examples/auth/external-auth/" title="External Basic Authentication" class="md-nav__link">
External Basic Authentication
</a>
</li>
@ -772,7 +912,7 @@
<li class="md-nav__item">
<a href="../examples/auth/oauth-external-auth/README/" title="External OAUTH Authentication" class="md-nav__link">
<a href="../examples/auth/oauth-external-auth/" title="External OAUTH Authentication" class="md-nav__link">
External OAUTH Authentication
</a>
</li>
@ -808,7 +948,7 @@
<li class="md-nav__item">
<a href="../examples/customization/configuration-snippets/README/" title="Configuration Snippets" class="md-nav__link">
<a href="../examples/customization/configuration-snippets/" title="Configuration Snippets" class="md-nav__link">
Configuration Snippets
</a>
</li>
@ -820,7 +960,7 @@
<li class="md-nav__item">
<a href="../examples/customization/custom-configuration/README/" title="Custom Configuration" class="md-nav__link">
<a href="../examples/customization/custom-configuration/" title="Custom Configuration" class="md-nav__link">
Custom Configuration
</a>
</li>
@ -832,7 +972,7 @@
<li class="md-nav__item">
<a href="../examples/customization/custom-errors/README/" title="Custom Errors" class="md-nav__link">
<a href="../examples/customization/custom-errors/" title="Custom Errors" class="md-nav__link">
Custom Errors
</a>
</li>
@ -844,7 +984,7 @@
<li class="md-nav__item">
<a href="../examples/customization/custom-headers/README/" title="Custom Headers" class="md-nav__link">
<a href="../examples/customization/custom-headers/" title="Custom Headers" class="md-nav__link">
Custom Headers
</a>
</li>
@ -856,7 +996,7 @@
<li class="md-nav__item">
<a href="../examples/customization/custom-upstream-check/README/" title="Custom Upstream server checks" class="md-nav__link">
<a href="../examples/customization/custom-upstream-check/" title="Custom Upstream server checks" class="md-nav__link">
Custom Upstream server checks
</a>
</li>
@ -868,8 +1008,8 @@
<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 href="../examples/customization/external-auth-headers/" title="External authentication" class="md-nav__link">
External authentication
</a>
</li>
@ -880,7 +1020,7 @@
<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">
<a href="../examples/customization/ssl-dh-param/" title="Custom DH parameters for perfect forward secrecy" class="md-nav__link">
Custom DH parameters for perfect forward secrecy
</a>
</li>
@ -892,7 +1032,7 @@
<li class="md-nav__item">
<a href="../examples/customization/sysctl/README/" title="Sysctl tuning" class="md-nav__link">
<a href="../examples/customization/sysctl/" title="Sysctl tuning" class="md-nav__link">
Sysctl tuning
</a>
</li>
@ -909,7 +1049,7 @@
<li class="md-nav__item">
<a href="../examples/docker-registry/README/" title="Docker registry" class="md-nav__link">
<a href="../examples/docker-registry/" title="Docker registry" class="md-nav__link">
Docker registry
</a>
</li>
@ -921,7 +1061,7 @@
<li class="md-nav__item">
<a href="../examples/grpc/README/" title="gRPC" class="md-nav__link">
<a href="../examples/grpc/" title="gRPC" class="md-nav__link">
gRPC
</a>
</li>
@ -933,7 +1073,7 @@
<li class="md-nav__item">
<a href="../examples/multi-tls/README/" title="Multi TLS certificate termination" class="md-nav__link">
<a href="../examples/multi-tls/" title="Multi TLS certificate termination" class="md-nav__link">
Multi TLS certificate termination
</a>
</li>
@ -945,7 +1085,7 @@
<li class="md-nav__item">
<a href="../examples/rewrite/README/" title="Rewrite" class="md-nav__link">
<a href="../examples/rewrite/" title="Rewrite" class="md-nav__link">
Rewrite
</a>
</li>
@ -957,7 +1097,7 @@
<li class="md-nav__item">
<a href="../examples/static-ip/README/" title="Static IPs" class="md-nav__link">
<a href="../examples/static-ip/" title="Static IPs" class="md-nav__link">
Static IPs
</a>
</li>
@ -969,7 +1109,7 @@
<li class="md-nav__item">
<a href="../examples/tls-termination/README/" title="TLS termination" class="md-nav__link">
<a href="../examples/tls-termination/" title="TLS termination" class="md-nav__link">
TLS termination
</a>
</li>
@ -980,121 +1120,6 @@
</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="Troubleshooting" class="md-nav__link">
Troubleshooting
</a>
</li>
</ul>
</nav>
</div>
@ -1187,12 +1212,12 @@
<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>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>
<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>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>
@ -1245,7 +1270,7 @@
<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">
<a href=".." title="Welcome" 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>
@ -1254,7 +1279,7 @@
<span class="md-footer-nav__direction">
Previous
</span>
Developing for NGINX Ingress Controller
Welcome
</span>
</div>
</a>
@ -1296,9 +1321,9 @@
</div>
<script src="../assets/javascripts/application.30f6b8b1.js"></script>
<script src="../assets/javascripts/application.583bbe55.js"></script>
<script>app.initialize({version:"0.17.5",url:{base:".."}})</script>
<script>app.initialize({version:"1.0.4",url:{base:".."}})</script>