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 2018-10-12 01:21:45 +00:00
parent 8125e59d3f
commit c09357b854
51 changed files with 612 additions and 5095 deletions
Download patch file Download diff file Expand all files Collapse all files

199
user-guide/nginx-configuration/annotations/index.html
View file

@ -569,13 +569,6 @@
Authentication
</a>
</li>
<li class="md-nav__item">
<a href="#custom-nginx-upstream-checks" title="Custom NGINX upstream checks" class="md-nav__link">
Custom NGINX upstream checks
</a>
</li>
<li class="md-nav__item">
@ -681,13 +674,6 @@
SSL Passthrough
</a>
</li>
<li class="md-nav__item">
<a href="#secure-backends-deprecated-since-0180" title="Secure backends DEPRECATED (since 0.18.0)" class="md-nav__link">
Secure backends DEPRECATED (since 0.18.0)
</a>
</li>
<li class="md-nav__item">
@ -813,13 +799,6 @@
Lua Resty WAF
</a>
</li>
<li class="md-nav__item">
<a href="#grpc-backend-deprecated-since-0180" title="gRPC backend DEPRECATED (since 0.18.0)" class="md-nav__link">
gRPC backend DEPRECATED (since 0.18.0)
</a>
</li>
<li class="md-nav__item">
@ -937,8 +916,8 @@
<li class="md-nav__item">
<a href="../../exposing-tcp-udp-services/" title="Exposing TCP and UDP services" class="md-nav__link">
Exposing TCP and UDP services
<a href="../../ingress-path-matching/" title="Regular expressions in paths" class="md-nav__link">
Regular expressions in paths
</a>
</li>
@ -1255,18 +1234,6 @@
<li class="md-nav__item">
<a href="../../../examples/customization/custom-upstream-check/" 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/" title="External authentication" class="md-nav__link">
External authentication
@ -1432,13 +1399,6 @@
Authentication
</a>
</li>
<li class="md-nav__item">
<a href="#custom-nginx-upstream-checks" title="Custom NGINX upstream checks" class="md-nav__link">
Custom NGINX upstream checks
</a>
</li>
<li class="md-nav__item">
@ -1544,13 +1504,6 @@
SSL Passthrough
</a>
</li>
<li class="md-nav__item">
<a href="#secure-backends-deprecated-since-0180" title="Secure backends DEPRECATED (since 0.18.0)" class="md-nav__link">
Secure backends DEPRECATED (since 0.18.0)
</a>
</li>
<li class="md-nav__item">
@ -1676,13 +1629,6 @@
Lua Resty WAF
</a>
</li>
<li class="md-nav__item">
<a href="#grpc-backend-deprecated-since-0180" title="gRPC backend DEPRECATED (since 0.18.0)" class="md-nav__link">
gRPC backend DEPRECATED (since 0.18.0)
</a>
</li>
<li class="md-nav__item">
@ -1849,10 +1795,6 @@ table below.</p>
<td>"true" or "false"</td>
</tr>
<tr>
<td><a href="#grpc-backend">nginx.ingress.kubernetes.io/grpc-backend</a></td>
<td>"true" or "false"</td>
</tr>
<tr>
<td><a href="#rate-limiting">nginx.ingress.kubernetes.io/limit-connections</a></td>
<td>number</td>
</tr>
@ -1921,10 +1863,6 @@ table below.</p>
<td>URI</td>
</tr>
<tr>
<td><a href="#secure-backends">nginx.ingress.kubernetes.io/secure-backends</a></td>
<td>"true" or "false"</td>
</tr>
<tr>
<td><a href="#secure-backends">nginx.ingress.kubernetes.io/secure-verify-ca-secret</a></td>
<td>string</td>
</tr>
@ -1957,14 +1895,6 @@ table below.</p>
<td>"true" or "false"</td>
</tr>
<tr>
<td><a href="#custom-nginx-upstream-checks">nginx.ingress.kubernetes.io/upstream-max-fails</a></td>
<td>number</td>
</tr>
<tr>
<td><a href="#custom-nginx-upstream-checks">nginx.ingress.kubernetes.io/upstream-fail-timeout</a></td>
<td>number</td>
</tr>
<tr>
<td><a href="#custom-nginx-upstream-hashing">nginx.ingress.kubernetes.io/upstream-hash-by</a></td>
<td>string</td>
</tr>
@ -2073,43 +2003,21 @@ So, at reload, if upstream servers have changed, index values are not guaranteed
<h3 id="authentication">Authentication<a class="headerlink" href="#authentication" title="Permanent link">&para;</a></h3>
<p>Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key <code class="codehilite">auth</code>.</p>
<p>The annotations are:
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-type: [basic|digest]
</pre></div>
</td></tr></table></p>
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-type: [basic|digest]
</pre></div></p>
<p>Indicates the <a href="https://tools.ietf.org/html/rfc2617">HTTP Authentication Type: Basic or Digest Access Authentication</a>.</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-secret: secretName
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-secret: secretName
</pre></div>
</td></tr></table>
<p>The name of the Secret that contains the usernames and passwords which are granted access to the <code class="codehilite">path</code>s defined in the Ingress rules.
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-realm: &quot;realm string&quot;
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-realm: &quot;realm string&quot;
</pre></div>
</td></tr></table>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p>Please check the <a href="../../../examples/auth/basic/">auth</a> example.</p>
</div>
<h3 id="custom-nginx-upstream-checks">Custom NGINX upstream checks<a class="headerlink" href="#custom-nginx-upstream-checks" title="Permanent link">&para;</a></h3>
<p>NGINX exposes some flags in the <a href="http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">upstream configuration</a> that enable the configuration of each server in the upstream. The Ingress controller allows custom <code class="codehilite">max_fails</code> and <code class="codehilite">fail_timeout</code> parameters in a global context using <code class="codehilite">upstream-max-fails</code> and <code class="codehilite">upstream-fail-timeout</code> in the NGINX ConfigMap or in a particular Ingress rule. <code class="codehilite">upstream-max-fails</code> defaults to 0. This means NGINX will respect the container's <code class="codehilite">readinessProbe</code> if it is defined. If there is no probe and no values for <code class="codehilite">upstream-max-fails</code> NGINX will continue to send traffic to the container.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>With the default configuration NGINX will not health check your backends. Whenever the endpoints controller notices a readiness probe failure, that pod's IP will be removed from the list of endpoints. This will trigger the NGINX controller to also remove it from the upstreams.**</p>
</div>
<p>To use custom values in an Ingress rule define these annotations:</p>
<p><code class="codehilite">nginx.ingress.kubernetes.io/upstream-max-fails</code>: number of unsuccessful attempts to communicate with the server that should occur in the duration set by the <code class="codehilite">upstream-fail-timeout</code> parameter to consider the server unavailable.</p>
<p><code class="codehilite">nginx.ingress.kubernetes.io/upstream-fail-timeout</code>: time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable.</p>
<p>In NGINX, backend server pools are called "<a href="http://nginx.org/en/docs/http/ngx_http_upstream_module.html">upstreams</a>". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined.</p>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>All Ingress rules using the same service will use the same upstream.<br />
Only one of the Ingress rules should define annotations to configure the upstream servers.</p>
</div>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p>Please check the <a href="../../../examples/customization/custom-upstream-check/">custom upstream check</a> example.</p>
</div>
<h3 id="custom-nginx-upstream-hashing">Custom NGINX upstream hashing<a class="headerlink" href="#custom-nginx-upstream-hashing" title="Permanent link">&para;</a></h3>
<p>NGINX supports load balancing by client-server mapping based on <a href="http://nginx.org/en/docs/http/ngx_http_upstream_module.html#hash">consistent hashing</a> for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The <a href="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</a> consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.</p>
<p>To enable consistent hashing for a backend:</p>
@ -2149,11 +2057,9 @@ Only one of the Ingress rules should define annotations to configure the upstrea
</div>
<h3 id="configuration-snippet">Configuration snippet<a class="headerlink" href="#configuration-snippet" title="Permanent link">&para;</a></h3>
<p>Using this annotation you can add additional configuration to the NGINX location. For example:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/configuration-snippet</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">|</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/configuration-snippet</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">|</span>
<span class="no">more_set_headers &quot;Request-Id: $req_id&quot;;</span>
</pre></div>
</td></tr></table>
<h3 id="default-backend">Default Backend<a class="headerlink" href="#default-backend" title="Permanent link">&para;</a></h3>
<p>The ingress controller requires a <a href="../../default-backend/">default backend</a>.
@ -2221,20 +2127,7 @@ the new server configuration will take place over the alias configuration.</p>
<p>For more information please see <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name">the <code class="codehilite">server_name</code> documentation</a>.</p>
<h3 id="server-snippet">Server snippet<a class="headerlink" href="#server-snippet" title="Permanent link">&para;</a></h3>
<p>Using the annotation <code class="codehilite">nginx.ingress.kubernetes.io/server-snippet</code> it is possible to add custom configuration in the server configuration block.</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">extensions/v1beta1</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">extensions/v1beta1</span>
<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Ingress</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">annotations</span><span class="p p-Indicator">:</span>
@ -2249,7 +2142,6 @@ the new server configuration will take place over the alias configuration.</p>
<span class="no">return 301 https://m.example.com;</span>
<span class="no">}</span>
</pre></div>
</td></tr></table>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
@ -2277,9 +2169,8 @@ applied to each location provided in the ingress rule.</p>
<p>For more information please see <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size">http://nginx.org</a></p>
<h3 id="external-authentication">External Authentication<a class="headerlink" href="#external-authentication" title="Permanent link">&para;</a></h3>
<p>To use an existing service that provides authentication the Ingress rule can be annotated with <code class="codehilite">nginx.ingress.kubernetes.io/auth-url</code> to indicate the URL where the HTTP request should be sent.</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/auth-url</span><span class="p p-Indicator">:</span> <span class="s">&quot;URL</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">the</span><span class="nv"> </span><span class="s">authentication</span><span class="nv"> </span><span class="s">service&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/auth-url</span><span class="p p-Indicator">:</span> <span class="s">&quot;URL</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">the</span><span class="nv"> </span><span class="s">authentication</span><span class="nv"> </span><span class="s">service&quot;</span>
</pre></div>
</td></tr></table>
<p>Additionally it is possible to set:</p>
<ul>
@ -2328,16 +2219,6 @@ the User guide.</p>
<p>Because SSL Passthrough works on layer 4 of the OSI model (TCP) and not on the layer 7 (HTTP), using SSL Passthrough
invalidates all the other annotations set on an Ingress object.</p>
</div>
<h3 id="secure-backends-deprecated-since-0180">Secure backends DEPRECATED (since 0.18.0)<a class="headerlink" href="#secure-backends-deprecated-since-0180" title="Permanent link">&para;</a></h3>
<p>Please use <code class="codehilite">nginx.ingress.kubernetes.io/backend-protocol: &quot;HTTPS&quot;</code></p>
<p>By default NGINX uses plain HTTP to reach the services.
Adding the annotation <code class="codehilite">nginx.ingress.kubernetes.io/secure-backends: &quot;true&quot;</code> in the Ingress rule changes the protocol to HTTPS.
If you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation <code class="codehilite">nginx.ingress.kubernetes.io/secure-verify-ca-secret</code>.</p>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>Note that if an invalid or non-existent secret is given,
the ingress controller will ignore the <code class="codehilite">secure-backends</code> annotation.</p>
</div>
<h3 id="service-upstream">Service Upstream<a class="headerlink" href="#service-upstream" title="Permanent link">&para;</a></h3>
<p>By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.</p>
<p>The <code class="codehilite">nginx.ingress.kubernetes.io/service-upstream</code> annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port.</p>
@ -2392,9 +2273,8 @@ otherwise, both annotations must be used in unison. Note that each annotation mu
<p>For NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size"><code class="codehilite">client_max_body_size</code></a>.</p>
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-body-size</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.
To use custom values in an Ingress rule define these annotation:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-body-size</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">8m</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-body-size</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">8m</span>
</pre></div>
</td></tr></table>
<h3 id="proxy-cookie-domain">Proxy cookie domain<a class="headerlink" href="#proxy-cookie-domain" title="Permanent link">&para;</a></h3>
<p>Sets a text that <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_domain">should be changed in the domain attribute</a> of the "Set-Cookie" header fields of a proxied server response.</p>
@ -2407,93 +2287,69 @@ To use custom values in an Ingress rule define these annotation:</p>
By default proxy buffering is disabled in the NGINX config.</p>
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-buffering</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.
To use custom values in an Ingress rule define these annotation:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffering</span><span class="p p-Indicator">:</span> <span class="s">&quot;on&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffering</span><span class="p p-Indicator">:</span> <span class="s">&quot;on&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="proxy-buffer-size">Proxy buffer size<a class="headerlink" href="#proxy-buffer-size" title="Permanent link">&para;</a></h3>
<p>Sets the size of the buffer <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size"><code class="codehilite">proxy_buffer_size</code></a> used for reading the first part of the response received from the proxied server.
By default proxy buffer size is set as "4k"</p>
<p>To configure this setting globally, set <code class="codehilite">proxy-buffer-size</code> in <a href="../configmap/">NGINX ConfigMap</a>. To use custom values in an Ingress rule, define this annotation:
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffer-size</span><span class="p p-Indicator">:</span> <span class="s">&quot;8k&quot;</span>
</pre></div>
</td></tr></table></p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffer-size</span><span class="p p-Indicator">:</span> <span class="s">&quot;8k&quot;</span>
</pre></div></p>
<h3 id="ssl-ciphers">SSL ciphers<a class="headerlink" href="#ssl-ciphers" title="Permanent link">&para;</a></h3>
<p>Specifies the <a href="http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers">enabled ciphers</a>.</p>
<p>Using this annotation will set the <code class="codehilite">ssl_ciphers</code> directive at the server level. This configuration is active for all the paths in the host.</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/ssl-ciphers</span><span class="p p-Indicator">:</span> <span class="s">&quot;ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/ssl-ciphers</span><span class="p p-Indicator">:</span> <span class="s">&quot;ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="connection-proxy-header">Connection proxy header<a class="headerlink" href="#connection-proxy-header" title="Permanent link">&para;</a></h3>
<p>Using this annotation will override the default connection header set by NGINX.
To use custom values in an Ingress rule, define the annotation:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/connection-proxy-header</span><span class="p p-Indicator">:</span> <span class="s">&quot;keep-alive&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/connection-proxy-header</span><span class="p p-Indicator">:</span> <span class="s">&quot;keep-alive&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="enable-access-log">Enable Access Log<a class="headerlink" href="#enable-access-log" title="Permanent link">&para;</a></h3>
<p>Access logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given
ingress. To do this, use the annotation:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-access-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;false&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-access-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;false&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="enable-rewrite-log">Enable Rewrite Log<a class="headerlink" href="#enable-rewrite-log" title="Permanent link">&para;</a></h3>
<p>Rewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs.
Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-rewrite-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-rewrite-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="lua-resty-waf">Lua Resty WAF<a class="headerlink" href="#lua-resty-waf" title="Permanent link">&para;</a></h3>
<p>Using <code class="codehilite">lua-resty-waf-*</code> annotations we can enable and control the <a href="https://github.com/p0pr0ck5/lua-resty-waf">lua-resty-waf</a>
Web Application Firewall per location.</p>
<p>Following configuration will enable the WAF for the paths defined in the corresponding ingress:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf</span><span class="p p-Indicator">:</span> <span class="s">&quot;active&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf</span><span class="p p-Indicator">:</span> <span class="s">&quot;active&quot;</span>
</pre></div>
</td></tr></table>
<p>In order to run it in debugging mode you can set <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-debug</code> to <code class="codehilite">&quot;true&quot;</code> in addition to the above configuration.
The other possible values for <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf</code> are <code class="codehilite">inactive</code> and <code class="codehilite">simulate</code>.
In <code class="codehilite">inactive</code> mode WAF won't do anything, whereas in <code class="codehilite">simulate</code> mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.</p>
<p><code class="codehilite">lua-resty-waf</code> comes with predefined set of rules <a href="https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules">https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules</a> that covers ModSecurity CRS.
You can use <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</code> to ignore a subset of those rulesets. For an example:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</span><span class="p p-Indicator">:</span> <span class="s">&quot;41000_sqli,</span><span class="nv"> </span><span class="s">42000_xss&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</span><span class="p p-Indicator">:</span> <span class="s">&quot;41000_sqli,</span><span class="nv"> </span><span class="s">42000_xss&quot;</span>
</pre></div>
</td></tr></table>
<p>will ignore the two mentioned rulesets.</p>
<p>It is also possible to configure custom WAF rules per ingress using the <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</code> annotation. For an example the following snippet will configure a WAF rule to deny requests with query string value that contains word <code class="codehilite">foo</code>:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</span><span class="p p-Indicator">:</span> <span class="s">&#39;[=[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;access&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;actions&quot;:</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;disrupt&quot;</span><span class="nv"> </span><span class="s">:</span><span class="nv"> </span><span class="s">&quot;DENY&quot;</span><span class="nv"> </span><span class="s">},</span><span class="nv"> </span><span class="s">&quot;id&quot;:</span><span class="nv"> </span><span class="s">10001,</span><span class="nv"> </span><span class="s">&quot;msg&quot;:</span><span class="nv"> </span><span class="s">&quot;my</span><span class="nv"> </span><span class="s">custom</span><span class="nv"> </span><span class="s">rule&quot;,</span><span class="nv"> </span><span class="s">&quot;operator&quot;:</span><span class="nv"> </span><span class="s">&quot;STR_CONTAINS&quot;,</span><span class="nv"> </span><span class="s">&quot;pattern&quot;:</span><span class="nv"> </span><span class="s">&quot;foo&quot;,</span><span class="nv"> </span><span class="s">&quot;vars&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;parse&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">&quot;values&quot;,</span><span class="nv"> </span><span class="s">1</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;type&quot;:</span><span class="nv"> </span><span class="s">&quot;REQUEST_ARGS&quot;</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;body_filter&quot;:</span><span class="nv"> </span><span class="s">[],</span><span class="nv"> </span><span class="s">&quot;header_filter&quot;:[]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]=]&#39;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</span><span class="p p-Indicator">:</span> <span class="s">&#39;[=[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;access&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;actions&quot;:</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;disrupt&quot;</span><span class="nv"> </span><span class="s">:</span><span class="nv"> </span><span class="s">&quot;DENY&quot;</span><span class="nv"> </span><span class="s">},</span><span class="nv"> </span><span class="s">&quot;id&quot;:</span><span class="nv"> </span><span class="s">10001,</span><span class="nv"> </span><span class="s">&quot;msg&quot;:</span><span class="nv"> </span><span class="s">&quot;my</span><span class="nv"> </span><span class="s">custom</span><span class="nv"> </span><span class="s">rule&quot;,</span><span class="nv"> </span><span class="s">&quot;operator&quot;:</span><span class="nv"> </span><span class="s">&quot;STR_CONTAINS&quot;,</span><span class="nv"> </span><span class="s">&quot;pattern&quot;:</span><span class="nv"> </span><span class="s">&quot;foo&quot;,</span><span class="nv"> </span><span class="s">&quot;vars&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;parse&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">&quot;values&quot;,</span><span class="nv"> </span><span class="s">1</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;type&quot;:</span><span class="nv"> </span><span class="s">&quot;REQUEST_ARGS&quot;</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;body_filter&quot;:</span><span class="nv"> </span><span class="s">[],</span><span class="nv"> </span><span class="s">&quot;header_filter&quot;:[]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]=]&#39;</span>
</pre></div>
</td></tr></table>
<p>For details on how to write WAF rules, please refer to <a href="https://github.com/p0pr0ck5/lua-resty-waf">https://github.com/p0pr0ck5/lua-resty-waf</a>.</p>
<h3 id="grpc-backend-deprecated-since-0180">gRPC backend DEPRECATED (since 0.18.0)<a class="headerlink" href="#grpc-backend-deprecated-since-0180" title="Permanent link">&para;</a></h3>
<p>Please use <code class="codehilite">nginx.ingress.kubernetes.io/backend-protocol: &quot;GRPC&quot;</code> or <code class="codehilite">nginx.ingress.kubernetes.io/backend-protocol: &quot;GRPCS&quot;</code></p>
<p>Since NGINX 1.13.10 it is possible to expose <a href="http://nginx.org/en/docs/http/ngx_http_grpc_module.html">gRPC services natively</a></p>
<p>You only need to add the annotation <code class="codehilite">nginx.ingress.kubernetes.io/grpc-backend: &quot;true&quot;</code> to enable this feature.
Additionally, if the gRPC service requires TLS, add <code class="codehilite">nginx.ingress.kubernetes.io/secure-backends: &quot;true&quot;</code>.</p>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>This feature requires HTTP2 to work which means we need to expose this service using HTTPS.
Exposing a gRPC service using HTTP is not supported.</p>
</div>
<h3 id="influxdb">InfluxDB<a class="headerlink" href="#influxdb" title="Permanent link">&para;</a></h3>
<p>Using <code class="codehilite">influxdb-*</code> annotations we can monitor requests passing through a Location by sending them to an InfluxDB backend exposing the UDP socket
using the <a href="https://github.com/influxdata/nginx-influxdb-module/">nginx-influxdb-module</a>.</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-influxdb</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-influxdb</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-measurement</span><span class="p p-Indicator">:</span> <span class="s">&quot;nginx-reqs&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-port</span><span class="p p-Indicator">:</span> <span class="s">&quot;8089&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-host</span><span class="p p-Indicator">:</span> <span class="s">&quot;127.0.0.1&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-server-name</span><span class="p p-Indicator">:</span> <span class="s">&quot;nginx-ingress&quot;</span>
</pre></div>
</td></tr></table>
<p>For the <code class="codehilite">influxdb-host</code> parameter you have two options:</p>
<ul>
@ -2509,20 +2365,17 @@ an ip address to <code class="codehilite">nginx.ingress.kubernetes.io/influxdb-h
Valid Values: HTTP, HTTPS, GRPC, GRPCS and AJP</p>
<p>By default NGINX uses <code class="codehilite">HTTP</code>.</p>
<p>Example:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/backend-protocol</span><span class="p p-Indicator">:</span> <span class="s">&quot;HTTPS&quot;</span>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/backend-protocol</span><span class="p p-Indicator">:</span> <span class="s">&quot;HTTPS&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="use-regex">Use Regex<a class="headerlink" href="#use-regex" title="Permanent link">&para;</a></h3>
<p>Using the <code class="codehilite">nginx.ingress.kubernetes.io/use-regex</code> annotation will indicate whether or not the paths defined on an Ingress use regular expressions. The default value is <code class="codehilite">false</code>.</p>
<p>The following will indicate that regular expression paths are being used:
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/use-regex</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
</pre></div>
</td></tr></table></p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/use-regex</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
</pre></div></p>
<p>The following will indicate that regular expression paths are <strong>not</strong> being used:
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/use-regex</span><span class="p p-Indicator">:</span> <span class="s">&quot;false&quot;</span>
</pre></div>
</td></tr></table></p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/use-regex</span><span class="p p-Indicator">:</span> <span class="s">&quot;false&quot;</span>
</pre></div></p>
<p>When this annotation is set to <code class="codehilite">true</code>, the case insensitive regular expression <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#location">location modifier</a> will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p>
<p>Additionally, if the <a href="#rewrite"><code class="codehilite">rewrite-target</code> annotation</a> is used on any Ingress for a given host, then the case insensitive regular expression <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#location">location modifier</a> will be enforced on ALL paths for a given host regardless of what Ingress they are defined on. </p>
<p>Please read about <a href="../../ingress-path-matching/">ingress path matching</a> before using this modifier. </p>