diff --git a/examples/grpc/index.html b/examples/grpc/index.html
index 113a19fbb..6e3373d04 100644
--- a/examples/grpc/index.html
+++ b/examples/grpc/index.html
@@ -81,4 +81,4 @@ EOF
 {
   "message": "Hello "
 }
-</code></pre></div> <h3 id=debugging-hints>Debugging Hints<a class=headerlink href=#debugging-hints title="Permanent link"> ¶</a></h3> <ol> <li>Obviously, watch the logs on your app.</li> <li>Watch the logs for the ingress-nginx-controller (increasing verbosity as needed).</li> <li>Double-check your address and ports.</li> <li>Set the <code>GODEBUG=http2debug=2</code> environment variable to get detailed http/2 logging on the client and/or server.</li> <li>Study RFC 7540 (http/2) <a href=https://tools.ietf.org/html/rfc7540>https://tools.ietf.org/html/rfc7540</a>.</li> </ol> <blockquote> <p>If you are developing public gRPC endpoints, check out https://proto.stack.build, a protocol buffer / gRPC build service that can use to help make it easier for your users to consume your API.</p> <p>See also the specific gRPC settings of NGINX: https://nginx.org/en/docs/http/ngx_http_grpc_module.html</p> </blockquote> <h3 id=notes-on-using-responserequest-streams>Notes on using response/request streams<a class=headerlink href=#notes-on-using-responserequest-streams title="Permanent link"> ¶</a></h3> <ol> <li>If your server only does response streaming and you expect a stream to be open longer than 60 seconds, you will have to change the <code>grpc_read_timeout</code> to accommodate this.</li> <li>If your service only does request streaming and you expect a stream to be open longer than 60 seconds, you have to change the <code>grpc_send_timeout</code> and the <code>client_body_timeout</code>.</li> <li>If you do both response and request streaming with an open stream longer than 60 seconds, you have to change all three timeouts: <code>grpc_read_timeout</code>, <code>grpc_send_timeout</code> and <code>client_body_timeout</code>.</li> </ol> <p>Values for the timeouts must be specified as e.g. <code>"1200s"</code>.</p> <blockquote> <p>On the most recent versions of ingress-nginx, changing these timeouts requires using the <code>nginx.ingress.kubernetes.io/server-snippet</code> annotation. There are plans for future releases to allow using the Kubernetes annotations to define each timeout separately.</p> </blockquote> </article> </div> </div> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> Made with <a href=https://squidfunk.github.io/mkdocs-material/ target=_blank rel=noopener> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <script id=__config type=application/json>{"base": "../..", "features": ["navigation.tabs", "navigation.tabs.sticky", "navigation.instant", "navigation.sections"], "search": "../../assets/javascripts/workers/search.f886a092.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src=../../assets/javascripts/bundle.aecac24b.min.js></script> </body> </html>
\ No newline at end of file
+</code></pre></div> <h3 id=debugging-hints>Debugging Hints<a class=headerlink href=#debugging-hints title="Permanent link"> ¶</a></h3> <ol> <li>Obviously, watch the logs on your app.</li> <li>Watch the logs for the ingress-nginx-controller (increasing verbosity as needed).</li> <li>Double-check your address and ports.</li> <li>Set the <code>GODEBUG=http2debug=2</code> environment variable to get detailed http/2 logging on the client and/or server.</li> <li>Study RFC 7540 (http/2) <a href=https://tools.ietf.org/html/rfc7540>https://tools.ietf.org/html/rfc7540</a>.</li> </ol> <blockquote> <p>If you are developing public gRPC endpoints, check out https://proto.stack.build, a protocol buffer / gRPC build service that can use to help make it easier for your users to consume your API.</p> <p>See also the specific gRPC settings of NGINX: https://nginx.org/en/docs/http/ngx_http_grpc_module.html</p> </blockquote> <h3 id=notes-on-using-responserequest-streams>Notes on using response/request streams<a class=headerlink href=#notes-on-using-responserequest-streams title="Permanent link"> ¶</a></h3> <blockquote> <p><code>grpc_read_timeout</code> and <code>grpc_send_timeout</code> will be set as <code>proxy_read_timeout</code> and <code>proxy_send_timeout</code> when you set backend protocol to <code>GRPC</code> or <code>GRPCS</code>.</p> </blockquote> <ol> <li>If your server only does response streaming and you expect a stream to be open longer than 60 seconds, you will have to change the <code>grpc_read_timeout</code> to accommodate this.</li> <li>If your service only does request streaming and you expect a stream to be open longer than 60 seconds, you have to change the <code>grpc_send_timeout</code> and the <code>client_body_timeout</code>.</li> <li>If you do both response and request streaming with an open stream longer than 60 seconds, you have to change all three timeouts: <code>grpc_read_timeout</code>, <code>grpc_send_timeout</code> and <code>client_body_timeout</code>.</li> </ol> </article> </div> </div> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> Made with <a href=https://squidfunk.github.io/mkdocs-material/ target=_blank rel=noopener> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <script id=__config type=application/json>{"base": "../..", "features": ["navigation.tabs", "navigation.tabs.sticky", "navigation.instant", "navigation.sections"], "search": "../../assets/javascripts/workers/search.f886a092.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src=../../assets/javascripts/bundle.aecac24b.min.js></script> </body> </html>
\ No newline at end of file
diff --git a/search/search_index.json b/search/search_index.json
index 9e3e7997c..20c87e537 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Overview","text":"<p>This is the documentation for the Ingress NGINX Controller.</p> <p>It is built around the Kubernetes Ingress resource, using a ConfigMap to store the controller configuration.</p> <p>You can learn more about using Ingress in the official Kubernetes documentation.</p>"},{"location":"#getting-started","title":"Getting Started","text":"<p>See Deployment for a whirlwind tour that will get you started.</p>"},{"location":"e2e-tests/","title":"E2e tests","text":""},{"location":"e2e-tests/#e2e-test-suite-for-ingress-nginx-controller","title":"e2e test suite for Ingress NGINX Controller","text":""},{"location":"e2e-tests/#admission-admission-controller","title":"[Admission] admission controller","text":"<ul> <li>reject ingress with global-rate-limit annotations when memcached is not configured</li> <li>should not allow overlaps of host and paths without canary annotations</li> <li>should allow overlaps of host and paths with canary annotation</li> <li>should block ingress with invalid path</li> <li>should return an error if there is an error validating the ingress definition</li> <li>should return an error if there is an invalid value in some annotation</li> <li>should return an error if there is a forbidden value in some annotation</li> <li>should return an error if there is an invalid path and wrong pathType is set</li> <li>should not return an error if the Ingress V1 definition is valid with Ingress Class</li> <li>should not return an error if the Ingress V1 definition is valid with IngressClass annotation</li> <li>should return an error if the Ingress V1 definition contains invalid annotations</li> <li>should not return an error for an invalid Ingress when it has unknown class</li> </ul>"},{"location":"e2e-tests/#affinity-session-cookie-name","title":"affinity session-cookie-name","text":"<ul> <li>should set sticky cookie SERVERID</li> <li>should change cookie name on ingress definition change</li> <li>should set the path to /something on the generated cookie</li> <li>does not set the path to / on the generated cookie if there's more than one rule referring to the same backend</li> <li>should set cookie with expires</li> <li>should set cookie with domain</li> <li>should not set cookie without domain annotation</li> <li>should work with use-regex annotation and session-cookie-path</li> <li>should warn user when use-regex is true and session-cookie-path is not set</li> <li>should not set affinity across all server locations when using separate ingresses</li> <li>should set sticky cookie without host</li> <li>should work with server-alias annotation</li> <li>should set secure in cookie with provided true annotation on http</li> <li>should not set secure in cookie with provided false annotation on http</li> <li>should set secure in cookie with provided false annotation on https</li> </ul>"},{"location":"e2e-tests/#affinitymode","title":"affinitymode","text":"<ul> <li>Balanced affinity mode should balance</li> <li>Check persistent affinity mode</li> </ul>"},{"location":"e2e-tests/#server-alias","title":"server-alias","text":"<ul> <li>should return status code 200 for host 'foo' and 404 for 'bar'</li> <li>should return status code 200 for host 'foo' and 'bar'</li> <li>should return status code 200 for hosts defined in two ingresses, different path with one alias</li> </ul>"},{"location":"e2e-tests/#app-root","title":"app-root","text":"<ul> <li>should redirect to /foo</li> </ul>"},{"location":"e2e-tests/#auth-","title":"auth-*","text":"<ul> <li>should return status code 200 when no authentication is configured</li> <li>should return status code 503 when authentication is configured with an invalid secret</li> <li>should return status code 401 when authentication is configured but Authorization header is not configured</li> <li>should return status code 401 when authentication is configured and Authorization header is sent with invalid credentials</li> <li>should return status code 401 and cors headers when authentication and cors is configured but Authorization header is not configured</li> <li>should return status code 200 when authentication is configured and Authorization header is sent</li> <li>should return status code 200 when authentication is configured with a map and Authorization header is sent</li> <li>should return status code 401 when authentication is configured with invalid content and Authorization header is sent</li> <li>proxy_set_header My-Custom-Header 42;</li> <li>proxy_set_header My-Custom-Header 42;</li> <li>proxy_set_header 'My-Custom-Header' '42';</li> <li>user retains cookie by default</li> <li>user does not retain cookie if upstream returns error status code</li> <li>user with annotated ingress retains cookie if upstream returns error status code</li> <li>should return status code 200 when signed in</li> <li>should redirect to signin url when not signed in</li> <li>keeps processing new ingresses even if one of the existing ingresses is misconfigured</li> <li>should overwrite Foo header with auth response</li> <li>should return status code 200 when signed in</li> <li>should redirect to signin url when not signed in</li> <li>keeps processing new ingresses even if one of the existing ingresses is misconfigured</li> <li>should return status code 200 when signed in after auth backend is deleted </li> <li>should deny login for different location on same server</li> <li>should deny login for different servers</li> <li>should redirect to signin url when not signed in</li> <li>should return 503 (location was denied)</li> <li>should add error to the config</li> </ul>"},{"location":"e2e-tests/#auth-tls-","title":"auth-tls-*","text":"<ul> <li>should set sslClientCertificate, sslVerifyClient and sslVerifyDepth with auth-tls-secret</li> <li>should set valid auth-tls-secret, sslVerify to off, and sslVerifyDepth to 2</li> <li>should 302 redirect to error page instead of 400 when auth-tls-error-page is set</li> <li>should pass URL-encoded certificate to upstream</li> <li>should validate auth-tls-verify-client</li> <li>should return 403 using auth-tls-match-cn with no matching CN from client</li> <li>should return 200 using auth-tls-match-cn with matching CN from client</li> <li>should return 200 using auth-tls-match-cn where atleast one of the regex options matches CN from client</li> </ul>"},{"location":"e2e-tests/#backend-protocol","title":"backend-protocol","text":"<ul> <li>should set backend protocol to https:// and use proxy_pass</li> <li>should set backend protocol to https:// and use proxy_pass with lowercase annotation</li> <li>should set backend protocol to $scheme:// and use proxy_pass</li> <li>should set backend protocol to grpc:// and use grpc_pass</li> <li>should set backend protocol to grpcs:// and use grpc_pass</li> <li>should set backend protocol to '' and use fastcgi_pass</li> </ul>"},{"location":"e2e-tests/#canary-","title":"canary-*","text":"<ul> <li>should response with a 200 status from the mainline upstream when requests are made to the mainline ingress</li> <li>should return 404 status for requests to the canary if no matching ingress is found</li> <li>should return the correct status codes when endpoints are unavailable</li> <li>should route requests to the correct upstream if mainline ingress is created before the canary ingress</li> <li>should route requests to the correct upstream if mainline ingress is created after the canary ingress</li> <li>should route requests to the correct upstream if the mainline ingress is modified</li> <li>should route requests to the correct upstream if the canary ingress is modified</li> <li>should route requests to the correct upstream</li> <li>should route requests to the correct upstream</li> <li>should route requests to the correct upstream</li> <li>should route requests to the correct upstream</li> <li>should routes to mainline upstream when the given Regex causes error</li> <li>should route requests to the correct upstream</li> <li>respects always and never values</li> <li>should route requests only to mainline if canary weight is 0</li> <li>should route requests only to canary if canary weight is 100</li> <li>should route requests only to canary if canary weight is equal to canary weight total</li> <li>should route requests split between mainline and canary if canary weight is 50</li> <li>should route requests split between mainline and canary if canary weight is 100 and weight total is 200</li> <li>should not use canary as a catch-all server</li> <li>should not use canary with domain as a server</li> <li>does not crash when canary ingress has multiple paths to the same non-matching backend</li> <li>always routes traffic to canary if first request was affinitized to canary (default behavior)</li> <li>always routes traffic to canary if first request was affinitized to canary (explicit sticky behavior)</li> <li>routes traffic to either mainline or canary backend (legacy behavior)</li> </ul>"},{"location":"e2e-tests/#client-body-buffer-size","title":"client-body-buffer-size","text":"<ul> <li>should set client_body_buffer_size to 1000</li> <li>should set client_body_buffer_size to 1K</li> <li>should set client_body_buffer_size to 1k</li> <li>should set client_body_buffer_size to 1m</li> <li>should set client_body_buffer_size to 1M</li> <li>should not set client_body_buffer_size to invalid 1b</li> </ul>"},{"location":"e2e-tests/#connection-proxy-header","title":"connection-proxy-header","text":"<ul> <li>set connection header to keep-alive</li> </ul>"},{"location":"e2e-tests/#cors-","title":"cors-*","text":"<ul> <li>should enable cors</li> <li>should set cors methods to only allow POST, GET</li> <li>should set cors max-age</li> <li>should disable cors allow credentials</li> <li>should allow origin for cors</li> <li>should allow headers for cors</li> <li>should expose headers for cors</li> <li>should allow - single origin for multiple cors values</li> <li>should not allow - single origin for multiple cors values</li> <li>should allow correct origins - single origin for multiple cors values</li> <li>should not break functionality</li> <li>should not break functionality - without <code>*</code></li> <li>should not break functionality with extra domain</li> <li>should not match</li> <li>should allow - single origin with required port</li> <li>should not allow - single origin with port and origin without port</li> <li>should not allow - single origin without port and origin with required port</li> <li>should allow - matching origin with wildcard origin (2 subdomains)</li> <li>should not allow - unmatching origin with wildcard origin (2 subdomains)</li> <li>should allow - matching origin+port with wildcard origin</li> <li>should not allow - portless origin with wildcard origin</li> <li>should allow correct origins - missing subdomain + origin with wildcard origin and correct origin</li> <li>should allow - missing origins (should allow all origins)</li> <li>should allow correct origin but not others - cors allow origin annotations contain trailing comma</li> </ul>"},{"location":"e2e-tests/#custom-http-errors","title":"custom-http-errors","text":"<ul> <li>configures Nginx correctly</li> </ul>"},{"location":"e2e-tests/#default-backend","title":"default-backend","text":"<ul> <li>should use a custom default backend as upstream</li> </ul>"},{"location":"e2e-tests/#disable-access-log-disable-http-access-log-disable-stream-access-log","title":"disable-access-log disable-http-access-log disable-stream-access-log","text":"<ul> <li>disable-access-log set access_log off</li> <li>disable-http-access-log set access_log off</li> <li>disable-stream-access-log set access_log off</li> </ul>"},{"location":"e2e-tests/#disable-proxy-intercept-errors","title":"disable-proxy-intercept-errors","text":"<ul> <li>configures Nginx correctly</li> </ul>"},{"location":"e2e-tests/#backend-protocol-fastcgi","title":"backend-protocol - FastCGI","text":"<ul> <li>should use fastcgi_pass in the configuration file</li> <li>should add fastcgi_index in the configuration file</li> <li>should add fastcgi_param in the configuration file</li> <li>should return OK for service with backend protocol FastCGI</li> </ul>"},{"location":"e2e-tests/#force-ssl-redirect","title":"force-ssl-redirect","text":"<ul> <li>should redirect to https</li> </ul>"},{"location":"e2e-tests/#from-to-www-redirect","title":"from-to-www-redirect","text":"<ul> <li>should redirect from www HTTP to HTTP</li> <li>should redirect from www HTTPS to HTTPS</li> </ul>"},{"location":"e2e-tests/#annotation-global-rate-limit","title":"annotation-global-rate-limit","text":"<ul> <li>generates correct configuration</li> </ul>"},{"location":"e2e-tests/#backend-protocol-grpc","title":"backend-protocol - GRPC","text":"<ul> <li>should use grpc_pass in the configuration file</li> <li>should return OK for service with backend protocol GRPC</li> <li>authorization metadata should be overwritten by external auth response headers</li> <li>should return OK for service with backend protocol GRPCS</li> </ul>"},{"location":"e2e-tests/#http2-push-preload","title":"http2-push-preload","text":"<ul> <li>enable the http2-push-preload directive</li> </ul>"},{"location":"e2e-tests/#allowlist-source-range","title":"allowlist-source-range","text":"<ul> <li>should set valid ip allowlist range</li> </ul>"},{"location":"e2e-tests/#denylist-source-range","title":"denylist-source-range","text":"<ul> <li>only deny explicitly denied IPs, allow all others</li> <li>only allow explicitly allowed IPs, deny all others</li> </ul>"},{"location":"e2e-tests/#annotation-limit-connections","title":"Annotation - limit-connections","text":"<ul> <li>should limit-connections</li> </ul>"},{"location":"e2e-tests/#limit-rate","title":"limit-rate","text":"<ul> <li>Check limit-rate annotation</li> </ul>"},{"location":"e2e-tests/#enable-access-log-enable-rewrite-log","title":"enable-access-log enable-rewrite-log","text":"<ul> <li>set access_log off</li> <li>set rewrite_log on</li> </ul>"},{"location":"e2e-tests/#mirror-","title":"mirror-*","text":"<ul> <li>should set mirror-target to http://localhost/mirror</li> <li>should set mirror-target to https://test.env.com/$request_uri</li> <li>should disable mirror-request-body</li> </ul>"},{"location":"e2e-tests/#modsecurity-owasp","title":"modsecurity owasp","text":"<ul> <li>should enable modsecurity</li> <li>should enable modsecurity with transaction ID and OWASP rules</li> <li>should disable modsecurity</li> <li>should enable modsecurity with snippet</li> <li>should enable modsecurity without using 'modsecurity on;'</li> <li>should disable modsecurity using 'modsecurity off;'</li> <li>should enable modsecurity with snippet and block requests</li> <li>should enable modsecurity globally and with modsecurity-snippet block requests</li> <li>should enable modsecurity when enable-owasp-modsecurity-crs is set to true</li> <li>should enable modsecurity through the config map</li> <li>should enable modsecurity through the config map but ignore snippet as disabled by admin</li> <li>should disable default modsecurity conf setting when modsecurity-snippet is specified</li> </ul>"},{"location":"e2e-tests/#preserve-trailing-slash","title":"preserve-trailing-slash","text":"<ul> <li>should allow preservation of trailing slashes</li> </ul>"},{"location":"e2e-tests/#proxy-","title":"proxy-*","text":"<ul> <li>should set proxy_redirect to off</li> <li>should set proxy_redirect to default</li> <li>should set proxy_redirect to hello.com goodbye.com</li> <li>should set proxy client-max-body-size to 8m</li> <li>should not set proxy client-max-body-size to incorrect value</li> <li>should set valid proxy timeouts</li> <li>should not set invalid proxy timeouts</li> <li>should turn on proxy-buffering</li> <li>should turn off proxy-request-buffering</li> <li>should build proxy next upstream</li> <li>should setup proxy cookies</li> <li>should change the default proxy HTTP version</li> </ul>"},{"location":"e2e-tests/#proxy-ssl-","title":"proxy-ssl-*","text":"<ul> <li>should set valid proxy-ssl-secret</li> <li>should set valid proxy-ssl-secret, proxy-ssl-verify to on, proxy-ssl-verify-depth to 2, and proxy-ssl-server-name to on</li> <li>should set valid proxy-ssl-secret, proxy-ssl-ciphers to HIGH:!AES</li> <li>should set valid proxy-ssl-secret, proxy-ssl-protocols</li> <li>proxy-ssl-location-only flag should change the nginx config server part</li> </ul>"},{"location":"e2e-tests/#permanent-redirect-permanent-redirect-code","title":"permanent-redirect permanent-redirect-code","text":"<ul> <li>should respond with a standard redirect code</li> <li>should respond with a custom redirect code</li> </ul>"},{"location":"e2e-tests/#rewrite-target-use-regex-enable-rewrite-log","title":"rewrite-target use-regex enable-rewrite-log","text":"<ul> <li>should write rewrite logs</li> <li>should use correct longest path match</li> <li>should use ~* location modifier if regex annotation is present</li> <li>should fail to use longest match for documented warning</li> <li>should allow for custom rewrite parameters</li> </ul>"},{"location":"e2e-tests/#satisfy","title":"satisfy","text":"<ul> <li>should configure satisfy directive correctly</li> <li>should allow multiple auth with satisfy any</li> </ul>"},{"location":"e2e-tests/#server-snippet","title":"server-snippet","text":""},{"location":"e2e-tests/#service-upstream","title":"service-upstream","text":"<ul> <li>should use the Service Cluster IP and Port </li> <li>should use the Service Cluster IP and Port </li> <li>should not use the Service Cluster IP and Port</li> </ul>"},{"location":"e2e-tests/#configuration-snippet","title":"configuration-snippet","text":"<ul> <li>set snippet more_set_headers in all locations</li> <li>drops snippet more_set_header in all locations if disabled by admin</li> </ul>"},{"location":"e2e-tests/#ssl-ciphers","title":"ssl-ciphers","text":"<ul> <li>should change ssl ciphers</li> <li>should keep ssl ciphers</li> </ul>"},{"location":"e2e-tests/#stream-snippet","title":"stream-snippet","text":"<ul> <li>should add value of stream-snippet to nginx config</li> <li>should add stream-snippet and drop annotations per admin config</li> </ul>"},{"location":"e2e-tests/#upstream-hash-by-","title":"upstream-hash-by-*","text":"<ul> <li>should connect to the same pod</li> <li>should connect to the same subset of pods</li> </ul>"},{"location":"e2e-tests/#upstream-vhost","title":"upstream-vhost","text":"<ul> <li>set host to upstreamvhost.bar.com</li> </ul>"},{"location":"e2e-tests/#x-forwarded-prefix","title":"x-forwarded-prefix","text":"<ul> <li>should set the X-Forwarded-Prefix to the annotation value</li> <li>should not add X-Forwarded-Prefix if the annotation value is empty</li> </ul>"},{"location":"e2e-tests/#debug-cli","title":"Debug CLI","text":"<ul> <li>should list the backend servers</li> <li>should get information for a specific backend server</li> <li>should produce valid JSON for /dbg general</li> </ul>"},{"location":"e2e-tests/#default-backend-custom-service","title":"[Default Backend] custom service","text":"<ul> <li>uses custom default backend that returns 200 as status code</li> </ul>"},{"location":"e2e-tests/#default-backend_1","title":"[Default Backend]","text":"<ul> <li>should return 404 sending requests when only a default backend is running</li> <li>enables access logging for default backend</li> <li>disables access logging for default backend</li> </ul>"},{"location":"e2e-tests/#default-backend-ssl","title":"[Default Backend] SSL","text":"<ul> <li>should return a self generated SSL certificate</li> </ul>"},{"location":"e2e-tests/#default-backend-change-default-settings","title":"[Default Backend] change default settings","text":"<ul> <li>should apply the annotation to the default backend</li> </ul>"},{"location":"e2e-tests/#endpointslices-long-service-name","title":"[Endpointslices] long service name","text":"<ul> <li>should return 200 when service name has max allowed number of characters 63</li> </ul>"},{"location":"e2e-tests/#topologyhints-topology-aware-routing","title":"[TopologyHints] topology aware routing","text":"<ul> <li>should return 200 when service has topology hints</li> </ul>"},{"location":"e2e-tests/#shutdown-grace-period-shutdown","title":"[Shutdown] Grace period shutdown","text":"<ul> <li>/healthz should return status code 500 during shutdown grace period</li> </ul>"},{"location":"e2e-tests/#shutdown-ingress-controller","title":"[Shutdown] ingress controller","text":"<ul> <li>should shutdown in less than 60 secons without pending connections</li> </ul>"},{"location":"e2e-tests/#shutdown-graceful-shutdown-with-pending-request","title":"[Shutdown] Graceful shutdown with pending request","text":"<ul> <li>should let slow requests finish before shutting down</li> </ul>"},{"location":"e2e-tests/#ingress-deepinspection","title":"[Ingress] DeepInspection","text":"<ul> <li>should drop whole ingress if one path matches invalid regex</li> </ul>"},{"location":"e2e-tests/#single-ingress-multiple-hosts","title":"single ingress - multiple hosts","text":"<ul> <li>should set the correct $service_name NGINX variable</li> </ul>"},{"location":"e2e-tests/#ingress-pathtype-exact","title":"[Ingress] [PathType] exact","text":"<ul> <li>should choose exact location for /exact</li> </ul>"},{"location":"e2e-tests/#ingress-pathtype-mix-exact-and-prefix-paths","title":"[Ingress] [PathType] mix Exact and Prefix paths","text":"<ul> <li>should choose the correct location</li> </ul>"},{"location":"e2e-tests/#ingress-pathtype-prefix-checks","title":"[Ingress] [PathType] prefix checks","text":"<ul> <li>should return 404 when prefix /aaa does not match request /aaaccc</li> <li>should test prefix path using simple regex pattern for /id/{int}</li> <li>should test prefix path using regex pattern for /id/{int} ignoring non-digits characters at end of string</li> <li>should test prefix path using fixed path size regex pattern /id/{int}{3}</li> <li>should correctly route multi-segment path patterns</li> </ul>"},{"location":"e2e-tests/#ingress-definition-without-host","title":"[Ingress] definition without host","text":"<ul> <li>should set ingress details variables for ingresses without a host</li> <li>should set ingress details variables for ingresses with host without IngressRuleValue, only Backend</li> </ul>"},{"location":"e2e-tests/#memory-leak-dynamic-certificates","title":"[Memory Leak] Dynamic Certificates","text":"<ul> <li>should not leak memory from ingress SSL certificates or configuration updates</li> </ul>"},{"location":"e2e-tests/#load-balancer-load-balance","title":"[Load Balancer] load-balance","text":"<ul> <li>should apply the configmap load-balance setting</li> </ul>"},{"location":"e2e-tests/#load-balancer-ewma","title":"[Load Balancer] EWMA","text":"<ul> <li>does not fail requests</li> </ul>"},{"location":"e2e-tests/#load-balancer-round-robin","title":"[Load Balancer] round-robin","text":"<ul> <li>should evenly distribute requests with round-robin (default algorithm)</li> </ul>"},{"location":"e2e-tests/#lua-dynamic-certificates","title":"[Lua] dynamic certificates","text":"<ul> <li>picks up the certificate when we add TLS spec to existing ingress</li> <li>picks up the previously missing secret for a given ingress without reloading</li> <li>supports requests with domain with trailing dot</li> <li>picks up the updated certificate without reloading</li> <li>falls back to using default certificate when secret gets deleted without reloading</li> <li>picks up a non-certificate only change</li> <li>removes HTTPS configuration when we delete TLS spec</li> </ul>"},{"location":"e2e-tests/#lua-dynamic-configuration","title":"[Lua] dynamic configuration","text":"<ul> <li>configures balancer Lua middleware correctly</li> <li>handles endpoints only changes</li> <li>handles endpoints only changes (down scaling of replicas)</li> <li>handles endpoints only changes consistently (down scaling of replicas vs. empty service)</li> <li>handles an annotation change</li> </ul>"},{"location":"e2e-tests/#metrics-exported-prometheus-metrics","title":"[metrics] exported prometheus metrics","text":"<ul> <li>exclude socket request metrics are absent</li> <li>exclude socket request metrics are present</li> </ul>"},{"location":"e2e-tests/#nginx-configuration","title":"nginx-configuration","text":"<ul> <li>start nginx with default configuration</li> <li>fails when using alias directive</li> <li>fails when using root directive</li> </ul>"},{"location":"e2e-tests/#security-request-smuggling","title":"[Security] request smuggling","text":"<ul> <li>should not return body content from error_page</li> </ul>"},{"location":"e2e-tests/#service-backend-status-code-503","title":"[Service] backend status code 503","text":"<ul> <li>should return 503 when backend service does not exist</li> <li>should return 503 when all backend service endpoints are unavailable</li> </ul>"},{"location":"e2e-tests/#service-type-externalname","title":"[Service] Type ExternalName","text":"<ul> <li>works with external name set to incomplete fqdn</li> <li>should return 200 for service type=ExternalName without a port defined</li> <li>should return 200 for service type=ExternalName with a port defined</li> <li>should return status 502 for service type=ExternalName with an invalid host</li> <li>should return 200 for service type=ExternalName using a port name</li> <li>should return 200 for service type=ExternalName using FQDN with trailing dot</li> <li>should update the external name after a service update</li> <li>should sync ingress on external name service addition/deletion</li> </ul>"},{"location":"e2e-tests/#service-nil-service-backend","title":"[Service] Nil Service Backend","text":"<ul> <li>should return 404 when backend service is nil</li> </ul>"},{"location":"e2e-tests/#access-log","title":"access-log","text":"<ul> <li>use the default configuration</li> <li>use the specified configuration</li> <li>use the specified configuration</li> <li>use the specified configuration</li> <li>use the specified configuration</li> </ul>"},{"location":"e2e-tests/#aio-write","title":"aio-write","text":"<ul> <li>should be enabled by default</li> <li>should be enabled when setting is true</li> <li>should be disabled when setting is false</li> </ul>"},{"location":"e2e-tests/#bad-annotation-values","title":"Bad annotation values","text":"<ul> <li>[BAD_ANNOTATIONS] should drop an ingress if there is an invalid character in some annotation</li> <li>[BAD_ANNOTATIONS] should drop an ingress if there is a forbidden word in some annotation</li> <li>[BAD_ANNOTATIONS] should allow an ingress if there is a default blocklist config in place</li> <li>[BAD_ANNOTATIONS] should drop an ingress if there is a custom blocklist config in place and allow others to pass</li> </ul>"},{"location":"e2e-tests/#brotli","title":"brotli","text":"<ul> <li>should only compress responses that meet the <code>brotli-min-length</code> condition</li> </ul>"},{"location":"e2e-tests/#configmap-change","title":"Configmap change","text":"<ul> <li>should reload after an update in the configuration</li> </ul>"},{"location":"e2e-tests/#add-headers","title":"add-headers","text":"<ul> <li>Add a custom header</li> <li>Add multiple custom headers</li> </ul>"},{"location":"e2e-tests/#ssl-flag-default-ssl-certificate","title":"[SSL] [Flag] default-ssl-certificate","text":"<ul> <li>uses default ssl certificate for catch-all ingress</li> <li>uses default ssl certificate for host based ingress when configured certificate does not match host</li> </ul>"},{"location":"e2e-tests/#flag-disable-catch-all","title":"[Flag] disable-catch-all","text":"<ul> <li>should ignore catch all Ingress with backend</li> <li>should ignore catch all Ingress with backend and rules</li> <li>should delete Ingress updated to catch-all</li> <li>should allow Ingress with rules</li> </ul>"},{"location":"e2e-tests/#flag-disable-service-external-name","title":"[Flag] disable-service-external-name","text":"<ul> <li>should ignore services of external-name type</li> </ul>"},{"location":"e2e-tests/#flag-disable-sync-events","title":"[Flag] disable-sync-events","text":"<ul> <li>should create sync events (default)</li> <li>should create sync events</li> <li>should not create sync events</li> </ul>"},{"location":"e2e-tests/#enable-real-ip","title":"enable-real-ip","text":"<ul> <li>trusts X-Forwarded-For header only when setting is true</li> <li>should not trust X-Forwarded-For header when setting is false</li> </ul>"},{"location":"e2e-tests/#use-forwarded-headers","title":"use-forwarded-headers","text":"<ul> <li>should trust X-Forwarded headers when setting is true</li> <li>should not trust X-Forwarded headers when setting is false</li> </ul>"},{"location":"e2e-tests/#geoip2","title":"Geoip2","text":"<ul> <li>should include geoip2 line in config when enabled and db file exists</li> <li>should only allow requests from specific countries</li> </ul>"},{"location":"e2e-tests/#security-block-","title":"[Security] block-*","text":"<ul> <li>should block CIDRs defined in the ConfigMap</li> <li>should block User-Agents defined in the ConfigMap</li> <li>should block Referers defined in the ConfigMap</li> </ul>"},{"location":"e2e-tests/#security-global-auth-url","title":"[Security] global-auth-url","text":"<ul> <li>should return status code 401 when request any protected service</li> <li>should return status code 200 when request whitelisted (via no-auth-locations) service and 401 when request protected service</li> <li>should return status code 200 when request whitelisted (via ingress annotation) service and 401 when request protected service</li> <li>should still return status code 200 after auth backend is deleted using cache</li> <li>user retains cookie by default</li> <li>user does not retain cookie if upstream returns error status code</li> <li>user with global-auth-always-set-cookie key in configmap retains cookie if upstream returns error status code</li> </ul>"},{"location":"e2e-tests/#global-options","title":"global-options","text":"<ul> <li>should have worker_rlimit_nofile option</li> <li>should have worker_rlimit_nofile option and be independent on amount of worker processes</li> </ul>"},{"location":"e2e-tests/#settings-global-rate-limit","title":"settings-global-rate-limit","text":"<ul> <li>generates correct NGINX configuration</li> </ul>"},{"location":"e2e-tests/#gzip","title":"gzip","text":"<ul> <li>should be disabled by default</li> <li>should be enabled with default settings</li> <li>should set gzip_comp_level to 4</li> <li>should set gzip_disable to msie6</li> <li>should set gzip_min_length to 100</li> <li>should set gzip_types to text/html</li> </ul>"},{"location":"e2e-tests/#hash-size","title":"hash size","text":"<ul> <li>should set server_names_hash_bucket_size</li> <li>should set server_names_hash_max_size</li> <li>should set proxy-headers-hash-bucket-size</li> <li>should set proxy-headers-hash-max-size</li> <li>should set variables-hash-bucket-size</li> <li>should set variables-hash-max-size</li> <li>should set vmap-hash-bucket-size</li> </ul>"},{"location":"e2e-tests/#flag-ingress-class","title":"[Flag] ingress-class","text":"<ul> <li>should ignore Ingress with a different class annotation</li> <li>should ignore Ingress with different controller class</li> <li>should accept both Ingresses with default IngressClassName and IngressClass annotation</li> <li>should ignore Ingress without IngressClass configuration</li> <li>should delete Ingress when class is removed</li> <li>should serve Ingress when class is added</li> <li>should serve Ingress when class is updated between annotation and ingressClassName</li> <li>should ignore Ingress with no class and accept the correctly configured Ingresses</li> <li>should watch Ingress with no class and ignore ingress with a different class</li> <li>should watch Ingress that uses the class name even if spec is different</li> <li>should watch Ingress with correct annotation</li> <li>should ignore Ingress with only IngressClassName</li> </ul>"},{"location":"e2e-tests/#keep-alive-keep-alive-requests","title":"keep-alive keep-alive-requests","text":"<ul> <li>should set keepalive_timeout</li> <li>should set keepalive_requests</li> <li>should set keepalive connection to upstream server</li> <li>should set keep alive connection timeout to upstream server</li> <li>should set keepalive time to upstream server</li> <li>should set the request count to upstream server through one keep alive connection</li> </ul>"},{"location":"e2e-tests/#configmap-limit-rate","title":"Configmap - limit-rate","text":"<ul> <li>Check limit-rate config</li> </ul>"},{"location":"e2e-tests/#flag-custom-http-and-https-ports","title":"[Flag] custom HTTP and HTTPS ports","text":"<ul> <li>should set X-Forwarded-Port headers accordingly when listening on a non-default HTTP port</li> <li>should set X-Forwarded-Port header to 443</li> <li>should set the X-Forwarded-Port header to 443</li> </ul>"},{"location":"e2e-tests/#log-format-","title":"log-format-*","text":"<ul> <li>should not configure log-format escape by default</li> <li>should enable the log-format-escape-json</li> <li>should disable the log-format-escape-json</li> <li>should enable the log-format-escape-none</li> <li>should disable the log-format-escape-none</li> <li>log-format-escape-json enabled</li> <li>log-format default escape</li> <li>log-format-escape-none enabled</li> </ul>"},{"location":"e2e-tests/#lua-lua-shared-dicts","title":"[Lua] lua-shared-dicts","text":"<ul> <li>configures lua shared dicts</li> </ul>"},{"location":"e2e-tests/#main-snippet","title":"main-snippet","text":"<ul> <li>should add value of main-snippet setting to nginx config</li> </ul>"},{"location":"e2e-tests/#security-modsecurity-snippet","title":"[Security] modsecurity-snippet","text":"<ul> <li>should add value of modsecurity-snippet setting to nginx config</li> </ul>"},{"location":"e2e-tests/#enable-multi-accept","title":"enable-multi-accept","text":"<ul> <li>should be enabled by default</li> <li>should be enabled when set to true</li> <li>should be disabled when set to false</li> </ul>"},{"location":"e2e-tests/#flag-watch-namespace-selector","title":"[Flag] watch namespace selector","text":"<ul> <li>should ignore Ingress of namespace without label foo=bar and accept those of namespace with label foo=bar</li> </ul>"},{"location":"e2e-tests/#security-no-auth-locations","title":"[Security] no-auth-locations","text":"<ul> <li>should return status code 401 when accessing '/' unauthentication</li> <li>should return status code 200 when accessing '/'  authentication</li> <li>should return status code 200 when accessing '/noauth' unauthenticated</li> </ul>"},{"location":"e2e-tests/#add-no-tls-redirect-locations","title":"Add no tls redirect locations","text":"<ul> <li>Check no tls redirect locations config</li> </ul>"},{"location":"e2e-tests/#ocsp","title":"OCSP","text":"<ul> <li>should enable OCSP and contain stapling information in the connection</li> </ul>"},{"location":"e2e-tests/#configure-opentelemetry","title":"Configure Opentelemetry","text":"<ul> <li>should not exists opentelemetry directive</li> <li>should exists opentelemetry directive when is enabled</li> <li>should include opentelemetry_trust_incoming_spans on directive when enabled</li> <li>should not exists opentelemetry_operation_name directive when is empty</li> <li>should exists opentelemetry_operation_name directive when is configured</li> </ul>"},{"location":"e2e-tests/#plugins","title":"plugins","text":"<ul> <li>should exist a x-hello-world header</li> </ul>"},{"location":"e2e-tests/#proxy-connect-timeout","title":"proxy-connect-timeout","text":"<ul> <li>should set valid proxy timeouts using configmap values</li> <li>should not set invalid proxy timeouts using configmap values</li> </ul>"},{"location":"e2e-tests/#dynamic-proxy_host","title":"Dynamic $proxy_host","text":"<ul> <li>should exist a proxy_host</li> <li>should exist a proxy_host using the upstream-vhost annotation value</li> </ul>"},{"location":"e2e-tests/#proxy-next-upstream","title":"proxy-next-upstream","text":"<ul> <li>should build proxy next upstream using configmap values</li> </ul>"},{"location":"e2e-tests/#use-proxy-protocol","title":"use-proxy-protocol","text":"<ul> <li>should respect port passed by the PROXY Protocol</li> <li>should respect proto passed by the PROXY Protocol server port</li> <li>should enable PROXY Protocol for HTTPS</li> <li>should enable PROXY Protocol for TCP</li> </ul>"},{"location":"e2e-tests/#proxy-read-timeout","title":"proxy-read-timeout","text":"<ul> <li>should set valid proxy read timeouts using configmap values</li> <li>should not set invalid proxy read timeouts using configmap values</li> </ul>"},{"location":"e2e-tests/#proxy-send-timeout","title":"proxy-send-timeout","text":"<ul> <li>should set valid proxy send timeouts using configmap values</li> <li>should not set invalid proxy send timeouts using configmap values</li> </ul>"},{"location":"e2e-tests/#reuse-port","title":"reuse-port","text":"<ul> <li>reuse port should be enabled by default</li> <li>reuse port should be disabled</li> <li>reuse port should be enabled</li> </ul>"},{"location":"e2e-tests/#configmap-server-snippet","title":"configmap server-snippet","text":"<ul> <li>should add value of server-snippet setting to all ingress config</li> <li>should add global server-snippet and drop annotations per admin config</li> </ul>"},{"location":"e2e-tests/#server-tokens","title":"server-tokens","text":"<ul> <li>should not exists Server header in the response</li> <li>should exists Server header in the response when is enabled</li> </ul>"},{"location":"e2e-tests/#ssl-ciphers_1","title":"ssl-ciphers","text":"<ul> <li>Add ssl ciphers</li> </ul>"},{"location":"e2e-tests/#flag-enable-ssl-passthrough","title":"[Flag] enable-ssl-passthrough","text":""},{"location":"e2e-tests/#with-enable-ssl-passthrough-enabled","title":"With enable-ssl-passthrough enabled","text":"<ul> <li>should enable ssl-passthrough-proxy-port on a different port</li> <li>should pass unknown traffic to default backend and handle known traffic</li> </ul>"},{"location":"e2e-tests/#configmap-stream-snippet","title":"configmap stream-snippet","text":"<ul> <li>should add value of stream-snippet via config map to nginx config</li> </ul>"},{"location":"e2e-tests/#ssl-tls-protocols-ciphers-and-headers","title":"[SSL] TLS protocols, ciphers and headers)","text":"<ul> <li>setting cipher suite</li> <li>setting max-age parameter</li> <li>setting includeSubDomains parameter</li> <li>setting preload parameter</li> <li>overriding what's set from the upstream</li> <li>should not use ports during the HTTP to HTTPS redirection</li> <li>should not use ports or X-Forwarded-Host during the HTTP to HTTPS redirection</li> </ul>"},{"location":"e2e-tests/#annotation-validations","title":"annotation validations","text":"<ul> <li>should allow ingress based on their risk on webhooks</li> <li>should allow ingress based on their risk on webhooks</li> </ul>"},{"location":"e2e-tests/#ssl-redirect-to-https","title":"[SSL] redirect to HTTPS","text":"<ul> <li>should redirect from HTTP to HTTPS when secret is missing</li> </ul>"},{"location":"e2e-tests/#ssl-secret-update","title":"[SSL] secret update","text":"<ul> <li>should not appear references to secret updates not used in ingress rules</li> <li>should return the fake SSL certificate if the secret is invalid</li> </ul>"},{"location":"e2e-tests/#status-status-update","title":"[Status] status update","text":"<ul> <li>should update status field after client-go reconnection</li> </ul>"},{"location":"e2e-tests/#tcp-tcp-services","title":"[TCP] tcp-services","text":"<ul> <li>should expose a TCP service</li> <li>should expose an ExternalName TCP service</li> <li>should reload after an update in the configuration</li> </ul>"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#retaining-client-ipaddress","title":"Retaining Client IPAddress","text":"<p>Please read Retain Client IPAddress Guide here.</p>"},{"location":"faq/#kubernetes-v122-migration","title":"Kubernetes v1.22 Migration","text":"<p>If you are using Ingress objects in your cluster (running Kubernetes older than version 1.22), and you plan to upgrade your Kubernetes version to K8S 1.22 or above, then please read the migration guide here.</p>"},{"location":"faq/#validation-of-path","title":"Validation Of <code>path</code>","text":"<ul> <li> <p>For improving security and also following desired standards on Kubernetes API spec, the next release, scheduled for v1.8.0, will include a new &amp; optional feature of validating the value for the key <code>ingress.spec.rules.http.paths.path</code>.</p> </li> <li> <p>This behavior will be disabled by default on the 1.8.0 release and enabled by default on the next breaking change release, set for 2.0.0.</p> </li> <li> <p>When \"<code>ingress.spec.rules.http.pathType=Exact</code>\" or \"<code>pathType=Prefix</code>\", this validation will limit the characters accepted on the field \"<code>ingress.spec.rules.http.paths.path</code>\", to \"<code>alphanumeric characters</code>\", and  <code>\"/,\" \"_,\" \"-.\"</code> Also, in this case, the path should start with <code>\"/.\"</code></p> </li> <li> <p>When the ingress resource path contains other characters (like on rewrite configurations), the pathType value should be \"<code>ImplementationSpecific</code>\".</p> </li> <li> <p>API Spec on pathType is documented here</p> </li> <li> <p>When this option is enabled, the validation will happen on the Admission Webhook. So if any new ingress object contains characters other than alphanumeric characters, and, <code>\"/,\",\"_\",\"-\"</code>, in the <code>path</code> field, but is not using <code>pathType</code> value as <code>ImplementationSpecific</code>, then the ingress object will be denied admission.</p> </li> <li> <p>The cluster admin should establish validation rules using mechanisms like \"<code>Open Policy Agent</code>\", to validate that only authorized users can use ImplementationSpecific pathType and that only the authorized characters can be used. The configmap value is here</p> </li> <li> <p>A complete example of an Openpolicyagent gatekeeper rule is available here</p> </li> <li> <p>If you have any issues or concerns, please do one of the following:</p> </li> <li>Open a GitHub issue</li> <li>Comment in our Dev Slack Channel</li> <li>Open a thread in our Google Group ingress-nginx-dev@kubernetes.io</li> </ul>"},{"location":"faq/#why-is-chunking-not-working-since-controller-v110","title":"Why is chunking not working since controller v1.10 ?","text":"<ul> <li> <p>If your code is setting the HTTP header <code>\"Transfer-Encoding: chunked\"</code> and the controller log messages show an error about duplicate header, it is because of this change http://hg.nginx.org/nginx/rev/2bf7792c262e</p> </li> <li> <p>More details are available in this issue https://github.com/kubernetes/ingress-nginx/issues/11162</p> </li> </ul>"},{"location":"how-it-works/","title":"How it works","text":"<p>The objective of this document is to explain how the Ingress-NGINX controller works, in particular how the NGINX model is built and why we need one.</p>"},{"location":"how-it-works/#nginx-configuration","title":"NGINX configuration","text":"<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. Though it is important to note that we don't reload Nginx on changes that impact only an <code>upstream</code> configuration (i.e Endpoints change when you deploy your app). We use lua-nginx-module to achieve this. Check below to learn more about how it's done.</p>"},{"location":"how-it-works/#nginx-model","title":"NGINX model","text":"<p>Usually, a Kubernetes Controller utilizes the synchronization loop pattern 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 Kubernetes Informers, in particular, <code>FilteredSharedInformer</code>. These informers allow reacting to change in using callbacks 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 Go template using the new model as input for the variables required by the template.</p>"},{"location":"how-it-works/#building-the-nginx-model","title":"Building the NGINX model","text":"<p>Building a model is an expensive operation, for this reason, the use of the synchronization loop is a must. By using a work queue it is possible to not lose changes and remove the use of sync.Mutex 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 work queue.</p> <p>Operations to build the model:</p> <ul> <li> <p>Order Ingress rules by <code>CreationTimestamp</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> </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>"},{"location":"how-it-works/#when-a-reload-is-required","title":"When a reload is required","text":"<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>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>"},{"location":"how-it-works/#avoiding-reloads","title":"Avoiding reloads","text":"<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>"},{"location":"how-it-works/#avoiding-reloads-on-endpoints-changes","title":"Avoiding reloads on Endpoints changes","text":"<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 <code>balancer_by_lua</code> 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. Note that this includes annotation changes that affects only <code>upstream</code> configuration in Nginx as well.</p> <p>In a relatively big cluster 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>"},{"location":"how-it-works/#avoiding-outage-from-wrong-configuration","title":"Avoiding outage from wrong configuration","text":"<p>Because the ingress controller works using the synchronization loop pattern, 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>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>To prevent this situation to happen, the Ingress-Nginx Controller optionally exposes a validating admission webhook server 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>"},{"location":"kubectl-plugin/","title":"kubectl plugin","text":""},{"location":"kubectl-plugin/#the-ingress-nginx-kubectl-plugin","title":"The ingress-nginx kubectl plugin","text":""},{"location":"kubectl-plugin/#installation","title":"Installation","text":"<p>Install krew, then run</p> <pre><code>kubectl krew install ingress-nginx\n</code></pre> <p>to install the plugin. Then run</p> <pre><code>kubectl ingress-nginx --help\n</code></pre> <p>to make sure the plugin is properly installed and to get a list of commands:</p> <pre><code>kubectl ingress-nginx --help\nA kubectl plugin for inspecting your ingress-nginx deployments\n\nUsage:\n  ingress-nginx [command]\n\nAvailable Commands:\n  backends    Inspect the dynamic backend information of an ingress-nginx instance\n  certs       Output the certificate data stored in an ingress-nginx pod\n  conf        Inspect the generated nginx.conf\n  exec        Execute a command inside an ingress-nginx pod\n  general     Inspect the other dynamic ingress-nginx information\n  help        Help about any command\n  info        Show information about the ingress-nginx service\n  ingresses   Provide a short summary of all of the ingress definitions\n  lint        Inspect kubernetes resources for possible issues\n  logs        Get the kubernetes logs for an ingress-nginx pod\n  ssh         ssh into a running ingress-nginx pod\n\nFlags:\n      --as string                      Username to impersonate for the operation\n      --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.\n      --cache-dir string               Default HTTP cache directory (default \"/Users/alexkursell/.kube/http-cache\")\n      --certificate-authority string   Path to a cert file for the certificate authority\n      --client-certificate string      Path to a client certificate file for TLS\n      --client-key string              Path to a client key file for TLS\n      --cluster string                 The name of the kubeconfig cluster to use\n      --context string                 The name of the kubeconfig context to use\n  -h, --help                           help for ingress-nginx\n      --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.\n  -n, --namespace string               If present, the namespace scope for this CLI request\n      --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default \"0\")\n  -s, --server string                  The address and port of the Kubernetes API server\n      --token string                   Bearer token for authentication to the API server\n      --user string                    The name of the kubeconfig user to use\n\nUse \"ingress-nginx [command] --help\" for more information about a command.\n</code></pre>"},{"location":"kubectl-plugin/#common-flags","title":"Common Flags","text":"<ul> <li>Every subcommand supports the basic <code>kubectl</code> configuration flags like <code>--namespace</code>, <code>--context</code>, <code>--client-key</code> and so on.</li> <li>Subcommands that act on a particular <code>ingress-nginx</code> pod (<code>backends</code>, <code>certs</code>, <code>conf</code>, <code>exec</code>, <code>general</code>, <code>logs</code>, <code>ssh</code>), support the <code>--deployment &lt;deployment&gt;</code>, <code>--pod &lt;pod&gt;</code>, and <code>--container &lt;container&gt;</code> flags to select either a pod from a deployment with the given name, or a pod with the given name (and the given container name). The <code>--deployment</code> flag defaults to <code>ingress-nginx-controller</code>, and the <code>--container</code> flag defaults to <code>controller</code>.</li> <li>Subcommands that inspect resources (<code>ingresses</code>, <code>lint</code>) support the <code>--all-namespaces</code> flag, which causes them to inspect resources in every namespace.</li> </ul>"},{"location":"kubectl-plugin/#subcommands","title":"Subcommands","text":"<p>Note that <code>backends</code>, <code>general</code>, <code>certs</code>, and <code>conf</code> require <code>ingress-nginx</code> version <code>0.23.0</code> or higher.</p>"},{"location":"kubectl-plugin/#backends","title":"backends","text":"<p>Run <code>kubectl ingress-nginx backends</code> to get a JSON array of the backends that an ingress-nginx controller currently knows about:</p> <pre><code>$ kubectl ingress-nginx backends -n ingress-nginx\n[\n  {\n    \"name\": \"default-apple-service-5678\",\n    \"service\": {\n      \"metadata\": {\n        \"creationTimestamp\": null\n      },\n      \"spec\": {\n        \"ports\": [\n          {\n            \"protocol\": \"TCP\",\n            \"port\": 5678,\n            \"targetPort\": 5678\n          }\n        ],\n        \"selector\": {\n          \"app\": \"apple\"\n        },\n        \"clusterIP\": \"10.97.230.121\",\n        \"type\": \"ClusterIP\",\n        \"sessionAffinity\": \"None\"\n      },\n      \"status\": {\n        \"loadBalancer\": {}\n      }\n    },\n    \"port\": 0,\n    \"sslPassthrough\": false,\n    \"endpoints\": [\n      {\n        \"address\": \"10.1.3.86\",\n        \"port\": \"5678\"\n      }\n    ],\n    \"sessionAffinityConfig\": {\n      \"name\": \"\",\n      \"cookieSessionAffinity\": {\n        \"name\": \"\"\n      }\n    },\n    \"upstreamHashByConfig\": {\n      \"upstream-hash-by-subset-size\": 3\n    },\n    \"noServer\": false,\n    \"trafficShapingPolicy\": {\n      \"weight\": 0,\n      \"header\": \"\",\n      \"headerValue\": \"\",\n      \"cookie\": \"\"\n    }\n  },\n  {\n    \"name\": \"default-echo-service-8080\",\n    ...\n  },\n  {\n    \"name\": \"upstream-default-backend\",\n    ...\n  }\n]\n</code></pre> <p>Add the <code>--list</code> option to show only the backend names. Add the <code>--backend &lt;backend&gt;</code> option to show only the backend with the given name.</p>"},{"location":"kubectl-plugin/#certs","title":"certs","text":"<p>Use <code>kubectl ingress-nginx certs --host &lt;hostname&gt;</code> to dump the SSL cert/key information for a given host.</p> <p>WARNING: This command will dump sensitive private key information. Don't blindly share the output, and certainly don't log it anywhere.</p> <pre><code>$ kubectl ingress-nginx certs -n ingress-nginx --host testaddr.local\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n\n-----BEGIN RSA PRIVATE KEY-----\n&lt;REDACTED! DO NOT SHARE THIS!&gt;\n-----END RSA PRIVATE KEY-----\n</code></pre>"},{"location":"kubectl-plugin/#conf","title":"conf","text":"<p>Use <code>kubectl ingress-nginx conf</code> to dump the generated <code>nginx.conf</code> file. Add the <code>--host &lt;hostname&gt;</code> option to view only the server block for that host:</p> <pre><code>kubectl ingress-nginx conf -n ingress-nginx --host testaddr.local\n\n    server {\n        server_name testaddr.local ;\n\n        listen 80;\n\n        set $proxy_upstream_name \"-\";\n        set $pass_access_scheme $scheme;\n        set $pass_server_port $server_port;\n        set $best_http_host $http_host;\n        set $pass_port $pass_server_port;\n\n        location / {\n\n            set $namespace      \"\";\n            set $ingress_name   \"\";\n            set $service_name   \"\";\n            set $service_port   \"0\";\n            set $location_path  \"/\";\n\n...\n</code></pre>"},{"location":"kubectl-plugin/#exec","title":"exec","text":"<p><code>kubectl ingress-nginx exec</code> is exactly the same as <code>kubectl exec</code>, with the same command flags. It will automatically choose an <code>ingress-nginx</code> pod to run the command in.</p> <pre><code>$ kubectl ingress-nginx exec -i -n ingress-nginx -- ls /etc/nginx\nfastcgi_params\ngeoip\nlua\nmime.types\nmodsecurity\nmodules\nnginx.conf\nopentracing.json\nopentelemetry.toml\nowasp-modsecurity-crs\ntemplate\n</code></pre>"},{"location":"kubectl-plugin/#info","title":"info","text":"<p>Shows the internal and external IP/CNAMES for an <code>ingress-nginx</code> service.</p> <pre><code>$ kubectl ingress-nginx info -n ingress-nginx\nService cluster IP address: 10.187.253.31\nLoadBalancer IP|CNAME: 35.123.123.123\n</code></pre> <p>Use the <code>--service &lt;service&gt;</code> flag if your <code>ingress-nginx</code> <code>LoadBalancer</code> service is not named <code>ingress-nginx</code>.</p>"},{"location":"kubectl-plugin/#ingresses","title":"ingresses","text":"<p><code>kubectl ingress-nginx ingresses</code>, alternately <code>kubectl ingress-nginx ing</code>, shows a more detailed view of the ingress definitions in a namespace.</p> <p>Compare:</p> <pre><code>$ kubectl get ingresses --all-namespaces\nNAMESPACE   NAME               HOSTS                            ADDRESS     PORTS   AGE\ndefault     example-ingress1   testaddr.local,testaddr2.local   localhost   80      5d\ndefault     test-ingress-2     *                                localhost   80      5d\n</code></pre> <p>vs.</p> <pre><code>$ kubectl ingress-nginx ingresses --all-namespaces\nNAMESPACE   INGRESS NAME       HOST+PATH                        ADDRESSES   TLS   SERVICE         SERVICE PORT   ENDPOINTS\ndefault     example-ingress1   testaddr.local/etameta           localhost   NO    pear-service    5678           5\ndefault     example-ingress1   testaddr2.local/otherpath        localhost   NO    apple-service   5678           1\ndefault     example-ingress1   testaddr2.local/otherotherpath   localhost   NO    pear-service    5678           5\ndefault     test-ingress-2     *                                localhost   NO    echo-service    8080           2\n</code></pre>"},{"location":"kubectl-plugin/#lint","title":"lint","text":"<p><code>kubectl ingress-nginx lint</code> can check a namespace or entire cluster for potential configuration issues. This command is especially useful when upgrading between <code>ingress-nginx</code> versions.</p> <pre><code>$ kubectl ingress-nginx lint --all-namespaces --verbose\nChecking ingresses...\n\u2717 anamespace/this-nginx\n  - Contains the removed session-cookie-hash annotation.\n       Lint added for version 0.24.0\n       https://github.com/kubernetes/ingress-nginx/issues/3743\n\u2717 othernamespace/ingress-definition-blah\n  - The rewrite-target annotation value does not reference a capture group\n      Lint added for version 0.22.0\n      https://github.com/kubernetes/ingress-nginx/issues/3174\n\nChecking deployments...\n\u2717 namespace2/ingress-nginx-controller\n  - Uses removed config flag --sort-backends\n      Lint added for version 0.22.0\n      https://github.com/kubernetes/ingress-nginx/issues/3655\n  - Uses removed config flag --enable-dynamic-certificates\n      Lint added for version 0.24.0\n      https://github.com/kubernetes/ingress-nginx/issues/3808\n</code></pre> <p>To show the lints added only for a particular <code>ingress-nginx</code> release, use the <code>--from-version</code> and <code>--to-version</code> flags:</p> <pre><code>$ kubectl ingress-nginx lint --all-namespaces --verbose --from-version 0.24.0 --to-version 0.24.0\nChecking ingresses...\n\u2717 anamespace/this-nginx\n  - Contains the removed session-cookie-hash annotation.\n       Lint added for version 0.24.0\n       https://github.com/kubernetes/ingress-nginx/issues/3743\n\nChecking deployments...\n\u2717 namespace2/ingress-nginx-controller\n  - Uses removed config flag --enable-dynamic-certificates\n      Lint added for version 0.24.0\n      https://github.com/kubernetes/ingress-nginx/issues/3808\n</code></pre>"},{"location":"kubectl-plugin/#logs","title":"logs","text":"<p><code>kubectl ingress-nginx logs</code> is almost the same as <code>kubectl logs</code>, with fewer flags. It will automatically choose an <code>ingress-nginx</code> pod to read logs from.</p> <pre><code>$ kubectl ingress-nginx logs -n ingress-nginx\n-------------------------------------------------------------------------------\nNGINX Ingress controller\n  Release:    dev\n  Build:      git-48dc3a867\n  Repository: git@github.com:kubernetes/ingress-nginx.git\n-------------------------------------------------------------------------------\n\nW0405 16:53:46.061589       7 flags.go:214] SSL certificate chain completion is disabled (--enable-ssl-chain-completion=false)\nnginx version: nginx/1.15.9\nW0405 16:53:46.070093       7 client_config.go:549] Neither --kubeconfig nor --master was specified.  Using the inClusterConfig.  This might not work.\nI0405 16:53:46.070499       7 main.go:205] Creating API client for https://10.96.0.1:443\nI0405 16:53:46.077784       7 main.go:249] Running in Kubernetes cluster version v1.10 (v1.10.11) - git (clean) commit 637c7e288581ee40ab4ca210618a89a555b6e7e9 - platform linux/amd64\nI0405 16:53:46.183359       7 nginx.go:265] Starting NGINX Ingress controller\nI0405 16:53:46.193913       7 event.go:209] Event(v1.ObjectReference{Kind:\"ConfigMap\", Namespace:\"ingress-nginx\", Name:\"udp-services\", UID:\"82258915-563e-11e9-9c52-025000000001\", APIVersion:\"v1\", ResourceVersion:\"494\", FieldPath:\"\"}): type: 'Normal' reason: 'CREATE' ConfigMap ingress-nginx/udp-services\n...\n</code></pre>"},{"location":"kubectl-plugin/#ssh","title":"ssh","text":"<p><code>kubectl ingress-nginx ssh</code> is exactly the same as <code>kubectl ingress-nginx exec -it -- /bin/bash</code>. Use it when you want to quickly be dropped into a shell inside a running <code>ingress-nginx</code> container.</p> <pre><code>$ kubectl ingress-nginx ssh -n ingress-nginx\nwww-data@ingress-nginx-controller-7cbf77c976-wx5pn:/etc/nginx$\n</code></pre>"},{"location":"lua_tests/","title":"Lua Tests","text":""},{"location":"lua_tests/#running-the-lua-tests","title":"Running the Lua Tests","text":"<p>To run the Lua tests you can run the following from the root directory:</p> <pre><code>make lua-test\n</code></pre> <p>This command makes use of docker hence does not need any dependency installations besides docker</p>"},{"location":"lua_tests/#where-are-the-lua-tests","title":"Where are the Lua Tests?","text":"<p>Lua Tests can be found in the rootfs/etc/nginx/lua/test directory</p>"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#troubleshooting","title":"Troubleshooting","text":""},{"location":"troubleshooting/#ingress-controller-logs-and-events","title":"Ingress-Controller Logs and Events","text":"<p>There are many ways to troubleshoot the ingress-controller. The following are basic troubleshooting methods to obtain more information.</p>"},{"location":"troubleshooting/#check-the-ingress-resource-events","title":"Check the Ingress Resource Events","text":"<pre><code>$ kubectl get ing -n &lt;namespace-of-ingress-resource&gt;\nNAME           HOSTS      ADDRESS     PORTS     AGE\ncafe-ingress   cafe.com   10.0.2.15   80        25s\n\n$ kubectl describe ing &lt;ingress-resource-name&gt; -n &lt;namespace-of-ingress-resource&gt;\nName:             cafe-ingress\nNamespace:        default\nAddress:          10.0.2.15\nDefault backend:  default-http-backend:80 (172.17.0.5:8080)\nRules:\n  Host      Path  Backends\n  ----      ----  --------\n  cafe.com\n            /tea      tea-svc:80 (&lt;none&gt;)\n            /coffee   coffee-svc:80 (&lt;none&gt;)\nAnnotations:\n  kubectl.kubernetes.io/last-applied-configuration:  {\"apiVersion\":\"networking.k8s.io/v1\",\"kind\":\"Ingress\",\"metadata\":{\"annotations\":{},\"name\":\"cafe-ingress\",\"namespace\":\"default\",\"selfLink\":\"/apis/networking/v1/namespaces/default/ingresses/cafe-ingress\"},\"spec\":{\"rules\":[{\"host\":\"cafe.com\",\"http\":{\"paths\":[{\"backend\":{\"serviceName\":\"tea-svc\",\"servicePort\":80},\"path\":\"/tea\"},{\"backend\":{\"serviceName\":\"coffee-svc\",\"servicePort\":80},\"path\":\"/coffee\"}]}}]},\"status\":{\"loadBalancer\":{\"ingress\":[{\"ip\":\"169.48.142.110\"}]}}}\n\nEvents:\n  Type    Reason  Age   From                      Message\n  ----    ------  ----  ----                      -------\n  Normal  CREATE  1m    ingress-nginx-controller  Ingress default/cafe-ingress\n  Normal  UPDATE  58s   ingress-nginx-controller  Ingress default/cafe-ingress\n</code></pre>"},{"location":"troubleshooting/#check-the-ingress-controller-logs","title":"Check the Ingress Controller Logs","text":"<pre><code>$ kubectl get pods -n &lt;namespace-of-ingress-controller&gt;\nNAME                                        READY     STATUS    RESTARTS   AGE\ningress-nginx-controller-67956bf89d-fv58j   1/1       Running   0          1m\n\n$ kubectl logs -n &lt;namespace&gt; ingress-nginx-controller-67956bf89d-fv58j\n-------------------------------------------------------------------------------\nNGINX Ingress controller\n  Release:    0.14.0\n  Build:      git-734361d\n  Repository: https://github.com/kubernetes/ingress-nginx\n-------------------------------------------------------------------------------\n....\n</code></pre>"},{"location":"troubleshooting/#check-the-nginx-configuration","title":"Check the Nginx Configuration","text":"<pre><code>$ kubectl get pods -n &lt;namespace-of-ingress-controller&gt;\nNAME                                        READY     STATUS    RESTARTS   AGE\ningress-nginx-controller-67956bf89d-fv58j   1/1       Running   0          1m\n\n$ kubectl exec -it -n &lt;namespace-of-ingress-controller&gt; ingress-nginx-controller-67956bf89d-fv58j -- cat /etc/nginx/nginx.conf\ndaemon off;\nworker_processes 2;\npid /run/nginx.pid;\nworker_rlimit_nofile 523264;\nworker_shutdown_timeout 240s;\nevents {\n    multi_accept        on;\n    worker_connections  16384;\n    use                 epoll;\n}\nhttp {\n....\n</code></pre>"},{"location":"troubleshooting/#check-if-used-services-exist","title":"Check if used Services Exist","text":"<pre><code>$ kubectl get svc --all-namespaces\nNAMESPACE     NAME                   TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)         AGE\ndefault       coffee-svc             ClusterIP   10.106.154.35    &lt;none&gt;        80/TCP          18m\ndefault       kubernetes             ClusterIP   10.96.0.1        &lt;none&gt;        443/TCP         30m\ndefault       tea-svc                ClusterIP   10.104.172.12    &lt;none&gt;        80/TCP          18m\nkube-system   default-http-backend   NodePort    10.108.189.236   &lt;none&gt;        80:30001/TCP    30m\nkube-system   kube-dns               ClusterIP   10.96.0.10       &lt;none&gt;        53/UDP,53/TCP   30m\nkube-system   kubernetes-dashboard   NodePort    10.103.128.17    &lt;none&gt;        80:30000/TCP    30m\n</code></pre>"},{"location":"troubleshooting/#debug-logging","title":"Debug Logging","text":"<p>Using the flag <code>--v=XX</code> it is possible to increase the level of logging. This is performed by editing the deployment.</p> <pre><code>$ kubectl get deploy -n &lt;namespace-of-ingress-controller&gt;\nNAME                       DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE\ndefault-http-backend       1         1         1            1           35m\ningress-nginx-controller   1         1         1            1           35m\n\n$ kubectl edit deploy -n &lt;namespace-of-ingress-controller&gt; ingress-nginx-controller\n# Add --v=X to \"- args\", where X is an integer\n</code></pre> <ul> <li><code>--v=2</code> shows details using <code>diff</code> about the changes in the configuration in nginx</li> <li><code>--v=3</code> shows details about the service, Ingress rule, endpoint changes and it dumps the nginx configuration in JSON format</li> <li><code>--v=5</code> configures NGINX in debug mode</li> </ul>"},{"location":"troubleshooting/#authentication-to-the-kubernetes-api-server","title":"Authentication to the Kubernetes API Server","text":"<p>A number of components are involved in the authentication process and the first step is to narrow down the source of the problem, namely whether it is a problem with service authentication or with the kubeconfig file.</p> <p>Both authentications must work:</p> <pre><code>+-------------+   service          +------------+\n|             |   authentication   |            |\n+  apiserver  +&lt;-------------------+  ingress   |\n|             |                    | controller |\n+-------------+                    +------------+\n</code></pre> <p>Service authentication</p> <p>The Ingress controller needs information from apiserver. Therefore, authentication is required, which can be achieved in a couple of ways:</p> <ul> <li> <p>Service Account: This is recommended, because nothing has to be configured. The Ingress controller will use information provided by the system to communicate with the API server. See 'Service Account' section for details.</p> </li> <li> <p>Kubeconfig file: In some Kubernetes environments service accounts are not available. In this case a manual configuration is required. The Ingress controller binary can be started with the <code>--kubeconfig</code> flag. The value of the flag is a path to a file specifying how to connect to the API server. Using the <code>--kubeconfig</code> does not requires the flag <code>--apiserver-host</code>.    The format of the file is identical to <code>~/.kube/config</code> which is used by kubectl to connect to the API server. See 'kubeconfig' section for details.</p> </li> <li> <p>Using the flag <code>--apiserver-host</code>: Using this flag <code>--apiserver-host=http://localhost:8080</code> it is possible to specify an unsecured API server or reach a remote kubernetes cluster using kubectl proxy.    Please do not use this approach in production.</p> </li> </ul> <p>In the diagram below you can see the full authentication flow with all options, starting with the browser on the lower left hand side.</p> <pre><code>Kubernetes                                                  Workstation\n+---------------------------------------------------+     +------------------+\n|                                                   |     |                  |\n|  +-----------+   apiserver        +------------+  |     |  +------------+  |\n|  |           |   proxy            |            |  |     |  |            |  |\n|  | apiserver |                    |  ingress   |  |     |  |  ingress   |  |\n|  |           |                    | controller |  |     |  | controller |  |\n|  |           |                    |            |  |     |  |            |  |\n|  |           |                    |            |  |     |  |            |  |\n|  |           |  service account/  |            |  |     |  |            |  |\n|  |           |  kubeconfig        |            |  |     |  |            |  |\n|  |           +&lt;-------------------+            |  |     |  |            |  |\n|  |           |                    |            |  |     |  |            |  |\n|  +------+----+      kubeconfig    +------+-----+  |     |  +------+-----+  |\n|         |&lt;--------------------------------------------------------|        |\n|                                                   |     |                  |\n+---------------------------------------------------+     +------------------+\n</code></pre>"},{"location":"troubleshooting/#service-account","title":"Service Account","text":"<p>If using a service account to connect to the API server, the ingress-controller expects the file <code>/var/run/secrets/kubernetes.io/serviceaccount/token</code> to be present. It provides a secret token that is required to authenticate with the API server.</p> <p>Verify with the following commands:</p> <pre><code># start a container that contains curl\n$ kubectl run -it --rm test --image=curlimages/curl --restart=Never -- /bin/sh\n\n# check if secret exists\n/ $ ls /var/run/secrets/kubernetes.io/serviceaccount/\nca.crt     namespace  token\n/ $\n\n# check base connectivity from cluster inside\n/ $ curl -k https://kubernetes.default.svc.cluster.local\n{\n  \"kind\": \"Status\",\n  \"apiVersion\": \"v1\",\n  \"metadata\": {\n\n  },\n  \"status\": \"Failure\",\n  \"message\": \"forbidden: User \\\"system:anonymous\\\" cannot get path \\\"/\\\"\",\n  \"reason\": \"Forbidden\",\n  \"details\": {\n\n  },\n  \"code\": 403\n}/ $\n\n# connect using tokens\n}/ $ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt -H  \"Authorization: Bearer $(cat /var/run/secrets/kubernetes.io/serviceaccount/token)\" https://kubernetes.default.svc.cluster.local\n&amp;&amp; echo\n{\n  \"paths\": [\n    \"/api\",\n    \"/api/v1\",\n    \"/apis\",\n    \"/apis/\",\n    ... TRUNCATED\n    \"/readyz/shutdown\",\n    \"/version\"\n  ]\n}\n/ $\n\n# when you type `exit` or `^D` the test pod will be deleted.\n</code></pre> <p>If it is not working, there are two possible reasons:</p> <ol> <li> <p>The contents of the tokens are invalid. Find the secret name with <code>kubectl get secrets | grep service-account</code> and    delete it with <code>kubectl delete secret &lt;name&gt;</code>. It will automatically be recreated.</p> </li> <li> <p>You have a non-standard Kubernetes installation and the file containing the token may not be present.    The API server will mount a volume containing this file, but only if the API server is configured to use    the ServiceAccount admission controller.    If you experience this error, verify that your API server is using the ServiceAccount admission controller.    If you are configuring the API server by hand, you can set this with the <code>--admission-control</code> parameter.</p> <p>Note that you should use other admission controllers as well. Before configuring this option, you should read about admission controllers.</p> </li> </ol> <p>More information:</p> <ul> <li>User Guide: Service Accounts</li> <li>Cluster Administrator Guide: Managing Service Accounts</li> </ul>"},{"location":"troubleshooting/#kube-config","title":"Kube-Config","text":"<p>If you want to use a kubeconfig file for authentication, follow the deploy procedure and add the flag <code>--kubeconfig=/etc/kubernetes/kubeconfig.yaml</code> to the args section of the deployment.</p>"},{"location":"troubleshooting/#using-gdb-with-nginx","title":"Using GDB with Nginx","text":"<p>Gdb can be used to with nginx to perform a configuration dump. This allows us to see which configuration is being used, as well as older configurations.</p> <p>Note: The below is based on the nginx documentation.</p> <ol> <li> <p>SSH into the worker</p> <pre><code>$ ssh user@workerIP\n</code></pre> </li> <li> <p>Obtain the Docker Container Running nginx</p> <pre><code>$ docker ps | grep ingress-nginx-controller\nCONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES\nd9e1d243156a        registry.k8s.io/ingress-nginx/controller   \"/usr/bin/dumb-init \u2026\"   19 minutes ago      Up 19 minutes                                                                            k8s_ingress-nginx-controller_ingress-nginx-controller-67956bf89d-mqxzt_kube-system_079f31ec-aa37-11e8-ad39-080027a227db_0\n</code></pre> </li> <li> <p>Exec into the container</p> <pre><code>$ docker exec -it --user=0 --privileged d9e1d243156a bash\n</code></pre> </li> <li> <p>Make sure nginx is running in <code>--with-debug</code></p> <pre><code>$ nginx -V 2&gt;&amp;1 | grep -- '--with-debug'\n</code></pre> </li> <li> <p>Get list of processes running on container</p> <pre><code>$ ps -ef\nUID        PID  PPID  C STIME TTY          TIME CMD\nroot         1     0  0 20:23 ?        00:00:00 /usr/bin/dumb-init /nginx-ingres\nroot         5     1  0 20:23 ?        00:00:05 /ingress-nginx-controller --defa\nroot        21     5  0 20:23 ?        00:00:00 nginx: master process /usr/sbin/\nnobody     106    21  0 20:23 ?        00:00:00 nginx: worker process\nnobody     107    21  0 20:23 ?        00:00:00 nginx: worker process\nroot       172     0  0 20:43 pts/0    00:00:00 bash\n</code></pre> </li> <li> <p>Attach gdb to the nginx master process</p> <pre><code>$ gdb -p 21\n....\nAttaching to process 21\nReading symbols from /usr/sbin/nginx...done.\n....\n(gdb)\n</code></pre> </li> <li> <p>Copy and paste the following:</p> <pre><code>set $cd = ngx_cycle-&gt;config_dump\nset $nelts = $cd.nelts\nset $elts = (ngx_conf_dump_t*)($cd.elts)\nwhile ($nelts-- &gt; 0)\nset $name = $elts[$nelts]-&gt;name.data\nprintf \"Dumping %s to nginx_conf.txt\\n\", $name\nappend memory nginx_conf.txt \\\n        $elts[$nelts]-&gt;buffer.start $elts[$nelts]-&gt;buffer.end\nend\n</code></pre> </li> <li> <p>Quit GDB by pressing CTRL+D</p> </li> <li> <p>Open nginx_conf.txt</p> <pre><code>cat nginx_conf.txt\n</code></pre> </li> </ol>"},{"location":"troubleshooting/#image-related-issues-faced-on-nginx-425-or-other-versions-helm-chart-versions","title":"Image related issues faced on Nginx 4.2.5 or other versions (Helm chart versions)","text":"<ol> <li> <p>Incase you face below error while installing Nginx using helm chart (either by helm commands or helm_release terraform provider )  <pre><code>Warning  Failed     5m5s (x4 over 6m34s)   kubelet            Failed to pull image \"registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.3.0@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": rpc error: code = Unknown desc = failed to pull and unpack image \"registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": failed to resolve reference \"registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": failed to do request: Head \"https://eu.gcr.io/v2/k8s-artifacts-prod/ingress-nginx/kube-webhook-certgen/manifests/sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": EOF\n</code></pre>    Then please follow the below steps.</p> </li> <li> <p>During troubleshooting you can also execute the below commands to test the connectivities from you local machines and repositories  details</p> <p>a. curl registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47 &gt; /dev/null   <pre><code>(\u2388 |myprompt)\u279c  ~ curl registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47 &gt; /dev/null\n                    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n                                                    Dload  Upload   Total   Spent    Left  Speed\n                    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\n (\u2388 |myprompt)\u279c  ~\n</code></pre>   b. curl -I https://eu.gcr.io/v2/k8s-artifacts-prod/ingress-nginx/kube-webhook-certgen/manifests/sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47   <pre><code>(\u2388 |myprompt)\u279c  ~ curl -I https://eu.gcr.io/v2/k8s-artifacts-prod/ingress-nginx/kube-webhook-certgen/manifests/sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\n                                    HTTP/2 200\n                                    docker-distribution-api-version: registry/2.0\n                                    content-type: application/vnd.docker.distribution.manifest.list.v2+json\n                                    docker-content-digest: sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\n                                    content-length: 1384\n                                    date: Wed, 28 Sep 2022 16:46:28 GMT\n                                    server: Docker Registry\n                                    x-xss-protection: 0\n                                    x-frame-options: SAMEORIGIN\n                                    alt-svc: h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"\n\n  (\u2388 |myprompt)\u279c  ~\n</code></pre>    Redirection in the proxy is implemented to ensure the pulling of the images.</p> </li> <li> <p>This is the solution recommended to whitelist the below image repositories :       <pre><code>*.appspot.com    \n*.k8s.io        \n*.pkg.dev\n*.gcr.io\n</code></pre>      More details about the above repos :       a. *.k8s.io -&gt; To ensure you can pull any images from registry.k8s.io      b. *.gcr.io -&gt; GCP services are used for image hosting. This is part of the domains suggested by GCP to allow and ensure users can pull images from their container registry services.      c. *.appspot.com -&gt; This a Google domain. part of the domain used for GCR.</p> </li> </ol>"},{"location":"troubleshooting/#unable-to-listen-on-port-80443","title":"Unable to listen on port (80/443)","text":"<p>One possible reason for this error is lack of permission to bind to the port.  Ports 80, 443, and any other port &lt; 1024 are Linux privileged ports which historically could only be bound by root.  The ingress-nginx-controller uses the CAP_NET_BIND_SERVICE linux capability to allow binding these ports as a normal user (www-data / 101).  This involves two components: 1. In the image, the /nginx-ingress-controller file has the cap_net_bind_service capability added (e.g. via setcap)  2. The NET_BIND_SERVICE capability is added to the container in the containerSecurityContext of the deployment.</p> <p>If encountering this on one/some node(s) and not on others, try to purge and pull a fresh copy of the image to the affected node(s), in case there has been corruption of the underlying layers to lose the capability on the executable.</p>"},{"location":"troubleshooting/#create-a-test-pod","title":"Create a test pod","text":"<p>The /nginx-ingress-controller process exits/crashes when encountering this error, making it difficult to troubleshoot what is happening inside the container.  To get around this, start an equivalent container running \"sleep 3600\", and exec into it for further troubleshooting.  For example: <pre><code>apiVersion: v1\nkind: Pod\nmetadata:\n  name: ingress-nginx-sleep\n  namespace: default\n  labels:\n    app: nginx\nspec:\n  containers:\n    - name: nginx\n      image: ##_CONTROLLER_IMAGE_##\n      resources:\n        requests:\n          memory: \"512Mi\"\n          cpu: \"500m\"\n        limits:\n          memory: \"1Gi\"\n          cpu: \"1\"\n      command: [\"sleep\"]\n      args: [\"3600\"]\n      ports:\n      - containerPort: 80\n        name: http\n        protocol: TCP\n      - containerPort: 443\n        name: https\n        protocol: TCP\n      securityContext:\n        allowPrivilegeEscalation: true\n        capabilities:\n          add:\n          - NET_BIND_SERVICE\n          drop:\n          - ALL\n        runAsUser: 101\n  restartPolicy: Never\n  nodeSelector:\n    kubernetes.io/hostname: ##_NODE_NAME_##\n  tolerations:\n  - key: \"node.kubernetes.io/unschedulable\"\n    operator: \"Exists\"\n    effect: NoSchedule\n</code></pre> * update the namespace if applicable/desired * replace <code>##_NODE_NAME_##</code> with the problematic node (or remove nodeSelector section if problem is not confined to one node) * replace <code>##_CONTROLLER_IMAGE_##</code> with the same image as in use by your ingress-nginx deployment * confirm the securityContext section matches what is in place for ingress-nginx-controller pods in your cluster</p> <p>Apply the YAML and open a shell into the pod. Try to manually run the controller process: <pre><code>$ /nginx-ingress-controller\n</code></pre> You should get the same error as from the ingress controller pod logs.</p> <p>Confirm the capabilities are properly surfacing into the pod: <pre><code>$ grep CapBnd /proc/1/status\nCapBnd: 0000000000000400\n</code></pre> The above value has only net_bind_service enabled (per security context in YAML which adds that and drops all). If you get a different value, then you can decode it on another linux box (capsh not available in this container) like below, and then figure out why specified capabilities are not propagating into the pod/container. <pre><code>$ capsh --decode=0000000000000400\n0x0000000000000400=cap_net_bind_service\n</code></pre></p>"},{"location":"troubleshooting/#create-a-test-pod-as-root","title":"Create a test pod as root","text":"<p>(Note, this may be restricted by PodSecurityPolicy, PodSecurityAdmission/Standards, OPA Gatekeeper, etc. in which case you will need to do the appropriate workaround for testing, e.g. deploy in a new namespace without the restrictions.) To test further you may want to install additional utilities, etc.  Modify the pod yaml by: * changing runAsUser from 101 to 0 * removing the \"drop..ALL\" section from the capabilities.</p> <p>Some things to try after shelling into this container:</p> <p>Try running the controller as the www-data (101) user: <pre><code>$ chmod 4755 /nginx-ingress-controller\n$ /nginx-ingress-controller\n</code></pre> Examine the errors to see if there is still an issue listening on the port or if it passed that and moved on to other expected errors due to running out of context.</p> <p>Install the libcap package and check capabilities on the file: <pre><code>$ apk add libcap\n(1/1) Installing libcap (2.50-r0)\nExecuting busybox-1.33.1-r7.trigger\nOK: 26 MiB in 41 packages\n$ getcap /nginx-ingress-controller\n/nginx-ingress-controller cap_net_bind_service=ep\n</code></pre> (if missing, see above about purging image on the server and re-pulling)</p> <p>Strace the executable to see what system calls are being executed when it fails: <pre><code>$ apk add strace\n(1/1) Installing strace (5.12-r0)\nExecuting busybox-1.33.1-r7.trigger\nOK: 28 MiB in 42 packages\n$ strace /nginx-ingress-controller\nexecve(\"/nginx-ingress-controller\", [\"/nginx-ingress-controller\"], 0x7ffeb9eb3240 /* 131 vars */) = 0\narch_prctl(ARCH_SET_FS, 0x29ea690)      = 0\n...\n</code></pre></p>"},{"location":"deploy/","title":"Installation Guide","text":"<p>There are multiple ways to install the Ingress-Nginx Controller:</p> <ul> <li>with Helm, using the project repository chart;</li> <li>with <code>kubectl apply</code>, using YAML manifests;</li> <li>with specific addons (e.g. for minikube or MicroK8s).</li> </ul> <p>On most Kubernetes clusters, the ingress controller will work without requiring any extra configuration. If you want to  get started as fast as possible, you can check the quick start instructions. However, in many  environments, you can improve the performance or get better logs by enabling extra features. We recommend that you  check the environment-specific instructions for details about optimizing the  ingress controller for your particular environment or cloud provider.</p>"},{"location":"deploy/#contents","title":"Contents","text":"<ul> <li> <p>Quick start</p> </li> <li> <p>Environment-specific instructions</p> </li> <li>... Docker Desktop</li> <li>... Rancher Desktop</li> <li>... minikube</li> <li>... MicroK8s</li> <li>... AWS</li> <li>... GCE - GKE</li> <li>... Azure</li> <li>... Digital Ocean</li> <li>... Scaleway</li> <li>... Exoscale</li> <li>... Oracle Cloud Infrastructure</li> <li>... OVHcloud</li> <li>... Bare-metal</li> <li>Miscellaneous</li> </ul>"},{"location":"deploy/#quick-start","title":"Quick start","text":"<p>If you have Helm, you can deploy the ingress controller with the following command:</p> <pre><code>helm upgrade --install ingress-nginx ingress-nginx \\\n  --repo https://kubernetes.github.io/ingress-nginx \\\n  --namespace ingress-nginx --create-namespace\n</code></pre> <p>It will install the controller in the <code>ingress-nginx</code> namespace, creating that namespace if it doesn't already exist.</p> <p>Info</p> <p>This command is idempotent:</p> <ul> <li>if the ingress controller is not installed, it will install it,</li> <li>if the ingress controller is already installed, it will upgrade it.</li> </ul> <p>If you want a full list of values that you can set, while installing with Helm, then run:</p> <pre><code>helm show values ingress-nginx --repo https://kubernetes.github.io/ingress-nginx\n</code></pre> <p>If you don't have Helm or if you prefer to use a YAML manifest, you can run the following command instead:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>Info</p> <p>The YAML manifest in the command above was generated with <code>helm template</code>, so you will end up with almost the same  resources as if you had used Helm to install the controller.</p> <p>Attention</p> <p>If you are running an old version of Kubernetes (1.18 or earlier), please read this paragraph for specific instructions. Because of api deprecations, the default manifest may not work on your cluster. Specific manifests for supported Kubernetes versions are available within a sub-folder of each provider.</p>"},{"location":"deploy/#firewall-configuration","title":"Firewall configuration","text":"<p>To check which ports are used by your installation of ingress-nginx, look at the output of <code>kubectl -n ingress-nginx get pod -o yaml</code>. In general, you need: - Port 8443 open between all hosts on which the kubernetes nodes are running. This is used for the ingress-nginx admission controller. - Port 80 (for HTTP) and/or 443 (for HTTPS) open to the public on the kubernetes nodes to which the DNS of your apps are pointing.</p>"},{"location":"deploy/#pre-flight-check","title":"Pre-flight check","text":"<p>A few pods should start in the <code>ingress-nginx</code> namespace:</p> <pre><code>kubectl get pods --namespace=ingress-nginx\n</code></pre> <p>After a while, they should all be running. The following command will wait for the ingress controller pod to be up,  running, and ready:</p> <pre><code>kubectl wait --namespace ingress-nginx \\\n  --for=condition=ready pod \\\n  --selector=app.kubernetes.io/component=controller \\\n  --timeout=120s\n</code></pre>"},{"location":"deploy/#local-testing","title":"Local testing","text":"<p>Let's create a simple web server and the associated service:</p> <pre><code>kubectl create deployment demo --image=httpd --port=80\nkubectl expose deployment demo\n</code></pre> <p>Then create an ingress resource. The following example uses a host that maps to <code>localhost</code>:</p> <pre><code>kubectl create ingress demo-localhost --class=nginx \\\n  --rule=\"demo.localdev.me/*=demo:80\"\n</code></pre> <p>Now, forward a local port to the ingress controller:</p> <pre><code>kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8080:80\n</code></pre> <p>Info</p> <p>A note on DNS &amp; network-connection. This documentation assumes that a user has awareness of the DNS and the network routing aspects involved in using ingress. The port-forwarding mentioned above, is the easiest way to demo the working of ingress. The \"kubectl port-forward...\" command above has forwarded the port number 8080, on the localhost's tcp/ip stack, where the command was typed, to the port  number 80, of the service created by the installation of ingress-nginx controller. So now, the traffic sent to port number 8080 on localhost will reach the port number 80, of the ingress-controller's service. Port-forwarding is not for a production environment use-case. But here we use port-forwarding, to simulate a HTTP request, originating from outside the cluster, to reach the service of the ingress-nginx controller, that is exposed to receive traffic from outside the cluster.</p> <p>This issue shows a typical DNS problem and its solution.</p> <p>At this point, you can access your deployment using curl ; <pre><code>curl --resolve demo.localdev.me:8080:127.0.0.1 http://demo.localdev.me:8080\n</code></pre></p> <p>You should see a HTML response containing text like \"It works!\".</p>"},{"location":"deploy/#online-testing","title":"Online testing","text":"<p>If your Kubernetes cluster is a \"real\" cluster that supports services of type <code>LoadBalancer</code>, it will have allocated an  external IP address or FQDN to the ingress controller.</p> <p>You can see that IP address or FQDN with the following command:</p> <pre><code>kubectl get service ingress-nginx-controller --namespace=ingress-nginx\n</code></pre> <p>It will be the <code>EXTERNAL-IP</code> field. If that field shows <code>&lt;pending&gt;</code>, this means that your Kubernetes cluster wasn't  able to provision the load balancer (generally, this is because it doesn't support services of type <code>LoadBalancer</code>).</p> <p>Once you have the external IP address (or FQDN), set up a DNS record pointing to it. Then you can create an ingress  resource. The following example assumes that you have set up a DNS record for <code>www.demo.io</code>:</p> <pre><code>kubectl create ingress demo --class=nginx \\\n  --rule=\"www.demo.io/*=demo:80\"\n</code></pre> <p>Alternatively, the above command can be rewritten as follows for the <code>--rule</code> command and below. <pre><code>kubectl create ingress demo --class=nginx \\\n  --rule www.demo.io/=demo:80\n</code></pre></p> <p>You should then be able to see the \"It works!\" page when you connect to http://www.demo.io/. Congratulations,  you are serving a public website hosted on a Kubernetes cluster! \ud83c\udf89</p>"},{"location":"deploy/#environment-specific-instructions","title":"Environment-specific instructions","text":""},{"location":"deploy/#local-development-clusters","title":"Local development clusters","text":""},{"location":"deploy/#minikube","title":"minikube","text":"<p>The ingress controller can be installed through minikube's addons system:</p> <pre><code>minikube addons enable ingress\n</code></pre>"},{"location":"deploy/#microk8s","title":"MicroK8s","text":"<p>The ingress controller can be installed through MicroK8s's addons system:</p> <pre><code>microk8s enable ingress\n</code></pre> <p>Please check the MicroK8s documentation page for details.</p>"},{"location":"deploy/#docker-desktop","title":"Docker Desktop","text":"<p>Kubernetes is available in Docker Desktop:</p> <ul> <li>Mac, from version 18.06.0-ce</li> <li>Windows, from version 18.06.0-ce</li> </ul> <p>First, make sure that Kubernetes is enabled in the Docker settings. The command <code>kubectl get nodes</code> should show a  single node called <code>docker-desktop</code>.</p> <p>The ingress controller can be installed on Docker Desktop using the default quick start instructions.</p> <p>On most systems, if you don't have any other service of type <code>LoadBalancer</code> bound to port 80, the ingress controller  will be assigned the <code>EXTERNAL-IP</code> of <code>localhost</code>, which means that it will be reachable on localhost:80. If that  doesn't work, you might have to fall back to the <code>kubectl port-forward</code> method described in the  local testing section.</p>"},{"location":"deploy/#rancher-desktop","title":"Rancher Desktop","text":"<p>Rancher Desktop provides Kubernetes and Container Management on the desktop. Kubernetes is enabled by default in Rancher Desktop. </p> <p>Rancher Desktop uses K3s under the hood, which in turn uses Traefik as the default ingress controller for the Kubernetes cluster. To use Ingress-Nginx Controller in place of the default Traefik, disable Traefik from Preference &gt; Kubernetes menu.</p> <p>Once traefik is disabled, the Ingress-Nginx Controller can be installed on Rancher Desktop using the default quick start instructions. Follow the instructions described in the local testing section to try a sample.</p>"},{"location":"deploy/#cloud-deployments","title":"Cloud deployments","text":"<p>If the load balancers of your cloud provider do active healthchecks on their backends (most do), you can change the  <code>externalTrafficPolicy</code> of the ingress controller Service to <code>Local</code> (instead of the default <code>Cluster</code>) to save an  extra hop in some cases. If you're installing with Helm, this can be done by adding  <code>--set controller.service.externalTrafficPolicy=Local</code> to the <code>helm install</code> or <code>helm upgrade</code> command.</p> <p>Furthermore, if the load balancers of your cloud provider support the PROXY protocol, you can enable it, and it will  let the ingress controller see the real IP address of the clients. Otherwise, it will generally see the IP address of  the upstream load balancer. This must be done both in the ingress controller  (with e.g. <code>--set controller.config.use-proxy-protocol=true</code>) and in the cloud provider's load balancer configuration  to function correctly.</p> <p>In the following sections, we provide YAML manifests that enable these options when possible, using the specific  options of various cloud providers.</p>"},{"location":"deploy/#aws","title":"AWS","text":"<p>In AWS, we use a Network load balancer (NLB) to expose the Ingress-Nginx Controller behind a Service of <code>Type=LoadBalancer</code>.</p> <p>Info</p> <p>The provided templates illustrate the setup for legacy in-tree service load balancer for AWS NLB. AWS provides the documentation on how to use  Network load balancing on Amazon EKS  with AWS Load Balancer Controller.</p>"},{"location":"deploy/#network-load-balancer-nlb","title":"Network Load Balancer (NLB)","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/aws/deploy.yaml\n</code></pre>"},{"location":"deploy/#tls-termination-in-aws-load-balancer-nlb","title":"TLS termination in AWS Load Balancer (NLB)","text":"<p>By default, TLS is terminated in the ingress controller. But it is also possible to terminate TLS in the Load Balancer.  This section explains how to do that on AWS using an NLB.</p> <ol> <li>Download the deploy.yaml template</li> </ol> <pre><code>wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/aws/nlb-with-tls-termination/deploy.yaml\n</code></pre> <ol> <li> <p>Edit the file and change the VPC CIDR in use for the Kubernetes cluster:    <pre><code>proxy-real-ip-cidr: XXX.XXX.XXX/XX\n</code></pre></p> </li> <li> <p>Change the AWS Certificate Manager (ACM) ID as well:    <pre><code>arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX\n</code></pre></p> </li> <li> <p>Deploy the manifest:    <pre><code>kubectl apply -f deploy.yaml\n</code></pre></p> </li> </ol>"},{"location":"deploy/#nlb-idle-timeouts","title":"NLB Idle Timeouts","text":"<p>Idle timeout value for TCP flows is 350 seconds and  cannot be modified.</p> <p>For this reason, you need to ensure the  keepalive_timeout  value is configured less than 350 seconds to work as expected.</p> <p>By default, NGINX <code>keepalive_timeout</code> is set to <code>75s</code>.</p> <p>More information with regard to timeouts can be found in the  official AWS documentation</p>"},{"location":"deploy/#gce-gke","title":"GCE-GKE","text":"<p>First, your user needs to have <code>cluster-admin</code> permissions on the cluster. This can be done with the following command:</p> <pre><code>kubectl create clusterrolebinding cluster-admin-binding \\\n  --clusterrole cluster-admin \\\n  --user $(gcloud config get-value account)\n</code></pre> <p>Then, the ingress controller can be installed like this:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>Warning</p> <p>For private clusters, you will need to either add a firewall rule that allows master nodes access to  port <code>8443/tcp</code> on worker nodes, or change the existing rule that allows access to port <code>80/tcp</code>, <code>443/tcp</code> and  <code>10254/tcp</code> to also allow access to port <code>8443/tcp</code>. More information can be found in the  Official GCP Documentation.</p> <p>See the GKE documentation  on adding rules and the Kubernetes issue for more detail.</p> <p>Proxy-protocol is supported in GCE check the Official Documentations on how to enable.</p>"},{"location":"deploy/#azure","title":"Azure","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>More information with regard to Azure annotations for ingress controller can be found in the official AKS documentation.</p>"},{"location":"deploy/#digital-ocean","title":"Digital Ocean","text":"<p><pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/do/deploy.yaml\n</code></pre> - By default the service object of the ingress-nginx-controller for Digital-Ocean, only configures one annotation. Its this one <code>service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol: \"true\"</code>. While this makes the service functional, it was reported that the Digital-Ocean LoadBalancer graphs shows <code>no data</code>, unless a few other annotations are also configured. Some of these other annotations require values that can not be generic and hence not forced in a out-of-the-box installation. These annotations and a discussion on them is well documented in this issue. Please refer to the issue to add annotations, with values specific to user, to get graphs of the DO-LB populated with data.</p>"},{"location":"deploy/#scaleway","title":"Scaleway","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/scw/deploy.yaml\n</code></pre>"},{"location":"deploy/#exoscale","title":"Exoscale","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/exoscale/deploy.yaml\n</code></pre> <p>The full list of annotations supported by Exoscale is available in the Exoscale Cloud Controller Manager  documentation.</p>"},{"location":"deploy/#oracle-cloud-infrastructure","title":"Oracle Cloud Infrastructure","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>A  complete list of available annotations for Oracle Cloud Infrastructure  can be found in the OCI Cloud Controller Manager documentation.</p>"},{"location":"deploy/#ovhcloud","title":"OVHcloud","text":"<pre><code>helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx\nhelm repo update\nhelm -n ingress-nginx install ingress-nginx ingress-nginx/ingress-nginx --create-namespace\n</code></pre> <p>You can find the complete tutorial.</p>"},{"location":"deploy/#bare-metal-clusters","title":"Bare metal clusters","text":"<p>This section is applicable to Kubernetes clusters deployed on bare metal servers, as well as \"raw\" VMs where Kubernetes  was installed manually, using generic Linux distros (like CentOS, Ubuntu...)</p> <p>For quick testing, you can use a  NodePort.  This should work on almost every cluster, but it will typically use a port in the range 30000-32767.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/baremetal/deploy.yaml\n</code></pre> <p>For more information about bare metal deployments (and how to use port 80 instead of a random port in the 30000-32767 range), see bare-metal considerations.</p>"},{"location":"deploy/#miscellaneous","title":"Miscellaneous","text":""},{"location":"deploy/#checking-ingress-controller-version","title":"Checking ingress controller version","text":"<p>Run <code>/nginx-ingress-controller --version</code> within the pod, for instance with <code>kubectl exec</code>:</p> <pre><code>POD_NAMESPACE=ingress-nginx\nPOD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/name=ingress-nginx --field-selector=status.phase=Running -o name)\nkubectl exec $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version\n</code></pre>"},{"location":"deploy/#scope","title":"Scope","text":"<p>By default, the controller watches Ingress objects from all namespaces. If you want to change this behavior,  use the flag <code>--watch-namespace</code> or check the Helm chart value <code>controller.scope</code> to limit the controller to a single  namespace.</p> <p>See also  \u201cHow to easily install multiple instances of the Ingress NGINX controller in the same cluster\u201d  for more details.</p>"},{"location":"deploy/#webhook-network-access","title":"Webhook network access","text":"<p>Warning</p> <p>The controller uses an admission webhook to validate Ingress definitions. Make sure that you don't have  Network policies  or additional firewalls preventing connections from the API server to the <code>ingress-nginx-controller-admission</code> service.</p>"},{"location":"deploy/#certificate-generation","title":"Certificate generation","text":"<p>Attention</p> <p>The first time the ingress controller starts, two Jobs create the SSL Certificate used by the admission webhook.</p> <p>This can cause an initial delay of up to two minutes until it is possible to create and validate Ingress definitions.</p> <p>You can wait until it is ready to run the next command:</p> <pre><code> kubectl wait --namespace ingress-nginx \\\n  --for=condition=ready pod \\\n  --selector=app.kubernetes.io/component=controller \\\n  --timeout=120s\n</code></pre>"},{"location":"deploy/#running-on-kubernetes-versions-older-than-119","title":"Running on Kubernetes versions older than 1.19","text":"<p>Ingress resources evolved over time. They started with <code>apiVersion: extensions/v1beta1</code>,  then moved to <code>apiVersion: networking.k8s.io/v1beta1</code> and more recently to <code>apiVersion: networking.k8s.io/v1</code>.</p> <p>Here is how these Ingress versions are supported in Kubernetes: - before Kubernetes 1.19, only <code>v1beta1</code> Ingress resources are supported - from Kubernetes 1.19 to 1.21, both <code>v1beta1</code> and <code>v1</code> Ingress resources are supported - in Kubernetes 1.22 and above, only <code>v1</code> Ingress resources are supported</p> <p>And here is how these Ingress versions are supported in Ingress-Nginx Controller: - before version 1.0, only <code>v1beta1</code> Ingress resources are supported - in version 1.0 and above, only <code>v1</code> Ingress resources are</p> <p>As a result, if you're running Kubernetes 1.19 or later, you should be able to use the latest version of the NGINX  Ingress Controller; but if you're using an old version of Kubernetes (1.18 or earlier) you will have to use version 0.X  of the Ingress-Nginx Controller (e.g. version 0.49).</p> <p>The Helm chart of the Ingress-Nginx Controller switched to version 1 in version 4 of the chart. In other words, if  you're running Kubernetes 1.19 or earlier, you should use version 3.X of the chart (this can be done by adding  <code>--version='&lt;4'</code> to the <code>helm install</code> command ).</p>"},{"location":"deploy/baremetal/","title":"Bare-metal considerations","text":"<p>In traditional cloud environments, where network load balancers are available on-demand, a single Kubernetes manifest suffices to provide a single point of contact to the Ingress-Nginx Controller to external clients and, indirectly, to any application running inside the cluster. Bare-metal environments lack this commodity, requiring a slightly different setup to offer the same kind of access to external consumers.</p> <p> </p> <p>The rest of this document describes a few recommended approaches to deploying the Ingress-Nginx Controller inside a Kubernetes cluster running on bare-metal.</p>"},{"location":"deploy/baremetal/#a-pure-software-solution-metallb","title":"A pure software solution: MetalLB","text":"<p>MetalLB provides a network load-balancer implementation for Kubernetes clusters that do not run on a supported cloud provider, effectively allowing the usage of LoadBalancer Services within any cluster.</p> <p>This section demonstrates how to use the Layer 2 configuration mode of MetalLB together with the NGINX Ingress controller in a Kubernetes cluster that has publicly accessible nodes. In this mode, one node attracts all the traffic for the <code>ingress-nginx</code> Service IP. See Traffic policies for more details.</p> <p></p> <p>Note</p> <p>The description of other supported configuration modes is off-scope for this document.</p> <p>Warning</p> <p>MetalLB is currently in beta. Read about the Project maturity and make sure you inform yourself by reading the official documentation thoroughly.</p> <p>MetalLB can be deployed either with a simple Kubernetes manifest or with Helm. The rest of this example assumes MetalLB was deployed following the Installation instructions, and that the Ingress-Nginx Controller was installed  using the steps described in the quickstart section of the installation guide.</p> <p>MetalLB requires a pool of IP addresses in order to be able to take ownership of the <code>ingress-nginx</code> Service. This pool can be defined through <code>IPAddressPool</code> objects in the same namespace as the MetalLB controller. This pool of IPs must be dedicated to MetalLB's use, you can't reuse the Kubernetes node IPs or IPs handed out by a DHCP server.</p> <p>Example</p> <p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>After creating the following objects, MetalLB takes ownership of one of the IP addresses in the pool and updates the loadBalancer IP field of the <code>ingress-nginx</code> Service accordingly.</p> <pre><code>---\napiVersion: metallb.io/v1beta1\nkind: IPAddressPool\nmetadata:\n  name: default\n  namespace: metallb-system\nspec:\n  addresses:\n  - 203.0.113.10-203.0.113.15\n  autoAssign: true\n---\napiVersion: metallb.io/v1beta1\nkind: L2Advertisement\nmetadata:\n  name: default\n  namespace: metallb-system\nspec:\n  ipAddressPools:\n  - default\n</code></pre> <pre><code>$ kubectl -n ingress-nginx get svc\nNAME                   TYPE          CLUSTER-IP     EXTERNAL-IP  PORT(S)\ndefault-http-backend   ClusterIP     10.0.64.249    &lt;none&gt;       80/TCP\ningress-nginx          LoadBalancer  10.0.220.217   203.0.113.10  80:30100/TCP,443:30101/TCP\n</code></pre> <p>As soon as MetalLB sets the external IP address of the <code>ingress-nginx</code> LoadBalancer Service, the corresponding entries are created in the iptables NAT table and the node with the selected IP address starts responding to HTTP requests on the ports configured in the LoadBalancer Service:</p> <pre><code>$ curl -D- http://203.0.113.10 -H 'Host: myapp.example.com'\nHTTP/1.1 200 OK\nServer: nginx/1.15.2\n</code></pre> <p>Tip</p> <p>In order to preserve the source IP address in HTTP requests sent to NGINX, it is necessary to use the <code>Local</code> traffic policy. Traffic policies are described in more details in Traffic policies as well as in the next section.</p>"},{"location":"deploy/baremetal/#over-a-nodeport-service","title":"Over a NodePort Service","text":"<p>Due to its simplicity, this is the setup a user will deploy by default when following the steps described in the installation guide.</p> <p>Info</p> <p>A Service of type <code>NodePort</code> exposes, via the <code>kube-proxy</code> component, the same unprivileged port (default: 30000-32767) on every Kubernetes node, masters included. For more information, see Services.</p> <p>In this configuration, the NGINX container remains isolated from the host network. As a result, it can safely bind to any port, including the standard HTTP ports 80 and 443. However, due to the container namespace isolation, a client located outside the cluster network (e.g. on the public internet) is not able to access Ingress hosts directly on ports 80 and 443. Instead, the external client must append the NodePort allocated to the <code>ingress-nginx</code> Service to HTTP requests.</p> <p></p> <p>Example</p> <p>Given the NodePort <code>30100</code> allocated to the <code>ingress-nginx</code> Service</p> <pre><code>$ kubectl -n ingress-nginx get svc\nNAME                   TYPE        CLUSTER-IP     PORT(S)\ndefault-http-backend   ClusterIP   10.0.64.249    80/TCP\ningress-nginx          NodePort    10.0.220.217   80:30100/TCP,443:30101/TCP\n</code></pre> <p>and a Kubernetes node with the public IP address <code>203.0.113.2</code> (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>a client would reach an Ingress with <code>host: myapp.example.com</code> at <code>http://myapp.example.com:30100</code>, where the myapp.example.com subdomain resolves to the 203.0.113.2 IP address.</p> <p>Impact on the host system</p> <p>While it may sound tempting to reconfigure the NodePort range using the <code>--service-node-port-range</code> API server flag to include unprivileged ports and be able to expose ports 80 and 443, doing so may result in unexpected issues including (but not limited to) the use of ports otherwise reserved to system daemons and the necessity to grant <code>kube-proxy</code> privileges it may otherwise not require.</p> <p>This practice is therefore discouraged. See the other approaches proposed in this page for alternatives.</p> <p>This approach has a few other limitations one ought to be aware of:</p> <ul> <li>Source IP address</li> </ul> <p>Services of type NodePort perform source address translation by default. This means the source IP of a HTTP request is always the IP address of the Kubernetes node that received the request from the perspective of NGINX.</p> <p>The recommended way to preserve the source IP in a NodePort setup is to set the value of the <code>externalTrafficPolicy</code> field of the <code>ingress-nginx</code> Service spec to <code>Local</code> (example).</p> <p>Warning</p> <p>This setting effectively drops packets sent to Kubernetes nodes which are not running any instance of the NGINX Ingress controller. Consider assigning NGINX Pods to specific nodes in order to control on what nodes the Ingress-Nginx Controller should be scheduled or not scheduled.</p> <p>Example</p> <p>In a Kubernetes cluster composed of 3 nodes (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>with a <code>ingress-nginx-controller</code> Deployment composed of 2 replicas</p> <pre><code>$ kubectl -n ingress-nginx get pod -o wide\nNAME                                       READY   STATUS    IP           NODE\ndefault-http-backend-7c5bc89cc9-p86md      1/1     Running   172.17.1.1   host-2\ningress-nginx-controller-cf9ff8c96-8vvf8   1/1     Running   172.17.0.3   host-3\ningress-nginx-controller-cf9ff8c96-pxsds   1/1     Running   172.17.1.4   host-2\n</code></pre> <p>Requests sent to <code>host-2</code> and <code>host-3</code> would be forwarded to NGINX and original client's IP would be preserved, while requests to <code>host-1</code> would get dropped because there is no NGINX replica running on that node.</p> <ul> <li>Ingress status</li> </ul> <p>Because NodePort Services do not get a LoadBalancerIP assigned by definition, the Ingress-Nginx Controller does not update the status of Ingress objects it manages.</p> <pre><code>$ kubectl get ingress\nNAME           HOSTS               ADDRESS   PORTS\ntest-ingress   myapp.example.com             80\n</code></pre> <p>Despite the fact there is no load balancer providing a public IP address to the Ingress-Nginx Controller, it is possible to force the status update of all managed Ingress objects by setting the <code>externalIPs</code> field of the <code>ingress-nginx</code> Service.</p> <p>Warning</p> <p>There is more to setting <code>externalIPs</code> than just enabling the Ingress-Nginx Controller to update the status of Ingress objects. Please read about this option in the Services page of official Kubernetes documentation as well as the section about External IPs in this document for more information.</p> <p>Example</p> <p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>one could edit the <code>ingress-nginx</code> Service and add the following field to the object spec</p> <pre><code>spec:\n  externalIPs:\n  - 203.0.113.1\n  - 203.0.113.2\n  - 203.0.113.3\n</code></pre> <p>which would in turn be reflected on Ingress objects as follows:</p> <pre><code>$ kubectl get ingress -o wide\nNAME           HOSTS               ADDRESS                               PORTS\ntest-ingress   myapp.example.com   203.0.113.1,203.0.113.2,203.0.113.3   80\n</code></pre> <ul> <li>Redirects</li> </ul> <p>As NGINX is not aware of the port translation operated by the NodePort Service, backend applications are responsible for generating redirect URLs that take into account the URL used by external clients, including the NodePort.</p> <p>Example</p> <p>Redirects generated by NGINX, for instance HTTP to HTTPS or <code>domain</code> to <code>www.domain</code>, are generated without NodePort:</p> <pre><code>$ curl -D- http://myapp.example.com:30100`\nHTTP/1.1 308 Permanent Redirect\nServer: nginx/1.15.2\nLocation: https://myapp.example.com/  #-&gt; missing NodePort in HTTPS redirect\n</code></pre>"},{"location":"deploy/baremetal/#via-the-host-network","title":"Via the host network","text":"<p>In a setup where there is no external load balancer available but using NodePorts is not an option, one can configure <code>ingress-nginx</code> Pods to use the network of the host they run on instead of a dedicated network namespace. The benefit of this approach is that the Ingress-Nginx Controller can bind ports 80 and 443 directly to Kubernetes nodes' network interfaces, without the extra network translation imposed by NodePort Services.</p> <p>Note</p> <p>This approach does not leverage any Service object to expose the Ingress-Nginx Controller. If the <code>ingress-nginx</code> Service exists in the target cluster, it is recommended to delete it.</p> <p>This can be achieved by enabling the <code>hostNetwork</code> option in the Pods' spec.</p> <pre><code>template:\n  spec:\n    hostNetwork: true\n</code></pre> <p>Security considerations</p> <p>Enabling this option exposes every system daemon to the Ingress-Nginx Controller on any network interface, including the host's loopback. Please evaluate the impact this may have on the security of your system carefully.</p> <p>Example</p> <p>Consider this <code>ingress-nginx-controller</code> Deployment composed of 2 replicas, NGINX Pods inherit from the IP address of their host instead of an internal Pod IP.</p> <pre><code>$ kubectl -n ingress-nginx get pod -o wide\nNAME                                       READY   STATUS    IP            NODE\ndefault-http-backend-7c5bc89cc9-p86md      1/1     Running   172.17.1.1    host-2\ningress-nginx-controller-5b4cf5fc6-7lg6c   1/1     Running   203.0.113.3   host-3\ningress-nginx-controller-5b4cf5fc6-lzrls   1/1     Running   203.0.113.2   host-2\n</code></pre> <p>One major limitation of this deployment approach is that only a single Ingress-Nginx Controller Pod may be scheduled on each cluster node, because binding the same port multiple times on the same network interface is technically impossible. Pods that are unschedulable due to such situation fail with the following event:</p> <pre><code>$ kubectl -n ingress-nginx describe pod &lt;unschedulable-ingress-nginx-controller-pod&gt;\n...\nEvents:\n  Type     Reason            From               Message\n  ----     ------            ----               -------\n  Warning  FailedScheduling  default-scheduler  0/3 nodes are available: 3 node(s) didn't have free ports for the requested pod ports.\n</code></pre> <p>One way to ensure only schedulable Pods are created is to deploy the Ingress-Nginx Controller as a DaemonSet instead of a traditional Deployment.</p> <p>Info</p> <p>A DaemonSet schedules exactly one type of Pod per cluster node, masters included, unless a node is configured to repel those Pods. For more information, see DaemonSet.</p> <p>Because most properties of DaemonSet objects are identical to Deployment objects, this documentation page leaves the configuration of the corresponding manifest at the user's discretion.</p> <p></p> <p>Like with NodePorts, this approach has a few quirks it is important to be aware of.</p> <ul> <li>DNS resolution</li> </ul> <p>Pods configured with <code>hostNetwork: true</code> do not use the internal DNS resolver (i.e. kube-dns or CoreDNS), unless their <code>dnsPolicy</code> spec field is set to <code>ClusterFirstWithHostNet</code>. Consider using this setting if NGINX is expected to resolve internal names for any reason.</p> <ul> <li>Ingress status</li> </ul> <p>Because there is no Service exposing the Ingress-Nginx Controller in a configuration using the host network, the default <code>--publish-service</code> flag used in standard cloud setups does not apply and the status of all Ingress objects remains blank.</p> <pre><code>$ kubectl get ingress\nNAME           HOSTS               ADDRESS   PORTS\ntest-ingress   myapp.example.com             80\n</code></pre> <p>Instead, and because bare-metal nodes usually don't have an ExternalIP, one has to enable the <code>--report-node-internal-ip-address</code> flag, which sets the status of all Ingress objects to the internal IP address of all nodes running the Ingress-Nginx Controller.</p> <p>Example</p> <p>Given a <code>ingress-nginx-controller</code> DaemonSet composed of 2 replicas</p> <pre><code>$ kubectl -n ingress-nginx get pod -o wide\nNAME                                       READY   STATUS    IP            NODE\ndefault-http-backend-7c5bc89cc9-p86md      1/1     Running   172.17.1.1    host-2\ningress-nginx-controller-5b4cf5fc6-7lg6c   1/1     Running   203.0.113.3   host-3\ningress-nginx-controller-5b4cf5fc6-lzrls   1/1     Running   203.0.113.2   host-2\n</code></pre> <p>the controller sets the status of all Ingress objects it manages to the following value:</p> <pre><code>$ kubectl get ingress -o wide\nNAME           HOSTS               ADDRESS                   PORTS\ntest-ingress   myapp.example.com   203.0.113.2,203.0.113.3   80\n</code></pre> <p>Note</p> <p>Alternatively, it is possible to override the address written to Ingress objects using the <code>--publish-status-address</code> flag. See Command line arguments.</p>"},{"location":"deploy/baremetal/#using-a-self-provisioned-edge","title":"Using a self-provisioned edge","text":"<p>Similarly to cloud environments, this deployment approach requires an edge network component providing a public entrypoint to the Kubernetes cluster. This edge component can be either hardware (e.g. vendor appliance) or software (e.g. HAproxy) and is usually managed outside of the Kubernetes landscape by operations teams.</p> <p>Such deployment builds upon the NodePort Service described above in Over a NodePort Service, with one significant difference: external clients do not access cluster nodes directly, only the edge component does. This is particularly suitable for private Kubernetes clusters where none of the nodes has a public IP address.</p> <p>On the edge side, the only prerequisite is to dedicate a public IP address that forwards all HTTP traffic to Kubernetes nodes and/or masters. Incoming traffic on TCP ports 80 and 443 is forwarded to the corresponding HTTP and HTTPS NodePort on the target nodes as shown in the diagram below:</p> <p></p>"},{"location":"deploy/baremetal/#external-ips","title":"External IPs","text":"<p>Source IP address</p> <p>This method does not allow preserving the source IP of HTTP requests in any manner, it is therefore not recommended to use it despite its apparent simplicity.</p> <p>The <code>externalIPs</code> Service option was previously mentioned in the NodePort section.</p> <p>As per the Services page of the official Kubernetes documentation, the <code>externalIPs</code> option causes <code>kube-proxy</code> to route traffic sent to arbitrary IP addresses and on the Service ports to the endpoints of that Service. These IP addresses must belong to the target node.</p> <p>Example</p> <p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>and the following <code>ingress-nginx</code> NodePort Service</p> <pre><code>$ kubectl -n ingress-nginx get svc\nNAME                   TYPE        CLUSTER-IP     PORT(S)\ningress-nginx          NodePort    10.0.220.217   80:30100/TCP,443:30101/TCP\n</code></pre> <p>One could set the following external IPs in the Service spec, and NGINX would become available on both the NodePort and the Service port:</p> <pre><code>spec:\n  externalIPs:\n  - 203.0.113.2\n  - 203.0.113.3\n</code></pre> <pre><code>$ curl -D- http://myapp.example.com:30100\nHTTP/1.1 200 OK\nServer: nginx/1.15.2\n\n$ curl -D- http://myapp.example.com\nHTTP/1.1 200 OK\nServer: nginx/1.15.2\n</code></pre> <p>We assume the myapp.example.com subdomain above resolves to both 203.0.113.2 and 203.0.113.3 IP addresses.</p>"},{"location":"deploy/hardening-guide/","title":"Hardening Guide","text":""},{"location":"deploy/hardening-guide/#overview","title":"Overview","text":"<p>There are several ways to do hardening and securing of nginx. In this documentation two guides are used, the guides are overlapping in some points:</p> <ul> <li>nginx CIS Benchmark</li> <li>cipherlist.eu (one of many forks of the now dead project cipherli.st)</li> </ul> <p>This guide describes, what of the different configurations described in those guides is already implemented as default in the nginx implementation of kubernetes ingress, what needs to be configured, what is obsolete due to the fact that the nginx is running as container (the CIS benchmark relates to a non-containerized installation) and what is difficult or not possible.</p> <p>Be aware that this is only a guide and you are responsible for your own implementation. Some of the configurations may lead to have specific clients unable to reach your site or similar consequences.</p> <p>This guide refers to chapters in the CIS Benchmark. For full explanation you should refer to the benchmark document itself</p>"},{"location":"deploy/hardening-guide/#configuration-guide","title":"Configuration Guide","text":"Chapter in CIS benchmark Status Default Action to do if not default 1 Initial Setup 1.1 Installation 1.1.1 Ensure NGINX is installed (Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.1.2 Ensure NGINX is installed from source (Not Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.2 Configure Software Updates 1.2.1 Ensure package manager repositories are properly configured (Not Scored) OK done via helm, nginx version could be overwritten, however compatibility is not ensured then 1.2.2 Ensure the latest software package is installed (Not Scored) ACTION NEEDED done via helm, nginx version could be overwritten, however compatibility is not ensured then Plan for periodic updates 2 Basic Configuration 2.1 Minimize NGINX Modules 2.1.1 Ensure only required modules are installed (Not Scored) OK Already only needed modules are installed, however proposals for further reduction are welcome 2.1.2 Ensure HTTP WebDAV module is not installed (Scored) OK 2.1.3 Ensure modules with gzip functionality are disabled (Scored) OK 2.1.4 Ensure the autoindex module is disabled (Scored) OK No autoindex configs so far in ingress defaults 2.2 Account Security 2.2.1 Ensure that NGINX is run using a non-privileged, dedicated service account (Not Scored) OK Pod configured as user www-data: See this line in helm chart values. Compiled with user www-data: See this line in build script 2.2.2 Ensure the NGINX service account is locked (Scored) OK Docker design ensures this 2.2.3 Ensure the NGINX service account has an invalid shell (Scored) OK Shell is nologin: see this line in build script 2.3 Permissions and Ownership 2.3.1 Ensure NGINX directories and files are owned by root (Scored) OK Obsolete through docker-design and ingress controller needs to update the configs dynamically 2.3.2 Ensure access to NGINX directories and files is restricted (Scored) OK See previous answer 2.3.3 Ensure the NGINX process ID (PID) file is secured (Scored) OK No PID-File due to docker design 2.3.4 Ensure the core dump directory is secured (Not Scored) OK No working_directory configured by default 2.4 Network Configuration 2.4.1 Ensure NGINX only listens for network connections on authorized ports (Not Scored) OK Ensured by automatic nginx.conf configuration 2.4.2 Ensure requests for unknown host names are rejected (Not Scored) OK They are not rejected but send to the \"default backend\" delivering appropriate errors (mostly 404) 2.4.3 Ensure keepalive_timeout is 10 seconds or less, but not 0 (Scored) ACTION NEEDED Default is 75s configure keep-alive to 10 seconds according to this documentation 2.4.4 Ensure send_timeout is set to 10 seconds or less, but not 0 (Scored) RISK TO BE ACCEPTED Not configured, however the nginx default is 60s Not configurable 2.5 Information Disclosure 2.5.1 Ensure server_tokens directive is set to <code>off</code> (Scored) OK server_tokens is configured to off by default 2.5.2 Ensure default error and index.html pages do not reference NGINX (Scored) ACTION NEEDED 404 shows no version at all, 503 and 403 show \"nginx\", which is hardcoded see this line in nginx source code configure custom error pages at least for 403, 404 and 503 and 500 2.5.3 Ensure hidden file serving is disabled (Not Scored) ACTION NEEDED config not set configure a config.server-snippet Snippet, but beware of .well-known challenges or similar. Refer to the benchmark here please 2.5.4 Ensure the NGINX reverse proxy does not enable information disclosure (Scored) ACTION NEEDED hide not configured configure hide-headers with array of \"X-Powered-By\" and \"Server\": according to this documentation 3 Logging 3.1 Ensure detailed logging is enabled (Not Scored) OK nginx ingress has a very detailed log format by default 3.2 Ensure access logging is enabled (Scored) OK Access log is enabled by default 3.3 Ensure error logging is enabled and set to the info logging level (Scored) OK Error log is configured by default. The log level does not matter, because it is all sent to STDOUT anyway 3.4 Ensure log files are rotated (Scored) OBSOLETE Log file handling is not part of the nginx ingress and should be handled separately 3.5 Ensure error logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.6 Ensure access logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.7 Ensure proxies pass source IP information (Scored) OK Headers are set by default 4 Encryption 4.1 TLS / SSL Configuration 4.1.1 Ensure HTTP is redirected to HTTPS (Scored) OK Redirect to TLS is default 4.1.2 Ensure a trusted certificate and trust chain is installed (Not Scored) ACTION NEEDED For installing certs there are enough manuals in the web. A good way is to use lets encrypt through cert-manager Install proper certificates or use lets encrypt with cert-manager 4.1.3 Ensure private key permissions are restricted (Scored) ACTION NEEDED See previous answer 4.1.4 Ensure only modern TLS protocols are used (Scored) OK/ACTION NEEDED Default is TLS 1.2 + 1.3, while this is okay for CIS Benchmark, cipherlist.eu only recommends 1.3. This may cut off old OS's Set controller.config.ssl-protocols to \"TLSv1.3\" 4.1.5 Disable weak ciphers (Scored) ACTION NEEDED Default ciphers are already good, but cipherlist.eu recommends even stronger ciphers Set controller.config.ssl-ciphers to \"EECDH+AESGCM:EDH+AESGCM\" 4.1.6 Ensure custom Diffie-Hellman parameters are used (Scored) ACTION NEEDED No custom DH parameters are generated Generate dh parameters for each ingress deployment you use - see here for a how to 4.1.7 Ensure Online Certificate Status Protocol (OCSP) stapling is enabled (Scored) ACTION NEEDED Not enabled set via this configuration parameter 4.1.8 Ensure HTTP Strict Transport Security (HSTS) is enabled (Scored) OK HSTS is enabled by default 4.1.9 Ensure HTTP Public Key Pinning is enabled (Not Scored) ACTION NEEDED / RISK TO BE ACCEPTED HKPK not enabled by default If lets encrypt is not used, set correct HPKP header. There are several ways to implement this - with the helm charts it works via controller.add-headers. If lets encrypt is used, this is complicated, a solution here is yet unknown 4.1.10 Ensure upstream server traffic is authenticated with a client certificate (Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, manual is here 4.1.11 Ensure the upstream traffic server certificate is trusted (Not Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, see configuration here 4.1.12 Ensure your domain is preloaded (Not Scored) ACTION NEEDED Preload is not active by default Set controller.config.hsts-preload to true 4.1.13 Ensure session resumption is disabled to enable perfect forward security (Scored) OK Session tickets are disabled by default 4.1.14 Ensure HTTP/2.0 is used (Not Scored) OK http2 is set by default 5 Request Filtering and Restrictions 5.1 Access Control 5.1.1 Ensure allow and deny filters limit access to specific IP addresses (Not Scored) OK/ACTION NEEDED Depends on use case, geo ip module is compiled into Ingress-Nginx Controller, there are several ways to use it If needed set IP restrictions via annotations or work with config snippets (be careful with lets-encrypt-http-challenge!) 5.1.2 Ensure only whitelisted HTTP methods are allowed (Not Scored) OK/ACTION NEEDED Depends on use case If required it can be set via config snippet 5.2 Request Limits 5.2.1 Ensure timeout values for reading the client header and body are set correctly (Scored) ACTION NEEDED Default timeout is 60s Set via this configuration parameter and respective body equivalent 5.2.2 Ensure the maximum request body size is set correctly (Scored) ACTION NEEDED Default is 1m set via this configuration parameter 5.2.3 Ensure the maximum buffer size for URIs is defined (Scored) ACTION NEEDED Default is 4 8k Set via this configuration parameter 5.2.4 Ensure the number of connections per IP address is limited (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.2.5 Ensure rate limits by IP address are set (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.3 Browser Security 5.3.1 Ensure X-Frame-Options header is configured and enabled (Scored) ACTION NEEDED Header not set by default Several ways to implement this - with the helm charts it works via controller.add-headers 5.3.2 Ensure X-Content-Type-Options header is configured and enabled (Scored) ACTION NEEDED See previous answer See previous answer 5.3.3 Ensure the X-XSS-Protection Header is enabled and configured properly (Scored) ACTION NEEDED See previous answer See previous answer 5.3.4 Ensure that Content Security Policy (CSP) is enabled and configured properly (Not Scored) ACTION NEEDED See previous answer See previous answer 5.3.5 Ensure the Referrer Policy is enabled and configured properly (Not Scored) ACTION NEEDED Depends on application. It should be handled in the applications webserver itself, not in the load balancing ingress check backend webserver 6 Mandatory Access Control n/a too high level, depends on backends"},{"location":"deploy/rbac/","title":"Role Based Access Control (RBAC)","text":""},{"location":"deploy/rbac/#overview","title":"Overview","text":"<p>This example applies to ingress-nginx-controllers being deployed in an environment with RBAC enabled.</p> <p>Role Based Access Control is comprised of four layers:</p> <ol> <li><code>ClusterRole</code> - permissions assigned to a role that apply to an entire cluster</li> <li><code>ClusterRoleBinding</code> - binding a ClusterRole to a specific account</li> <li><code>Role</code> - permissions assigned to a role that apply to a specific namespace</li> <li><code>RoleBinding</code> - binding a Role to a specific account</li> </ol> <p>In order for RBAC to be applied to an ingress-nginx-controller, that controller should be assigned to a <code>ServiceAccount</code>.  That <code>ServiceAccount</code> should be bound to the <code>Role</code>s and <code>ClusterRole</code>s defined for the ingress-nginx-controller.</p>"},{"location":"deploy/rbac/#service-accounts-created-in-this-example","title":"Service Accounts created in this example","text":"<p>One ServiceAccount is created in this example, <code>ingress-nginx</code>.</p>"},{"location":"deploy/rbac/#permissions-granted-in-this-example","title":"Permissions Granted in this example","text":"<p>There are two sets of permissions defined in this example.  Cluster-wide permissions defined by the <code>ClusterRole</code> named <code>ingress-nginx</code>, and namespace specific permissions defined by the <code>Role</code> named <code>ingress-nginx</code>.</p>"},{"location":"deploy/rbac/#cluster-permissions","title":"Cluster Permissions","text":"<p>These permissions are granted in order for the ingress-nginx-controller to be able to function as an ingress across the cluster.  These permissions are granted to the <code>ClusterRole</code> named <code>ingress-nginx</code></p> <ul> <li><code>configmaps</code>, <code>endpoints</code>, <code>nodes</code>, <code>pods</code>, <code>secrets</code>: list, watch</li> <li><code>nodes</code>: get</li> <li><code>services</code>, <code>ingresses</code>, <code>ingressclasses</code>, <code>endpointslices</code>: get, list, watch</li> <li><code>events</code>: create, patch</li> <li><code>ingresses/status</code>: update</li> <li><code>leases</code>: list, watch</li> </ul>"},{"location":"deploy/rbac/#namespace-permissions","title":"Namespace Permissions","text":"<p>These permissions are granted specific to the ingress-nginx namespace.  These permissions are granted to the <code>Role</code> named <code>ingress-nginx</code></p> <ul> <li><code>configmaps</code>, <code>pods</code>, <code>secrets</code>: get</li> <li><code>endpoints</code>: get</li> </ul> <p>Furthermore to support leader-election, the ingress-nginx-controller needs to have access to a <code>leases</code> using the resourceName <code>ingress-nginx-leader</code></p> <p>Note that resourceNames can NOT be used to limit requests using the \u201ccreate\u201d verb because authorizers only have access to information that can be obtained from the request URL, method, and headers (resource names in a \u201ccreate\u201d request are part of the request body).</p> <ul> <li><code>leases</code>: get, update (for resourceName <code>ingress-controller-leader</code>)</li> <li><code>leases</code>: create</li> </ul> <p>This resourceName is the <code>election-id</code> defined by the ingress-controller, which defaults to:</p> <ul> <li><code>election-id</code>: <code>ingress-controller-leader</code></li> <li><code>resourceName</code> : <code>&lt;election-id&gt;</code></li> </ul> <p>Please adapt accordingly if you overwrite either parameter when launching the ingress-nginx-controller.</p>"},{"location":"deploy/rbac/#bindings","title":"Bindings","text":"<p>The ServiceAccount <code>ingress-nginx</code> is bound to the Role <code>ingress-nginx</code> and the ClusterRole <code>ingress-nginx</code>.</p> <p>The serviceAccountName associated with the containers in the deployment must match the serviceAccount. The namespace references in the Deployment metadata,  container arguments, and POD_NAMESPACE should be in the ingress-nginx namespace.</p>"},{"location":"deploy/upgrade/","title":"Upgrading","text":"<p>Important</p> <p>No matter the method you use for upgrading, if you use template overrides, make sure your templates are compatible with the new version of ingress-nginx.</p>"},{"location":"deploy/upgrade/#without-helm","title":"Without Helm","text":"<p>To upgrade your ingress-nginx installation, it should be enough to change the version of the image in the controller Deployment.</p> <p>I.e. if your deployment resource looks like (partial example):</p> <pre><code>kind: Deployment\nmetadata:\n  name: ingress-nginx-controller\n  namespace: ingress-nginx\nspec:\n  replicas: 1\n  selector: ...\n  template:\n    metadata: ...\n    spec:\n      containers:\n        - name: ingress-nginx-controller\n          image: registry.k8s.io/ingress-nginx/controller:v1.0.4@sha256:545cff00370f28363dad31e3b59a94ba377854d3a11f18988f5f9e56841ef9ef\n          args: ...\n</code></pre> <p>simply change the <code>v1.0.4</code> tag to the version you wish to upgrade to. The easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):</p> <pre><code>kubectl set image deployment/ingress-nginx-controller \\\n  controller=registry.k8s.io/ingress-nginx/controller:v1.0.5@sha256:55a1fcda5b7657c372515fe402c3e39ad93aa59f6e4378e82acd99912fe6028d \\\n  -n ingress-nginx\n</code></pre> <p>For interactive editing, use <code>kubectl edit deployment ingress-nginx-controller -n ingress-nginx</code>.</p>"},{"location":"deploy/upgrade/#with-helm","title":"With Helm","text":"<p>If you installed ingress-nginx using the Helm command in the deployment docs so its name is <code>ingress-nginx</code>, you should be able to upgrade using</p> <pre><code>helm upgrade --reuse-values ingress-nginx ingress-nginx/ingress-nginx\n</code></pre>"},{"location":"deploy/upgrade/#migrating-from-stablenginx-ingress","title":"Migrating from stable/nginx-ingress","text":"<p>See detailed steps in the upgrading section of the <code>ingress-nginx</code> chart README.</p>"},{"location":"developer-guide/code-overview/","title":"Ingress NGINX - Code Overview","text":"<p>This document provides an overview of Ingress NGINX code.</p>"},{"location":"developer-guide/code-overview/#core-golang-code","title":"Core Golang code","text":"<p>This part of the code is responsible for the main logic of Ingress NGINX. It contains all the logics that parses Ingress Objects,  annotations, watches Endpoints and turn them into usable nginx.conf configuration.</p>"},{"location":"developer-guide/code-overview/#core-sync-logics","title":"Core Sync Logics:","text":"<p>Ingress-nginx has an internal model of the ingresses, secrets and endpoints in a given cluster. It maintains two copies of that:</p> <ol> <li>One copy is the currently running configuration model</li> <li>Second copy is the one generated in response to some changes in the cluster</li> </ol> <p>The sync logic diffs the two models and if there's a change it tries to converge the running configuration to the new one. </p> <p>There are static and dynamic configuration changes. </p> <p>All endpoints and certificate changes are handled dynamically by posting the payload to an internal NGINX endpoint that is handled by Lua.</p> <p>The following parts of the code can be found:</p>"},{"location":"developer-guide/code-overview/#entrypoint","title":"Entrypoint","text":"<p>The <code>main</code> package is responsible for starting ingress-nginx program, which can be found in cmd/nginx directory.</p>"},{"location":"developer-guide/code-overview/#version","title":"Version","text":"<p>Is the package of the code responsible for adding <code>version</code> subcommand, and can be found in version directory.</p>"},{"location":"developer-guide/code-overview/#internal-code","title":"Internal code","text":"<p>This part of the code contains the internal logics that compose Ingress NGINX Controller, and it's split into:</p>"},{"location":"developer-guide/code-overview/#admission-controller","title":"Admission Controller","text":"<p>Contains the code of Kubernetes Admission Controller which validates the syntax of ingress objects before accepting it.</p> <p>This code can be found in internal/admission/controller directory.</p>"},{"location":"developer-guide/code-overview/#file-functions","title":"File functions","text":"<p>Contains auxiliary codes that deal with files, such as generating the SHA1 checksum of a file, or creating required directories.</p> <p>This code can be found in internal/file directory.</p>"},{"location":"developer-guide/code-overview/#ingress-functions","title":"Ingress functions","text":"<p>Contains all the logics from Ingress-Nginx Controller, with some examples being:</p> <ul> <li>Expected Golang structures that will be used in templates and other parts of the code - internal/ingress/types.go.</li> <li>supported annotations and its parsing logics - internal/ingress/annotations.</li> <li>reconciliation loops and logics - internal/ingress/controller</li> <li>defaults - define the default struct - internal/ingress/defaults.</li> <li>Error interface and types implementation - internal/ingress/errors</li> <li>Metrics collectors for Prometheus exporting - internal/ingress/metric.</li> <li>Resolver - Extracts information from a controller - internal/ingress/resolver.</li> <li>Ingress Object status publisher - internal/ingress/status.</li> </ul> <p>And other parts of the code that will be written in this document in a future.</p>"},{"location":"developer-guide/code-overview/#k8s-functions","title":"K8s functions","text":"<p>Contains helper functions for parsing Kubernetes objects.</p> <p>This part of the code can be found in internal/k8s directory.</p>"},{"location":"developer-guide/code-overview/#networking-functions","title":"Networking functions","text":"<p>Contains helper functions for networking, such as IPv4 and IPv6 parsing, SSL certificate parsing, etc.</p> <p>This part of the code can be found in internal/net directory.</p>"},{"location":"developer-guide/code-overview/#nginx-functions","title":"NGINX functions","text":"<p>Contains helper function to deal with NGINX, such as verify if it's running and reading it's configuration file parts.</p> <p>This part of the code can be found in internal/nginx directory.</p>"},{"location":"developer-guide/code-overview/#tasks-queue","title":"Tasks / Queue","text":"<p>Contains the functions responsible for the sync queue part of the controller.</p> <p>This part of the code can be found in internal/task directory.</p>"},{"location":"developer-guide/code-overview/#other-parts-of-internal","title":"Other parts of internal","text":"<p>Other parts of internal code might not be covered here, like runtime and watch but they can be added in a future.</p>"},{"location":"developer-guide/code-overview/#e2e-test","title":"E2E Test","text":"<p>The e2e tests code is in test directory.</p>"},{"location":"developer-guide/code-overview/#other-programs","title":"Other programs","text":"<p>Describe here <code>kubectl plugin</code>, <code>dbg</code>, <code>waitshutdown</code> and cover the hack scripts.</p>"},{"location":"developer-guide/code-overview/#kubectl-plugin","title":"kubectl plugin","text":"<p>It contains kubectl plugin for inspecting your ingress-nginx deployments. This part of code can be found in cmd/plugin directory Detail functions flow and available flow can be found in kubectl-plugin</p>"},{"location":"developer-guide/code-overview/#deploy-files","title":"Deploy files","text":"<p>This directory contains the <code>yaml</code> deploy files used as examples or references in the docs to deploy Ingress NGINX and other components.</p> <p>Those files are in deploy directory.</p>"},{"location":"developer-guide/code-overview/#helm-chart","title":"Helm Chart","text":"<p>Used to generate the Helm chart published.</p> <p>Code is in charts/ingress-nginx.</p>"},{"location":"developer-guide/code-overview/#documentationwebsite","title":"Documentation/Website","text":"<p>The documentation used to generate the website https://kubernetes.github.io/ingress-nginx/</p> <p>This code is available in docs and it's main \"language\" is <code>Markdown</code>, used by mkdocs file to generate static pages.</p>"},{"location":"developer-guide/code-overview/#container-images","title":"Container Images","text":"<p>Container images used to run ingress-nginx, or to build the final image.</p>"},{"location":"developer-guide/code-overview/#base-images","title":"Base Images","text":"<p>Contains the <code>Dockerfiles</code> and scripts used to build base images that are used in other parts of the repo. They are present in images repo. Some examples: * nginx - The base NGINX image ingress-nginx uses is not a vanilla NGINX. It bundles many libraries together and it is a job in itself to maintain that and keep things up-to-date. * custom-error-pages - Used on the custom error page examples.</p> <p>There are other images inside this directory.</p>"},{"location":"developer-guide/code-overview/#ingress-controller-image","title":"Ingress Controller Image","text":"<p>The image used to build the final ingress controller, used in deploy scripts and Helm charts. </p> <p>This is NGINX with some Lua enhancement. We do dynamic certificate, endpoints handling, canary traffic split, custom load balancing etc at this component. One can also add new functionalities using Lua plugin system.</p> <p>The files are in rootfs directory and contains:</p> <ul> <li>The Dockerfile</li> <li>nginx config</li> </ul>"},{"location":"developer-guide/code-overview/#ingress-nginx-lua-scripts","title":"Ingress NGINX Lua Scripts","text":"<p>Ingress NGINX uses Lua Scripts to enable features like hot reloading, rate limiting and monitoring. Some are written using the OpenResty helper.</p> <p>The directory containing Lua scripts is rootfs/etc/nginx/lua.</p>"},{"location":"developer-guide/code-overview/#nginx-go-template-file","title":"Nginx Go template file","text":"<p>One of the functions of Ingress NGINX is to turn Ingress objects into nginx.conf file. </p> <p>To do so, the final step is to apply those configurations in nginx.tmpl turning it into a final nginx.conf file.</p>"},{"location":"developer-guide/getting-started/","title":"Getting Started","text":"<p>Developing for Ingress-Nginx Controller</p> <p>This document explains how to get started with developing for Ingress-Nginx Controller.</p> <p>For the really new contributors, who want to contribute to the INGRESS-NGINX project, but need help with understanding some basic concepts, that are needed to work with the Kubernetes ingress resource, here is a link to the New Contributors Guide. This guide contains tips on how a http/https request travels, from a browser or a curl command, to the webserver process running inside a container, in a pod, in a Kubernetes cluster, but enters the cluster via a ingress resource. For those who are familiar with those basic networking concepts like routing of a packet with regards to a http request, termination of connection, reverseproxy etc. etc., you can skip this and move on to the sections below. (or read it anyways just for context and also provide feedbacks if any)</p>"},{"location":"developer-guide/getting-started/#prerequisites","title":"Prerequisites","text":"<p>Install Go 1.14 or later.</p> <p>Note</p> <p>The project uses Go Modules</p> <p>Install Docker (v19.03.0 or later with experimental feature on)</p> <p>Important</p> <p>The majority of make tasks run as docker containers</p>"},{"location":"developer-guide/getting-started/#quick-start","title":"Quick Start","text":"<ol> <li>Fork the repository</li> <li>Clone the repository to any location in your work station</li> <li>Add a <code>GO111MODULE</code> environment variable with <code>export GO111MODULE=on</code></li> <li>Run <code>go mod download</code> to install dependencies</li> </ol>"},{"location":"developer-guide/getting-started/#local-build","title":"Local build","text":"<p>Start a local Kubernetes cluster using kind, build and deploy the ingress controller</p> <p><pre><code>make dev-env\n</code></pre> - If you are working on the v1.x.x version of this controller, and you want to create a cluster with kubernetes version 1.22, then please visit the documentation for kind, and look for how to set a custom image for the kind node (image: kindest/node...), in the kind config file.</p>"},{"location":"developer-guide/getting-started/#testing","title":"Testing","text":"<p>Run go unit tests</p> <pre><code>make test\n</code></pre> <p>Run unit-tests for lua code</p> <pre><code>make lua-test\n</code></pre> <p>Lua tests are located in the directory <code>rootfs/etc/nginx/lua/test</code></p> <p>Important</p> <p>Test files must follow the naming convention <code>&lt;mytest&gt;_test.lua</code> or it will be ignored</p> <p>Run e2e test suite</p> <pre><code>make kind-e2e-test\n</code></pre> <p>To limit the scope of the tests to execute, we can use the environment variable <code>FOCUS</code></p> <pre><code>FOCUS=\"no-auth-locations\" make kind-e2e-test\n</code></pre> <p>Note</p> <p>The variable <code>FOCUS</code> defines Ginkgo Focused Specs</p> <p>Valid values are defined in the describe definition of the e2e tests like Default Backend</p> <p>The complete list of tests can be found here</p>"},{"location":"developer-guide/getting-started/#custom-docker-image","title":"Custom docker image","text":"<p>In some cases, it can be useful to build a docker image and publish such an image to a private or custom registry location.</p> <p>This can be done setting two environment variables, <code>REGISTRY</code> and <code>TAG</code></p> <pre><code>export TAG=\"dev\"\nexport REGISTRY=\"$USER\"\n\nmake build image\n</code></pre> <p>and then publish such version with</p> <pre><code>docker push $REGISTRY/controller:$TAG\n</code></pre>"},{"location":"enhancements/","title":"Kubernetes Enhancement Proposals (KEPs)","text":"<p>A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the <code>ingress-nginx</code> project is adopting it.</p>"},{"location":"enhancements/#quick-start-for-the-kep-process","title":"Quick start for the KEP process","text":"<p>Follow the process outlined in the KEP template</p>"},{"location":"enhancements/#do-i-have-to-use-the-kep-process","title":"Do I have to use the KEP process?","text":"<p>No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record.</p> <p>KEPs are only required when the changes are wide ranging and impact most of the project.</p>"},{"location":"enhancements/#why-would-i-want-to-use-the-kep-process","title":"Why would I want to use the KEP process?","text":"<p>Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata.</p> <p>Benefits to KEP users (in the limit):</p> <ul> <li>Exposure on a kubernetes blessed web site that is findable via web search engines.</li> <li>Cross indexing of KEPs so that users can find connections and the current status of any KEP.</li> <li>A clear process with approvers and reviewers for making decisions.   This will lead to more structured decisions that stick as there is a discoverable record around the decisions.</li> </ul> <p>We are inspired by IETF RFCs, Python PEPs, and Rust RFCs.</p>"},{"location":"enhancements/20190724-only-dynamic-ssl/","title":"Remove static SSL configuration mode","text":""},{"location":"enhancements/20190724-only-dynamic-ssl/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Summary</li> <li>Motivation</li> <li>Goals</li> <li>Non-Goals</li> <li>Proposal</li> <li>Implementation Details/Notes/Constraints</li> <li>Drawbacks</li> <li>Alternatives</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#summary","title":"Summary","text":"<p>Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic.</p>"},{"location":"enhancements/20190724-only-dynamic-ssl/#motivation","title":"Motivation","text":"<p>The static configuration implies reloads, something that affects the majority of the users.</p>"},{"location":"enhancements/20190724-only-dynamic-ssl/#goals","title":"Goals","text":"<ul> <li>Deprecation of the flag <code>--enable-dynamic-certificates</code>.</li> <li>Cleanup of the codebase.</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#non-goals","title":"Non-Goals","text":"<ul> <li>Features related to certificate authentication are not changed in any way.</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#proposal","title":"Proposal","text":"<ul> <li>Remove static SSL configuration</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#implementation-detailsnotesconstraints","title":"Implementation Details/Notes/Constraints","text":"<ul> <li>Deprecate the flag Move the directives <code>ssl_certificate</code> and <code>ssl_certificate_key</code> from each server block to the <code>http</code> section. These settings are required to avoid NGINX errors in the logs.</li> <li>Remove any action of the flag <code>--enable-dynamic-certificates</code></li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#drawbacks","title":"Drawbacks","text":""},{"location":"enhancements/20190724-only-dynamic-ssl/#alternatives","title":"Alternatives","text":"<p>Keep both implementations</p>"},{"location":"enhancements/20190815-zone-aware-routing/","title":"Availability zone aware routing","text":""},{"location":"enhancements/20190815-zone-aware-routing/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Availability zone aware routing</li> <li>Table of Contents</li> <li>Summary</li> <li>Motivation<ul> <li>Goals</li> <li>Non-Goals</li> </ul> </li> <li>Proposal</li> <li>Implementation History</li> <li>Drawbacks [optional]</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#summary","title":"Summary","text":"<p>Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint.</p>"},{"location":"enhancements/20190815-zone-aware-routing/#motivation","title":"Motivation","text":"<p>When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money.</p> <p>At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic.</p> <p>This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost.</p> <p>Arguably inter-zone network latency should also be better than cross-zone.</p>"},{"location":"enhancements/20190815-zone-aware-routing/#goals","title":"Goals","text":"<ul> <li>Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying</li> <li>This should not impact canary feature</li> <li>ingress-nginx should be able to operate successfully if there are no zonal endpoints</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#non-goals","title":"Non-Goals","text":"<ul> <li>This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone</li> <li>This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#proposal","title":"Proposal","text":"<p>The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior.</p> <p>Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that.</p> <p>How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the <code>failure-domain.beta.kubernetes.io/zone</code> annotation. Then we can pass that value to Lua land through Nginx configuration when loading <code>lua_ingress.lua</code> module in <code>init_by_lua</code> phase.</p> <p>How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using <code>.subsets.addresses[i].nodeName</code> and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes <code>failure-domain.beta.kubernetes.io/zone</code> annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead.</p> <p>Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on,  it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded.</p> <p>How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer.</p> <p>We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem.</p>"},{"location":"enhancements/20190815-zone-aware-routing/#implementation-history","title":"Implementation History","text":"<ul> <li>initial version of KEP is shipped</li> <li>proposal and implementation details are done</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#drawbacks-optional","title":"Drawbacks [optional]","text":"<p>More load on the Kubernetes API server.</p>"},{"location":"enhancements/20231001-split-containers/","title":"Proposal to split containers","text":"<ul> <li>All the NGINX files should live on one container</li> <li>No file other than NGINX files should exist on this container</li> <li>This includes not mounting the service account</li> <li>All the controller files should live on a different container</li> <li>Controller container should have bare minimum to work (just go program)</li> <li> <p>ServiceAccount should be mounted just on controller</p> </li> <li> <p>Inside nginx container, there should be a really small http listener just able  to start, stop and reload NGINX</p> </li> </ul>"},{"location":"enhancements/20231001-split-containers/#roadmap-what-needs-to-be-done","title":"Roadmap (what needs to be done)","text":"<ul> <li>Map what needs to be done to mount the SA just on controller container</li> <li>Map all the required files for NGINX to work</li> <li>Map all the required network calls between controller and NGINX</li> <li>eg.: Dynamic lua reconfiguration</li> <li>Map problematic features that will need attention</li> <li>SSLPassthrough today happens on controller process and needs to happen on NGINX</li> </ul>"},{"location":"enhancements/20231001-split-containers/#ports-and-endpoints-on-nginx-container","title":"Ports and endpoints on NGINX container","text":"<ul> <li>Public HTTP/HTTPs port - 80 and 443</li> <li>Lua configuration port - 10246 (HTTP) and 10247 (Stream)</li> <li>3333 (temp) - Dataplane controller http server</li> <li>/reload - (POST) Reloads the configuration.<ul> <li>\"config\" argument is the location of temporary file that should be used / moved to nginx.conf</li> </ul> </li> <li>/test - (POST) Test the configuration of a given file location<ul> <li>\"config\" argument is the location of temporary file that should be tested</li> </ul> </li> </ul>"},{"location":"enhancements/20231001-split-containers/#mounting-empty-sa-on-controller-container","title":"Mounting empty SA on controller container","text":"<pre><code>kind: Pod\napiVersion: v1\nmetadata:\n  name: test\nspec:\n  containers:\n  - name: nginx\n    image: nginx:latest\n    ports:\n    - containerPort: 80\n  - name: othernginx\n    image: alpine:latest\n    command: [\"/bin/sh\"]\n    args: [\"-c\", \"while true; do date; sleep 3; done\"]\n    volumeMounts:\n    - mountPath: /var/run/secrets/kubernetes.io/serviceaccount\n      name: emptysecret\n  volumes:\n  - name: emptysecret\n    emptyDir:\n      sizeLimit: 1Mi\n</code></pre>"},{"location":"enhancements/20231001-split-containers/#mapped-folders-on-nginx-configuration","title":"Mapped folders on NGINX configuration","text":"<p>WARNING We need to be aware of inter mount containers and inode problems. If we  mount a file instead of a directory, it may take time to reflect the file value on  the target container</p> <ul> <li>\"/etc/nginx/lua/?.lua;/etc/nginx/lua/vendor/?.lua;;\"; - Lua scripts</li> <li>\"/var/log/nginx\" - NGINX logs</li> <li>\"/tmp/nginx (nginx.pid)\" - NGINX pid directory / file, fcgi socket, etc</li> <li>\" /etc/nginx/geoip\" - GeoIP database directory - OK - /etc/ingress-controller/geoip</li> <li>/etc/nginx/mime.types - Mime types</li> <li>/etc/ingress-controller/ssl - SSL directory (fake cert, auth cert)</li> <li>/etc/ingress-controller/auth - Authentication files</li> <li>/etc/nginx/modsecurity - Modsecurity configuration</li> <li>/etc/nginx/owasp-modsecurity-crs - Modsecurity rules</li> <li>/etc/nginx/tickets.key - SSL tickets - OK - /etc/ingress-controller/tickets.key</li> <li>/etc/nginx/opentelemetry.toml - OTEL config - OK - /etc/ingress-controller/telemetry</li> <li>/etc/nginx/opentracing.json - Opentracing config - OK - /etc/ingress-controller/telemetry</li> <li>/etc/nginx/modules - NGINX modules</li> <li>/etc/nginx/fastcgi_params (maybe) - fcgi params</li> <li>/etc/nginx/template - Template, may be used by controller only</li> </ul>"},{"location":"enhancements/20231001-split-containers/#list-of-modules","title":"List of modules","text":"<pre><code>ngx_http_auth_digest_module.so    ngx_http_modsecurity_module.so\nngx_http_brotli_filter_module.so  ngx_http_opentracing_module.so\nngx_http_brotli_static_module.so  ngx_stream_geoip2_module.so\nngx_http_geoip2_module.so\n</code></pre>"},{"location":"enhancements/20231001-split-containers/#list-of-files-that-may-be-removed","title":"List of files that may be removed","text":"<pre><code>-rw-r--r--    1 www-data www-data      1077 Jun 23 19:44 fastcgi.conf\n-rw-r--r--    1 www-data www-data      1077 Jun 23 19:44 fastcgi.conf.default\n-rw-r--r--    1 www-data www-data      1007 Jun 23 19:44 fastcgi_params\n-rw-r--r--    1 www-data www-data      1007 Jun 23 19:44 fastcgi_params.default\ndrwxr-xr-x    2 www-data www-data      4096 Jun 23 19:34 geoip\n-rw-r--r--    1 www-data www-data      2837 Jun 23 19:44 koi-utf\n-rw-r--r--    1 www-data www-data      2223 Jun 23 19:44 koi-win\ndrwxr-xr-x    6 www-data www-data      4096 Sep 19 14:13 lua\n-rw-r--r--    1 www-data www-data      5349 Jun 23 19:44 mime.types\n-rw-r--r--    1 www-data www-data      5349 Jun 23 19:44 mime.types.default\ndrwxr-xr-x    2 www-data www-data      4096 Jun 23 19:44 modsecurity\ndrwxr-xr-x    2 www-data www-data      4096 Jun 23 19:44 modules\n-rw-r--r--    1 www-data www-data     18275 Oct  1 21:28 nginx.conf\n-rw-r--r--    1 www-data www-data      2656 Jun 23 19:44 nginx.conf.default\n-rwx------    1 www-data www-data       420 Oct  1 21:28 opentelemetry.toml\n-rw-r--r--    1 www-data www-data         2 Oct  1 21:28 opentracing.json\ndrwxr-xr-x    7 www-data www-data      4096 Jun 23 19:44 owasp-modsecurity-crs\n-rw-r--r--    1 www-data www-data       636 Jun 23 19:44 scgi_params\n-rw-r--r--    1 www-data www-data       636 Jun 23 19:44 scgi_params.default\ndrwxr-xr-x    2 www-data www-data      4096 Sep 19 14:13 template\n-rw-r--r--    1 www-data www-data       664 Jun 23 19:44 uwsgi_params\n-rw-r--r--    1 www-data www-data       664 Jun 23 19:44 uwsgi_params.default\n-rw-r--r--    1 www-data www-data      3610 Jun 23 19:44 win-utf\n</code></pre>"},{"location":"enhancements/YYYYMMDD-kep-template/","title":"Title","text":"<p>This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review.</p> <p>The title should be lowercased and spaces/punctuation should be replaced with <code>-</code>.</p> <p>To get started with this template:</p> <ol> <li>Make a copy of this template.   Create a copy of this template and name it <code>YYYYMMDD-my-title.md</code>, where <code>YYYYMMDD</code> is the date the KEP was first drafted.</li> <li>Fill out the \"overview\" sections.   This includes the Summary and Motivation sections.   These should be easy if you've preflighted the idea of the KEP in an issue.</li> <li>Create a PR.   Assign it to folks that are sponsoring this process.</li> <li>Create an issue   When filing an enhancement tracking issue, please ensure to complete all fields in the template.</li> <li>Merge early.   Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly.   The best way to do this is to just start with the \"Overview\" sections and fill out details incrementally in follow on PRs.   View anything marked as a <code>provisional</code> as a working document and subject to change.   Aim for single topic PRs to keep discussions focused.   If you disagree with what is already in a document, open a new PR with suggested changes.</li> </ol> <p>The canonical place for the latest set of instructions (and the likely source of this file) is here.</p> <p>The <code>Metadata</code> section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#table-of-contents","title":"Table of Contents","text":"<p>A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template.</p> <p>Ensure the TOC is wrapped with <code>&lt;!-- toc --&amp;rt;&lt;!-- /toc --&amp;rt;</code> tags, and then generate with <code>hack/update-toc.sh</code>.</p> <ul> <li>Summary</li> <li>Motivation</li> <li>Goals</li> <li>Non-Goals</li> <li>Proposal</li> <li>User Stories [optional]<ul> <li>Story 1</li> <li>Story 2</li> </ul> </li> <li>Implementation Details/Notes/Constraints [optional]</li> <li>Risks and Mitigations</li> <li>Design Details</li> <li>Test Plan<ul> <li>Removing a deprecated flag</li> </ul> </li> <li>Implementation History</li> <li>Drawbacks [optional]</li> <li>Alternatives [optional]</li> </ul>"},{"location":"enhancements/YYYYMMDD-kep-template/#summary","title":"Summary","text":"<p>The <code>Summary</code> section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself.</p> <p>A good summary is probably at least a paragraph in length.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#motivation","title":"Motivation","text":"<p>This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#goals","title":"Goals","text":"<p>List the specific goals of the KEP. How will we know that this has succeeded?</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#non-goals","title":"Non-Goals","text":"<p>What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#proposal","title":"Proposal","text":"<p>This is where we get down to the nitty gritty of what the proposal actually is.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#user-stories-optional","title":"User Stories [optional]","text":"<p>Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the \"how\" of the system. The goal here is to make this feel real for users without getting bogged down.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#story-1","title":"Story 1","text":""},{"location":"enhancements/YYYYMMDD-kep-template/#story-2","title":"Story 2","text":""},{"location":"enhancements/YYYYMMDD-kep-template/#implementation-detailsnotesconstraints-optional","title":"Implementation Details/Notes/Constraints [optional]","text":"<p>What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#risks-and-mitigations","title":"Risks and Mitigations","text":"<p>What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem.</p> <p>How will security be reviewed and by whom? How will UX be reviewed and by whom?</p> <p>Consider including folks that also work outside project.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#design-details","title":"Design Details","text":""},{"location":"enhancements/YYYYMMDD-kep-template/#test-plan","title":"Test Plan","text":"<p>Note: Section not required until targeted at a release.</p> <p>Consider the following in developing a test plan for this enhancement:</p> <ul> <li>Will there be e2e and integration tests, in addition to unit tests?</li> <li>How will it be tested in isolation vs with other components?</li> </ul> <p>No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out.</p> <p>All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#removing-a-deprecated-flag","title":"Removing a deprecated flag","text":"<ul> <li>Announce deprecation and support policy of the existing flag</li> <li>Two versions passed since introducing the functionality which deprecates the flag (to address version skew)</li> <li>Address feedback on usage/changed behavior, provided on GitHub issues</li> <li>Deprecate the flag</li> </ul>"},{"location":"enhancements/YYYYMMDD-kep-template/#implementation-history","title":"Implementation History","text":"<p>Major milestones in the life cycle of a KEP should be tracked in <code>Implementation History</code>. Major milestones might include</p> <ul> <li>the <code>Summary</code> and <code>Motivation</code> sections being merged signaling acceptance</li> <li>the <code>Proposal</code> section being merged signaling agreement on a proposed design</li> <li>the date implementation started</li> <li>the first Kubernetes release where an initial version of the KEP was available</li> <li>the version of Kubernetes where the KEP graduated to general availability</li> <li>when the KEP was retired or superseded</li> </ul>"},{"location":"enhancements/YYYYMMDD-kep-template/#drawbacks-optional","title":"Drawbacks [optional]","text":"<p>Why should this KEP not be implemented.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#alternatives-optional","title":"Alternatives [optional]","text":"<p>Similar to the <code>Drawbacks</code> section the <code>Alternatives</code> section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.</p>"},{"location":"examples/","title":"Ingress examples","text":"<p>This directory contains a catalog of examples on how to run, configure and scale Ingress. Please review the prerequisites before trying them.</p> <p>The examples on these pages include the <code>spec.ingressClassName</code> field which replaces the deprecated <code>kubernetes.io/ingress.class: nginx</code> annotation. Users of ingress-nginx &lt; 1.0.0 (Helm chart &lt; 4.0.0) should use the legacy documentation.</p> <p>For more information, check out the Migration to apiVersion networking.k8s.io/v1 guide.</p> Category Name Description Complexity Level Apps Docker Registry TODO TODO Auth Basic authentication password protect your website Intermediate Auth Client certificate authentication secure your website with client certificate authentication Intermediate Auth External authentication plugin defer to an external authentication service Intermediate Auth OAuth external auth TODO TODO Customization Configuration snippets customize nginx location configuration using annotations Advanced Customization Custom configuration TODO TODO Customization Custom DH parameters for perfect forward secrecy TODO TODO Customization Custom errors serve custom error pages from the default backend Intermediate Customization Custom headers set custom headers before sending traffic to backends Advanced Customization External authentication with response header propagation TODO TODO Customization Sysctl tuning TODO TODO Features Rewrite TODO TODO Features Session stickiness route requests consistently to the same endpoint Advanced Features Canary Deployments weighted canary routing to a seperate deployment Intermediate Scaling Static IP a single ingress gets a single static IP Intermediate TLS Multi TLS certificate termination TODO TODO TLS TLS termination TODO TODO"},{"location":"examples/PREREQUISITES/","title":"Prerequisites","text":"<p>Many of the examples in this directory have common prerequisites.</p>"},{"location":"examples/PREREQUISITES/#tls-certificates","title":"TLS certificates","text":"<p>Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows</p> <pre><code>$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj \"/CN=nginxsvc/O=nginxsvc\"\nGenerating a 2048 bit RSA private key\n................+++\n................+++\nwriting new private key to 'tls.key'\n-----\n\n$ kubectl create secret tls tls-secret --key tls.key --cert tls.crt\nsecret \"tls-secret\" created\n</code></pre> <p>Note: If using CA Authentication, described below, you will need to sign the server certificate with the CA.</p>"},{"location":"examples/PREREQUISITES/#client-certificate-authentication","title":"Client Certificate Authentication","text":"<p>CA Authentication also known as Mutual Authentication allows both the server and client to verify each others identity via a common CA.</p> <p>We have a CA Certificate which we usually obtain from a Certificate Authority and use that to sign both our server certificate and client certificate. Then every time we want to access our backend, we must pass the client certificate.</p> <p>These instructions are based on the following blog</p> <p>Generate the CA Key and Certificate:</p> <pre><code>openssl req -x509 -sha256 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 356 -nodes -subj '/CN=My Cert Authority'\n</code></pre> <p>Generate the Server Key, and Certificate and Sign with the CA Certificate:</p> <pre><code>openssl req -new -newkey rsa:4096 -keyout server.key -out server.csr -nodes -subj '/CN=mydomain.com'\nopenssl x509 -req -sha256 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt\n</code></pre> <p>Generate the Client Key, and Certificate and Sign with the CA Certificate:</p> <pre><code>openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=My Client'\nopenssl x509 -req -sha256 -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 02 -out client.crt\n</code></pre> <p>Once this is complete you can continue to follow the instructions here</p>"},{"location":"examples/PREREQUISITES/#test-http-service","title":"Test HTTP Service","text":"<p>All examples that require a test HTTP Service use the standard http-svc pod, which you can deploy as follows</p> <pre><code>$ kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/http-svc.yaml\nservice \"http-svc\" created\nreplicationcontroller \"http-svc\" created\n\n$ kubectl get po\nNAME             READY     STATUS    RESTARTS   AGE\nhttp-svc-p1t3t   1/1       Running   0          1d\n\n$ kubectl get svc\nNAME             CLUSTER-IP     EXTERNAL-IP   PORT(S)            AGE\nhttp-svc         10.0.122.116   &lt;pending&gt;     80:30301/TCP       1d\n</code></pre> <p>You can test that the HTTP Service works by exposing it temporarily</p> <pre><code>$ kubectl patch svc http-svc -p '{\"spec\":{\"type\": \"LoadBalancer\"}}'\n\"http-svc\" patched\n\n$ kubectl get svc http-svc\nNAME             CLUSTER-IP     EXTERNAL-IP   PORT(S)            AGE\nhttp-svc         10.0.122.116   &lt;pending&gt;     80:30301/TCP       1d\n\n$ kubectl describe svc http-svc\nName:                   http-svc\nNamespace:              default\nLabels:                 app=http-svc\nSelector:               app=http-svc\nType:                   LoadBalancer\nIP:                     10.0.122.116\nLoadBalancer Ingress:   108.59.87.136\nPort:                   http    80/TCP\nNodePort:               http    30301/TCP\nEndpoints:              10.180.1.6:8080\nSession Affinity:       None\nEvents:\n  FirstSeen LastSeen    Count   From            SubObjectPath   Type        Reason          Message\n  --------- --------    -----   ----            -------------   --------    ------          -------\n  1m        1m      1   {service-controller }           Normal      Type            ClusterIP -&gt; LoadBalancer\n  1m        1m      1   {service-controller }           Normal      CreatingLoadBalancer    Creating load balancer\n  16s       16s     1   {service-controller }           Normal      CreatedLoadBalancer Created load balancer\n\n$ curl 108.59.87.136\nCLIENT VALUES:\nclient_address=10.240.0.3\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://108.59.87.136:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nhost=108.59.87.136\nuser-agent=curl/7.46.0\nBODY:\n-no body in request-\n\n$ kubectl patch svc http-svc -p '{\"spec\":{\"type\": \"NodePort\"}}'\n\"http-svc\" patched\n</code></pre>"},{"location":"examples/affinity/cookie/","title":"Sticky sessions","text":"<p>This example demonstrates how to achieve session affinity using cookies.</p>"},{"location":"examples/affinity/cookie/#deployment","title":"Deployment","text":"<p>Session affinity can be configured using the following annotations:</p> Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to <code>cookie</code> to enable session affinity string (NGINX only supports <code>cookie</code>) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use <code>balanced</code> to redistribute some sessions when scaling pods or <code>persistent</code> for maximum stickiness. <code>balanced</code> (default) or <code>persistent</code> nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is <code>sticky</code>, and canaries respect session affinity configuration. Set this to <code>legacy</code> to restore original canary behavior, when session affinity parameters were not respected. <code>sticky</code> (default) or <code>legacy</code> nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to <code>INGRESSCOOKIE</code>) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request <code>\"true\"</code> or <code>\"false\"</code> nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite <code>SameSite</code> attribute to apply to the cookie Browser accepted values are <code>None</code>, <code>Lax</code>, and <code>Strict</code> nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit <code>SameSite=None</code> attribute for older browsers which reject the more-recently defined <code>SameSite=None</code> value <code>\"true\"</code> or <code>\"false\"</code> nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the <code>Max-Age</code> cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an <code>Expires</code> cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to <code>false</code> nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to <code>true</code> and previous attempt failed, sticky cookie will be changed to point to another upstream. <code>true</code> or <code>false</code> (defaults to <code>false</code>) <p>You can create the session affinity example Ingress to test this:</p> <pre><code>kubectl create -f ingress.yaml\n</code></pre>"},{"location":"examples/affinity/cookie/#validation","title":"Validation","text":"<p>You can confirm that the Ingress works:</p> <pre><code>$ kubectl describe ing nginx-test\nName:           nginx-test\nNamespace:      default\nAddress:\nDefault backend:    default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)\nRules:\n  Host                          Path    Backends\n  ----                          ----    --------\n  stickyingress.example.com\n                                /        nginx-service:80 (&lt;none&gt;)\nAnnotations:\n  affinity: cookie\n  session-cookie-name:      INGRESSCOOKIE\n  session-cookie-expires: 172800\n  session-cookie-max-age: 172800\nEvents:\n  FirstSeen LastSeen    Count   From                SubObjectPath   Type        Reason  Message\n  --------- --------    -----   ----                -------------   --------    ------  -------\n  7s        7s      1   {ingress-nginx-controller }         Normal      CREATE  default/nginx-test\n\n\n$ curl -I http://stickyingress.example.com\nHTTP/1.1 200 OK\nServer: nginx/1.11.9\nDate: Fri, 10 Feb 2017 14:11:12 GMT\nContent-Type: text/html\nContent-Length: 612\nConnection: keep-alive\nSet-Cookie: INGRESSCOOKIE=a9907b79b248140b56bb13723f72b67697baac3d; Expires=Sun, 12-Feb-17 14:11:12 GMT; Max-Age=172800; Path=/; HttpOnly\nLast-Modified: Tue, 24 Jan 2017 14:02:19 GMT\nETag: \"58875e6b-264\"\nAccept-Ranges: bytes\n</code></pre> <p>In the example above, you can see that the response contains a <code>Set-Cookie</code> header with the settings we have defined. This cookie is created by the Ingress-Nginx Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an <code>Expires</code> directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie.</p> <p>If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded.</p> <p>When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change.</p>"},{"location":"examples/affinity/cookie/#caveats","title":"Caveats","text":"<p>When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this.</p>"},{"location":"examples/auth/basic/","title":"Basic Authentication","text":"<p>This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with <code>htpasswd</code>. It's important the file generated is named <code>auth</code> (actually - that the secret has a key <code>data.auth</code>), otherwise the ingress-controller returns a 503.</p>"},{"location":"examples/auth/basic/#create-htpasswd-file","title":"Create htpasswd file","text":"<pre><code>$ htpasswd -c auth foo\nNew password: &lt;bar&gt;\nNew password:\nRe-type new password:\nAdding password for user foo\n</code></pre>"},{"location":"examples/auth/basic/#convert-htpasswd-into-a-secret","title":"Convert htpasswd into a secret","text":"<pre><code>$ kubectl create secret generic basic-auth --from-file=auth\nsecret \"basic-auth\" created\n</code></pre>"},{"location":"examples/auth/basic/#examine-secret","title":"Examine secret","text":"<pre><code>$ kubectl get secret basic-auth -o yaml\napiVersion: v1\ndata:\n  auth: Zm9vOiRhcHIxJE9GRzNYeWJwJGNrTDBGSERBa29YWUlsSDkuY3lzVDAK\nkind: Secret\nmetadata:\n  name: basic-auth\n  namespace: default\ntype: Opaque\n</code></pre>"},{"location":"examples/auth/basic/#using-kubectl-create-an-ingress-tied-to-the-basic-auth-secret","title":"Using kubectl, create an ingress tied to the basic-auth secret","text":"<pre><code>$ echo \"\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-with-auth\n  annotations:\n    # type of authentication\n    nginx.ingress.kubernetes.io/auth-type: basic\n    # name of the secret that contains the user/password definitions\n    nginx.ingress.kubernetes.io/auth-secret: basic-auth\n    # message to display with an appropriate context why the authentication is required\n    nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required - foo'\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: foo.bar.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service: \n            name: http-svc\n            port: \n              number: 80\n\" | kubectl create -f -\n</code></pre>"},{"location":"examples/auth/basic/#use-curl-to-confirm-authorization-is-required-by-the-ingress","title":"Use curl to confirm authorization is required by the ingress","text":"<pre><code>$ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com'\n*   Trying 10.2.29.4...\n* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: foo.bar.com\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 401 Unauthorized\n&lt; Server: nginx/1.10.0\n&lt; Date: Wed, 11 May 2016 05:27:23 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 195\n&lt; Connection: keep-alive\n&lt; WWW-Authenticate: Basic realm=\"Authentication Required - foo\"\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;401 Authorization Required&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;401 Authorization Required&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.10.0&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 10.2.29.4 left intact\n</code></pre>"},{"location":"examples/auth/basic/#use-curl-with-the-correct-credentials-to-connect-to-the-ingress","title":"Use curl with the correct credentials to connect to the ingress","text":"<pre><code>$ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com' -u 'foo:bar'\n*   Trying 10.2.29.4...\n* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0)\n* Server auth using Basic with user 'foo'\n&gt; GET / HTTP/1.1\n&gt; Host: foo.bar.com\n&gt; Authorization: Basic Zm9vOmJhcg==\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.10.0\n&lt; Date: Wed, 11 May 2016 06:05:26 GMT\n&lt; Content-Type: text/plain\n&lt; Transfer-Encoding: chunked\n&lt; Connection: keep-alive\n&lt; Vary: Accept-Encoding\n&lt;\nCLIENT VALUES:\nclient_address=10.2.29.4\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://foo.bar.com:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nconnection=close\nhost=foo.bar.com\nuser-agent=curl/7.43.0\nx-request-id=e426c7829ef9f3b18d40730857c3eddb\nx-forwarded-for=10.2.29.1\nx-forwarded-host=foo.bar.com\nx-forwarded-port=80\nx-forwarded-proto=http\nx-real-ip=10.2.29.1\nx-scheme=http\nBODY:\n* Connection #0 to host 10.2.29.4 left intact\n-no body in request-\n</code></pre>"},{"location":"examples/auth/client-certs/","title":"Client Certificate Authentication","text":"<p>It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource.</p> <p>Before getting started you must have the following Certificates configured:</p> <ol> <li>CA certificate and Key (Intermediate Certs need to be in CA)</li> <li>Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use)</li> <li>Client Certificate (Signed by CA) and Key</li> </ol> <p>For more details on the generation process, checkout the Prerequisite docs.</p> <p>You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following:</p> <pre><code>openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem\n</code></pre> <p>Then, you can concatenate them all into one file, named 'ca.crt' with the following:</p> <pre><code>cat certificate1.crt certificate2.crt certificate3.crt &gt;&gt; ca.crt\n</code></pre> <p>Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error.</p>"},{"location":"examples/auth/client-certs/#creating-certificate-secrets","title":"Creating Certificate Secrets","text":"<p>There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly.</p> <ul> <li> <p>You can create a secret containing just the CA certificate and another     Secret containing the Server Certificate which is Signed by the CA.</p> <pre><code>kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt\nkubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key\n</code></pre> </li> <li> <p>You can create a secret containing CA certificate along with the Server     Certificate that can be used for both TLS and Client Auth.</p> <pre><code>kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt\n</code></pre> </li> <li> <p>If you want to also enable Certificate Revocation List verification you can    create the secret also containing the CRL file in PEM format:    <pre><code>kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt --from-file=ca.crl=ca.crl\n</code></pre></p> </li> </ul> <p>Note: The CA Certificate must contain the trusted certificate authority chain to verify client certificates.</p>"},{"location":"examples/auth/client-certs/#setup-instructions","title":"Setup Instructions","text":"<ol> <li>Add the annotations as provided in the ingress.yaml example to your own ingress resources as required.</li> <li>Test by performing a curl against the Ingress Path without the Client Cert and expect a Status Code 400.</li> <li>Test by performing a curl against the Ingress Path with the Client Cert and expect a Status Code 200.</li> </ol>"},{"location":"examples/auth/external-auth/","title":"External Basic Authentication","text":""},{"location":"examples/auth/external-auth/#example-1","title":"Example 1","text":"<p>Use an external service (Basic Auth) located in <code>https://httpbin.org</code></p> <pre><code>$ kubectl create -f ingress.yaml\ningress \"external-auth\" created\n\n$ kubectl get ing external-auth\nNAME            HOSTS                         ADDRESS       PORTS     AGE\nexternal-auth   external-auth-01.sample.com   172.17.4.99   80        13s\n\n$ kubectl get ing external-auth -o yaml\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd\n  creationTimestamp: 2016-10-03T13:50:35Z\n  generation: 1\n  name: external-auth\n  namespace: default\n  resourceVersion: \"2068378\"\n  selfLink: /apis/networking/v1/namespaces/default/ingresses/external-auth\n  uid: 5c388f1d-8970-11e6-9004-080027d2dc94\nspec:\n  rules:\n  - host: external-auth-01.sample.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service: \n            name: http-svc\n            port: \n              number: 80\nstatus:\n  loadBalancer:\n    ingress:\n    - ip: 172.17.4.99\n$\n</code></pre>"},{"location":"examples/auth/external-auth/#test-1-no-usernamepassword-expect-code-401","title":"Test 1: no username/password (expect code 401)","text":"<pre><code>$ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com'\n* Rebuilt URL to: http://172.17.4.99/\n*   Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: external-auth-01.sample.com\n&gt; User-Agent: curl/7.50.1\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 401 Unauthorized\n&lt; Server: nginx/1.11.3\n&lt; Date: Mon, 03 Oct 2016 14:52:08 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 195\n&lt; Connection: keep-alive\n&lt; WWW-Authenticate: Basic realm=\"Fake Realm\"\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;401 Authorization Required&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;401 Authorization Required&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.11.3&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 172.17.4.99 left intact\n</code></pre>"},{"location":"examples/auth/external-auth/#test-2-valid-usernamepassword-expect-code-200","title":"Test 2: valid username/password (expect code 200)","text":"<pre><code>$ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:passwd'\n* Rebuilt URL to: http://172.17.4.99/\n*   Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n* Server auth using Basic with user 'user'\n&gt; GET / HTTP/1.1\n&gt; Host: external-auth-01.sample.com\n&gt; Authorization: Basic dXNlcjpwYXNzd2Q=\n&gt; User-Agent: curl/7.50.1\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.3\n&lt; Date: Mon, 03 Oct 2016 14:52:50 GMT\n&lt; Content-Type: text/plain\n&lt; Transfer-Encoding: chunked\n&lt; Connection: keep-alive\n&lt;\nCLIENT VALUES:\nclient_address=10.2.60.2\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://external-auth-01.sample.com:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nauthorization=Basic dXNlcjpwYXNzd2Q=\nconnection=close\nhost=external-auth-01.sample.com\nuser-agent=curl/7.50.1\nx-forwarded-for=10.2.60.1\nx-forwarded-host=external-auth-01.sample.com\nx-forwarded-port=80\nx-forwarded-proto=http\nx-real-ip=10.2.60.1\nBODY:\n* Connection #0 to host 172.17.4.99 left intact\n-no body in request-\n</code></pre>"},{"location":"examples/auth/external-auth/#test-3-invalid-usernamepassword-expect-code-401","title":"Test 3: invalid username/password (expect code 401)","text":"<pre><code>curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:user'\n* Rebuilt URL to: http://172.17.4.99/\n*   Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n* Server auth using Basic with user 'user'\n&gt; GET / HTTP/1.1\n&gt; Host: external-auth-01.sample.com\n&gt; Authorization: Basic dXNlcjp1c2Vy\n&gt; User-Agent: curl/7.50.1\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 401 Unauthorized\n&lt; Server: nginx/1.11.3\n&lt; Date: Mon, 03 Oct 2016 14:53:04 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 195\n&lt; Connection: keep-alive\n* Authentication problem. Ignoring this.\n&lt; WWW-Authenticate: Basic realm=\"Fake Realm\"\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;401 Authorization Required&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;401 Authorization Required&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.11.3&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 172.17.4.99 left intact\n</code></pre>"},{"location":"examples/auth/oauth-external-auth/","title":"External OAUTH Authentication","text":""},{"location":"examples/auth/oauth-external-auth/#overview","title":"Overview","text":"<p>The <code>auth-url</code> and <code>auth-signin</code> annotations allow you to use an external authentication provider to protect your Ingress resources.</p> <p>Important</p> <p>This annotation requires <code>ingress-nginx-controller v0.9.0</code> or greater.</p>"},{"location":"examples/auth/oauth-external-auth/#key-detail","title":"Key Detail","text":"<p>This functionality is enabled by deploying multiple Ingress objects for a single host. One Ingress object has no special annotations and handles authentication.</p> <p>Other Ingress objects can then be annotated in such a way that require the user to authenticate against the first Ingress's endpoint, and can redirect <code>401</code>s to the same endpoint.</p> <p>Sample:</p> <pre><code>...\nmetadata:\n  name: application\n  annotations:\n    nginx.ingress.kubernetes.io/auth-url: \"https://$host/oauth2/auth\"\n    nginx.ingress.kubernetes.io/auth-signin: \"https://$host/oauth2/start?rd=$escaped_request_uri\"\n...\n</code></pre>"},{"location":"examples/auth/oauth-external-auth/#example-oauth2-proxy-kubernetes-dashboard","title":"Example: OAuth2 Proxy + Kubernetes-Dashboard","text":"<p>This example will show you how to deploy <code>oauth2_proxy</code> into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using GitHub as the OAuth2 provider.</p>"},{"location":"examples/auth/oauth-external-auth/#prepare","title":"Prepare","text":"<ol> <li> <p>Install the kubernetes dashboard</p> <pre><code>kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml\n</code></pre> </li> <li> <p>Create a custom GitHub OAuth application</p> <p></p> <ul> <li>Homepage URL is the FQDN in the Ingress rule, like <code>https://foo.bar.com</code></li> <li>Authorization callback URL is the same as the base FQDN plus <code>/oauth2/callback</code>, like <code>https://foo.bar.com/oauth2/callback</code></li> </ul> <p></p> </li> <li> <p>Configure values in the file <code>oauth2-proxy.yaml</code> with the values:</p> <ul> <li>OAUTH2_PROXY_CLIENT_ID with the github <code>&lt;Client ID&gt;</code></li> <li>OAUTH2_PROXY_CLIENT_SECRET with the github <code>&lt;Client Secret&gt;</code></li> <li>OAUTH2_PROXY_COOKIE_SECRET with value of <code>python -c 'import os,base64; print(base64.b64encode(os.urandom(16)).decode(\"ascii\"))'</code></li> <li>(optional, but recommended) OAUTH2_PROXY_GITHUB_USERS with GitHub usernames to allow to login</li> <li><code>__INGRESS_HOST__</code> with a valid FQDN (e.g. <code>foo.bar.com</code>)</li> <li><code>__INGRESS_SECRET__</code> with a Secret with a valid SSL certificate</li> </ul> </li> <li> <p>Deploy the oauth2 proxy and the ingress rules by running:</p> <pre><code>$ kubectl create -f oauth2-proxy.yaml\n</code></pre> </li> </ol>"},{"location":"examples/auth/oauth-external-auth/#test","title":"Test","text":"<p>Test the integration by accessing the configured URL, e.g. <code>https://foo.bar.com</code></p> <p></p> <p></p> <p></p>"},{"location":"examples/auth/oauth-external-auth/#example-vouch-proxy-kubernetes-dashboard","title":"Example: Vouch Proxy + Kubernetes-Dashboard","text":"<p>This example will show you how to deploy <code>Vouch Proxy</code> into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using GitHub as the OAuth2 provider.</p>"},{"location":"examples/auth/oauth-external-auth/#prepare_1","title":"Prepare","text":"<ol> <li> <p>Install the kubernetes dashboard</p> <pre><code>kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml\n</code></pre> </li> <li> <p>Create a custom GitHub OAuth application</p> <p></p> <ul> <li>Homepage URL is the FQDN in the Ingress rule, like <code>https://foo.bar.com</code></li> <li>Authorization callback URL is the same as the base FQDN plus <code>/oauth2/auth</code>, like <code>https://foo.bar.com/oauth2/auth</code></li> </ul> <p></p> </li> <li> <p>Configure Vouch Proxy values in the file <code>vouch-proxy.yaml</code> with the values:</p> <ul> <li>VOUCH_COOKIE_DOMAIN with value of <code>&lt;Ingress Host&gt;</code></li> <li>OAUTH_CLIENT_ID with the github <code>&lt;Client ID&gt;</code></li> <li>OAUTH_CLIENT_SECRET with the github <code>&lt;Client Secret&gt;</code></li> <li>(optional, but recommended) VOUCH_WHITELIST with GitHub usernames to allow to login</li> <li><code>__INGRESS_HOST__</code> with a valid FQDN (e.g. <code>foo.bar.com</code>)</li> <li><code>__INGRESS_SECRET__</code> with a Secret with a valid SSL certificate</li> </ul> </li> <li> <p>Deploy Vouch Proxy and the ingress rules by running:</p> <pre><code>$ kubectl create -f vouch-proxy.yaml\n</code></pre> </li> </ol>"},{"location":"examples/auth/oauth-external-auth/#test_1","title":"Test","text":"<p>Test the integration by accessing the configured URL, e.g. <code>https://foo.bar.com</code></p> <p></p> <p></p> <p></p>"},{"location":"examples/canary/","title":"Canary","text":"<p>Ingress Nginx Has the ability to handle canary routing by setting specific annotations, the following is an example of how to configure a canary deployment with weighted canary routing.</p>"},{"location":"examples/canary/#create-your-main-deployment-and-service","title":"Create your main deployment and service","text":"<p>This is the main deployment of your application with the service that will be used to route to it</p> <pre><code>echo \"\n---\n# Deployment\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: production\n  labels:\n    app: production\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: production\n  template:\n    metadata:\n      labels:\n        app: production\n    spec:\n      containers:\n      - name: production\n        image: registry.k8s.io/ingress-nginx/e2e-test-echo@sha256:6fc5aa2994c86575975bb20a5203651207029a0d28e3f491d8a127d08baadab4\n        ports:\n        - containerPort: 80\n        env:\n          - name: NODE_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: spec.nodeName\n          - name: POD_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.name\n          - name: POD_NAMESPACE\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.namespace\n          - name: POD_IP\n            valueFrom:\n              fieldRef:\n                fieldPath: status.podIP\n---\n# Service\napiVersion: v1\nkind: Service\nmetadata:\n  name: production\n  labels:\n    app: production\nspec:\n  ports:\n  - port: 80\n    targetPort: 80\n    protocol: TCP\n    name: http\n  selector:\n    app: production\n\" | kubectl apply -f -\n</code></pre>"},{"location":"examples/canary/#create-the-canary-deployment-and-service","title":"Create the canary deployment and service","text":"<p>This is the canary deployment that will take a weighted amount of requests instead of the main deployment</p> <pre><code>echo \"\n---\n# Deployment\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: canary\n  labels:\n    app: canary\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: canary\n  template:\n    metadata:\n      labels:\n        app: canary\n    spec:\n      containers:\n      - name: canary\n        image: registry.k8s.io/ingress-nginx/e2e-test-echo@sha256:6fc5aa2994c86575975bb20a5203651207029a0d28e3f491d8a127d08baadab4\n        ports:\n        - containerPort: 80\n        env:\n          - name: NODE_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: spec.nodeName\n          - name: POD_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.name\n          - name: POD_NAMESPACE\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.namespace\n          - name: POD_IP\n            valueFrom:\n              fieldRef:\n                fieldPath: status.podIP\n---\n# Service\napiVersion: v1\nkind: Service\nmetadata:\n  name: canary\n  labels:\n    app: canary\nspec:\n  ports:\n  - port: 80\n    targetPort: 80\n    protocol: TCP\n    name: http\n  selector:\n    app: canary\n\" | kubectl apply -f -\n</code></pre>"},{"location":"examples/canary/#create-ingress-pointing-to-your-main-deployment","title":"Create Ingress Pointing To Your Main Deployment","text":"<p>Next you will need to expose your main deployment with an ingress resource, note there are no canary specific annotations on this ingress</p> <pre><code>echo \"\n---\n# Ingress\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: production\n  annotations:\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: echo.prod.mydomain.com\n    http:\n      paths:\n      - pathType: Prefix\n        path: /\n        backend:\n          service:\n            name: production\n            port:\n              number: 80\n\" | kubectl apply -f -\n</code></pre>"},{"location":"examples/canary/#create-ingress-pointing-to-your-canary-deployment","title":"Create Ingress Pointing To Your Canary Deployment","text":"<p>You will then create an Ingress that has the canary specific configuration, please pay special notice of the following:</p> <ul> <li>The host name is identical to the main ingress host name</li> <li>The <code>nginx.ingress.kubernetes.io/canary: \"true\"</code> annotation is required and   defines this as a canary annotation (if you do not have this the Ingresses   will clash)</li> <li>The <code>nginx.ingress.kubernetes.io/canary-weight: \"50\"</code> annotation dictates the   weight of the routing, in this case there is a \"50%\" chance a request will   hit the canary deployment over the main deployment <pre><code>echo \"\n---\n# Ingress\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: canary\n  annotations:\n    nginx.ingress.kubernetes.io/canary: \\\"true\\\"\n    nginx.ingress.kubernetes.io/canary-weight: \\\"50\\\"\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: echo.prod.mydomain.com\n    http:\n      paths:\n      - pathType: Prefix\n        path: /\n        backend:\n          service:\n            name: canary\n            port:\n              number: 80\n\" | kubectl apply -f -\n</code></pre></li> </ul>"},{"location":"examples/canary/#testing-your-setup","title":"Testing your setup","text":"<p>You can use the following command to test your setup (replacing INGRESS_CONTROLLER_IP with your ingresse controllers IP Address)</p> <pre><code>for i in $(seq 1 10); do curl -s --resolve echo.prod.mydomain.com:80:$INGRESS_CONTROLLER_IP echo.prod.mydomain.com  | grep \"Hostname\"; done\n</code></pre> <p>You will get the following output showing that your canary setup is working as expected:</p> <pre><code>Hostname: production-5c5f65d859-phqzc\nHostname: canary-6697778457-zkfjf\nHostname: canary-6697778457-zkfjf\nHostname: production-5c5f65d859-phqzc\nHostname: canary-6697778457-zkfjf\nHostname: production-5c5f65d859-phqzc\nHostname: production-5c5f65d859-phqzc\nHostname: production-5c5f65d859-phqzc\nHostname: canary-6697778457-zkfjf\nHostname: production-5c5f65d859-phqzc\n</code></pre>"},{"location":"examples/customization/configuration-snippets/","title":"Configuration Snippets","text":""},{"location":"examples/customization/configuration-snippets/#ingress","title":"Ingress","text":"<p>The Ingress in this example adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at an example of specifying custom headers.</p> <pre><code>kubectl apply -f ingress.yaml\n</code></pre>"},{"location":"examples/customization/configuration-snippets/#test","title":"Test","text":"<p>Check if the contents of the annotation are present in the nginx.conf file using:</p> <pre><code>kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf\n</code></pre>"},{"location":"examples/customization/custom-configuration/","title":"Custom Configuration","text":"<p>Using a ConfigMap is possible to customize the NGINX configuration</p> <p>For example, if we want to change the timeouts we need to create a ConfigMap:</p> <pre><code>$ cat configmap.yaml\napiVersion: v1\ndata:\n  proxy-connect-timeout: \"10\"\n  proxy-read-timeout: \"120\"\n  proxy-send-timeout: \"120\"\nkind: ConfigMap\nmetadata:\n  name: ingress-nginx-controller\n</code></pre> <pre><code>curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-configuration/configmap.yaml \\\n    | kubectl apply -f -\n</code></pre> <p>If the Configmap is updated, NGINX will be reloaded with the new configuration.</p>"},{"location":"examples/customization/custom-errors/","title":"Custom Errors","text":"<p>This example demonstrates how to use a custom backend to render custom error pages.</p> <p>If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment.</p>"},{"location":"examples/customization/custom-errors/#customized-default-backend","title":"Customized default backend","text":"<p>First, create the custom <code>default-backend</code>. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository.</p> <pre><code>$ kubectl create -f custom-default-backend.yaml\nservice \"nginx-errors\" created\ndeployment.apps \"nginx-errors\" created\n</code></pre> <p>This should have created a Deployment and a Service with the name <code>nginx-errors</code>.</p> <pre><code>$ kubectl get deploy,svc\nNAME                           DESIRED   CURRENT   READY     AGE\ndeployment.apps/nginx-errors   1         1         1         10s\n\nNAME                   TYPE        CLUSTER-IP  EXTERNAL-IP   PORT(S)   AGE\nservice/nginx-errors   ClusterIP   10.0.0.12   &lt;none&gt;        80/TCP    10s\n</code></pre>"},{"location":"examples/customization/custom-errors/#ingress-controller-configuration","title":"Ingress controller configuration","text":"<p>If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps:</p> <ol> <li> <p>Edit the <code>ingress-nginx-controller</code> Deployment and set the value of the <code>--default-backend-service</code> flag to the name of the    newly created error backend.</p> </li> <li> <p>Edit the <code>ingress-nginx-controller</code> ConfigMap and create the key <code>custom-http-errors</code> with a value of <code>404,503</code>.</p> </li> <li> <p>Take note of the IP address assigned to the Ingress-Nginx Controller Service.     <pre><code>$ kubectl get svc ingress-nginx\nNAME            TYPE        CLUSTER-IP  EXTERNAL-IP   PORT(S)          AGE\ningress-nginx   ClusterIP   10.0.0.13   &lt;none&gt;        80/TCP,443/TCP   10m\n</code></pre></p> </li> </ol> <p>Note</p> <p>The <code>ingress-nginx</code> Service is of type <code>ClusterIP</code> in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example.</p>"},{"location":"examples/customization/custom-errors/#testing-error-pages","title":"Testing error pages","text":"<p>Let us send a couple of HTTP requests using cURL and validate everything is working as expected.</p> <p>A request to the default backend returns a 404 error with a custom message:</p> <pre><code>$ curl -D- http://10.0.0.13/\nHTTP/1.1 404 Not Found\nServer: nginx/1.13.12\nDate: Tue, 12 Jun 2018 19:11:24 GMT\nContent-Type: */*\nTransfer-Encoding: chunked\nConnection: keep-alive\n\n&lt;span&gt;The page you're looking for could not be found.&lt;/span&gt;\n</code></pre> <p>A request with a custom <code>Accept</code> header returns the corresponding document type (JSON):</p> <pre><code>$ curl -D- -H 'Accept: application/json' http://10.0.0.13/\nHTTP/1.1 404 Not Found\nServer: nginx/1.13.12\nDate: Tue, 12 Jun 2018 19:12:36 GMT\nContent-Type: application/json\nTransfer-Encoding: chunked\nConnection: keep-alive\nVary: Accept-Encoding\n\n{ \"message\": \"The page you're looking for could not be found\" }\n</code></pre> <p>To go further with this example, feel free to deploy your own applications and Ingress objects, and validate that the responses are still in the correct format when a backend returns 503 (eg. if you scale a Deployment down to 0 replica).</p>"},{"location":"examples/customization/custom-headers/","title":"Custom Headers","text":""},{"location":"examples/customization/custom-headers/#caveats","title":"Caveats","text":"<p>Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers.</p>"},{"location":"examples/customization/custom-headers/#workaround","title":"Workaround","text":"<p>To work around this limitation, perform a rolling restart of the deployment.</p>"},{"location":"examples/customization/custom-headers/#example","title":"Example","text":"<p>This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server.</p> <p>custom-headers.yaml defines a ConfigMap in the <code>ingress-nginx</code> namespace named <code>custom-headers</code>, holding several custom X-prefixed HTTP headers.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml\n</code></pre> <p>configmap.yaml defines a ConfigMap in the <code>ingress-nginx</code> namespace named <code>ingress-nginx-controller</code>. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key <code>proxy-set-headers</code> is set to cite the previously-created <code>ingress-nginx/custom-headers</code> ConfigMap.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml\n</code></pre> <p>The Ingress-Nginx Controller will read the <code>ingress-nginx/ingress-nginx-controller</code> ConfigMap, find the <code>proxy-set-headers</code> key, read HTTP headers from the <code>ingress-nginx/custom-headers</code> ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends.</p> <p>The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml\n</code></pre>"},{"location":"examples/customization/custom-headers/#test","title":"Test","text":"<p>Check the contents of the ConfigMaps are present in the nginx.conf file using: <code>kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf</code></p>"},{"location":"examples/customization/external-auth-headers/","title":"External authentication, authentication service response headers propagation","text":"<p>This example demonstrates propagation of selected authentication service response headers to a backend service.</p> <p>Sample configuration includes:</p> <ul> <li>Sample authentication service producing several response headers</li> <li>Authentication logic is based on HTTP header: requests with header <code>User</code> containing string <code>internal</code> are considered authenticated</li> <li>After successful authentication service generates response headers <code>UserID</code> and <code>UserRole</code></li> <li>Sample echo service displaying header information</li> <li>Two ingress objects pointing to echo service</li> <li>Public, which allows access from unauthenticated users</li> <li>Private, which allows access from authenticated users only</li> </ul> <p>You can deploy the controller as follows:</p> <pre><code>$ kubectl create -f deploy/\ndeployment \"demo-auth-service\" created\nservice \"demo-auth-service\" created\ningress \"demo-auth-service\" created\ndeployment \"demo-echo-service\" created\nservice \"demo-echo-service\" created\ningress \"public-demo-echo-service\" created\ningress \"secure-demo-echo-service\" created\n\n$ kubectl get po\nNAME                                        READY     STATUS    RESTARTS   AGE\ndemo-auth-service-2769076528-7g9mh          1/1       Running            0          30s\ndemo-echo-service-3636052215-3vw8c          1/1       Running            0          29s\n\nkubectl get ing\nNAME                       HOSTS                                 ADDRESS   PORTS     AGE\npublic-demo-echo-service   public-demo-echo-service.kube.local             80        1m\nsecure-demo-echo-service   secure-demo-echo-service.kube.local             80        1m\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-1-public-service-with-no-auth-header","title":"Test 1: public service with no auth header","text":"<pre><code>$ curl -H 'Host: public-demo-echo-service.kube.local' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: public-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:19:21 GMT\n&lt; Content-Type: text/plain; charset=utf-8\n&lt; Content-Length: 20\n&lt; Connection: keep-alive\n&lt;\n* Connection #0 to host 192.168.99.100 left intact\nUserID: , UserRole:\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-2-secure-service-with-no-auth-header","title":"Test 2: secure service with no auth header","text":"<pre><code>$ curl -H 'Host: secure-demo-echo-service.kube.local' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: secure-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 403 Forbidden\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:18:48 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 170\n&lt; Connection: keep-alive\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;403 Forbidden&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;403 Forbidden&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.11.10&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 192.168.99.100 left intact\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-3-public-service-with-valid-auth-header","title":"Test 3: public service with valid auth header","text":"<pre><code>$ curl -H 'Host: public-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: public-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt; User:internal\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:19:59 GMT\n&lt; Content-Type: text/plain; charset=utf-8\n&lt; Content-Length: 44\n&lt; Connection: keep-alive\n&lt;\n* Connection #0 to host 192.168.99.100 left intact\nUserID: 1443635317331776148, UserRole: admin\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-4-secure-service-with-valid-auth-header","title":"Test 4: secure service with valid auth header","text":"<pre><code>$ curl -H 'Host: secure-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: secure-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt; User:internal\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:17:23 GMT\n&lt; Content-Type: text/plain; charset=utf-8\n&lt; Content-Length: 43\n&lt; Connection: keep-alive\n&lt;\n* Connection #0 to host 192.168.99.100 left intact\nUserID: 605394647632969758, UserRole: admin\n</code></pre>"},{"location":"examples/customization/jwt/","title":"Accommodation for JWT","text":"<p>JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it.</p>"},{"location":"examples/customization/jwt/#symptoms","title":"Symptoms","text":"<p>If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough.</p> <p>To be 100% sure look at the logs of the <code>ingress-nginx-controller</code> pod, you should see something like this:</p> <pre><code>upstream sent too big header while reading response header from upstream...\n</code></pre>"},{"location":"examples/customization/jwt/#increase-buffer-size-for-headers","title":"Increase buffer size for headers","text":"<p>In nginx, we want to modify the property <code>proxy-buffer-size</code>. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered.</p>"},{"location":"examples/customization/jwt/#using-helm","title":"Using helm","text":"<p>If you're using helm you can simply use the <code>config</code> properties. <pre><code> # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/\n  config: \n    proxy-buffer-size: 16k\n</code></pre></p>"},{"location":"examples/customization/jwt/#manually-in-kubernetes-config-files","title":"Manually in kubernetes config files","text":"<p>If you use an already generated config from for a provider, you will have to change the <code>controller-configmap.yaml</code></p> <pre><code>---\n# Source: ingress-nginx/templates/controller-configmap.yaml\napiVersion: v1\nkind: ConfigMap\n# ...\ndata:\n  #...\n  proxy-buffer-size: \"16k\"\n</code></pre> <p>References:  * Custom Configuration</p>"},{"location":"examples/customization/ssl-dh-param/","title":"Custom DH parameters for perfect forward secrecy","text":"<p>This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with \"Perfect Forward Secrecy\".</p>"},{"location":"examples/customization/ssl-dh-param/#custom-configuration","title":"Custom configuration","text":"<pre><code>$ cat configmap.yaml\napiVersion: v1\ndata:\n  ssl-dh-param: \"ingress-nginx/lb-dhparam\"\nkind: ConfigMap\nmetadata:\n  name: ingress-nginx-controller\n  namespace: ingress-nginx\n  labels:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\n</code></pre> <pre><code>$ kubectl create -f configmap.yaml\n</code></pre>"},{"location":"examples/customization/ssl-dh-param/#custom-dh-parameters-secret","title":"Custom DH parameters secret","text":"<pre><code>$ openssl dhparam 4096 2&gt; /dev/null | base64\nLS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\n</code></pre> <pre><code>$ cat ssl-dh-param.yaml\napiVersion: v1\ndata:\n  dhparam.pem: \"LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\"\nkind: Secret\nmetadata:\n  name: lb-dhparam\n  namespace: ingress-nginx\n  labels:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\n</code></pre> <pre><code>$ kubectl create -f ssl-dh-param.yaml\n</code></pre>"},{"location":"examples/customization/ssl-dh-param/#test","title":"Test","text":"<p>Check the contents of the configmap is present in the nginx.conf file using: <pre><code>$ kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf\n</code></pre></p>"},{"location":"examples/customization/sysctl/","title":"Sysctl tuning","text":"<p>This example aims to demonstrate the use of an Init Container to adjust sysctl default values using <code>kubectl patch</code>.</p> <pre><code>kubectl patch deployment -n ingress-nginx ingress-nginx-controller \\\n    --patch=\"$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)\"\n</code></pre> <p>Changes:</p> <ul> <li>Backlog Queue setting <code>net.core.somaxconn</code> from <code>128</code> to <code>32768</code></li> <li>Ephemeral Ports setting <code>net.ipv4.ip_local_port_range</code> from <code>32768 60999</code> to <code>1024 65000</code></li> </ul> <p>In a post from the NGINX blog, it is possible to see an explanation for the changes.</p>"},{"location":"examples/docker-registry/","title":"Docker registry","text":"<p>This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet.</p>"},{"location":"examples/docker-registry/#deployment","title":"Deployment","text":"<p>First we deploy the docker registry in the cluster:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml\n</code></pre> <p>Important</p> <p>DO NOT RUN THIS IN PRODUCTION</p> <p>This deployment uses <code>emptyDir</code> in the <code>volumeMount</code> which means the contents of the registry will be deleted when the pod dies.</p> <p>The next required step is creation of the ingress rules. To do this we have two options: with and without TLS</p>"},{"location":"examples/docker-registry/#without-tls","title":"Without TLS","text":"<p>Download and edit the yaml deployment replacing <code>registry.&lt;your domain&gt;</code> with a valid DNS name pointing to the ingress controller:</p> <pre><code>wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/ingress-without-tls.yaml\n</code></pre> <p>Important</p> <p>Running a docker registry without TLS requires we configure our local docker daemon with the insecure registry flag.</p> <p>Please check deploy a plain http registry</p>"},{"location":"examples/docker-registry/#with-tls","title":"With TLS","text":"<p>Download and edit the yaml deployment replacing <code>registry.&lt;your domain&gt;</code> with a valid DNS name pointing to the ingress controller:</p> <pre><code>wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/ingress-with-tls.yaml\n</code></pre> <p>Deploy kube lego use Let's Encrypt certificates or edit the ingress rule to use a secret with an existing SSL certificate.</p>"},{"location":"examples/docker-registry/#testing","title":"Testing","text":"<p>To test the registry is working correctly we download a known image from docker hub, create a tag pointing to the new registry and upload the image:</p> <pre><code>docker pull ubuntu:16.04\ndocker tag ubuntu:16.04 `registry.&lt;your domain&gt;/ubuntu:16.04`\ndocker push `registry.&lt;your domain&gt;/ubuntu:16.04`\n</code></pre> <p>Please replace <code>registry.&lt;your domain&gt;</code> with your domain.</p>"},{"location":"examples/grpc/","title":"gRPC","text":"<p>This example demonstrates how to route traffic to a gRPC service through the Ingress-NGINX controller.</p>"},{"location":"examples/grpc/#prerequisites","title":"Prerequisites","text":"<ol> <li>You have a kubernetes cluster running.</li> <li>You have a domain name such as <code>example.com</code> that is configured to route traffic to the Ingress-NGINX controller.</li> <li>You have the ingress-nginx-controller installed as per docs.</li> <li>You have a backend application running a gRPC server listening for TCP traffic.  If you want, you can use https://github.com/grpc/grpc-go/blob/91e0aeb192456225adf27966d04ada4cf8599915/examples/features/reflection/server/main.go as an example.</li> <li>You're also responsible for provisioning an SSL certificate for the ingress. So you need to have a valid SSL certificate, deployed as a Kubernetes secret of type <code>tls</code>, in the same namespace as the gRPC application.</li> </ol>"},{"location":"examples/grpc/#step-1-create-a-kubernetes-deployment-for-grpc-app","title":"Step 1: Create a Kubernetes <code>Deployment</code> for gRPC app","text":"<ul> <li>Make sure your gRPC application pod is running and listening for connections. For example you can try a kubectl command like this below:   <pre><code>$ kubectl get po -A -o wide | grep go-grpc-greeter-server\n</code></pre></li> <li> <p>If you have a gRPC app deployed in your cluster, then skip further notes in this Step 1, and continue from Step 2 below.</p> </li> <li> <p>As an example gRPC application, we can use this app https://github.com/grpc/grpc-go/blob/91e0aeb192456225adf27966d04ada4cf8599915/examples/features/reflection/server/main.go.</p> </li> <li> <p>To create a container image for this app, you can use this Dockerfile. </p> </li> <li> <p>If you use the Dockerfile mentioned above, to create a image, then you can use the following example Kubernetes manifest to create a deployment resource that uses that image. If necessary edit this manifest to suit your needs.</p> </li> </ul> <pre><code>cat &lt;&lt;EOF | kubectl apply -f -\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  labels:\n    app: go-grpc-greeter-server\n  name: go-grpc-greeter-server\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: go-grpc-greeter-server\n  template:\n    metadata:\n      labels:\n        app: go-grpc-greeter-server\n    spec:\n      containers:\n      - image: &lt;reponame&gt;/go-grpc-greeter-server   # Edit this for your reponame\n        resources:\n          limits:\n            cpu: 100m\n            memory: 100Mi\n          requests:\n            cpu: 50m\n            memory: 50Mi\n        name: go-grpc-greeter-server\n        ports:\n        - containerPort: 50051\nEOF\n</code></pre>"},{"location":"examples/grpc/#step-2-create-the-kubernetes-service-for-the-grpc-app","title":"Step 2: Create the Kubernetes <code>Service</code> for the gRPC app","text":"<ul> <li>You can use the following example manifest to create a service of type ClusterIP. Edit the name/namespace/label/port to match your deployment/pod.   <pre><code>cat &lt;&lt;EOF | kubectl apply -f -\napiVersion: v1\nkind: Service\nmetadata:\n  labels:\n    app: go-grpc-greeter-server\n  name: go-grpc-greeter-server\nspec:\n  ports:\n  - port: 80\n    protocol: TCP\n    targetPort: 50051\n  selector:\n    app: go-grpc-greeter-server\n  type: ClusterIP\nEOF\n</code></pre></li> <li>You can save the above example manifest to a file with name <code>service.go-grpc-greeter-server.yaml</code> and edit it to match your deployment/pod, if required. You can create the service resource with a kubectl command like this:</li> </ul> <pre><code>$ kubectl create -f service.go-grpc-greeter-server.yaml\n</code></pre>"},{"location":"examples/grpc/#step-3-create-the-kubernetes-ingress-resource-for-the-grpc-app","title":"Step 3: Create the Kubernetes <code>Ingress</code> resource for the gRPC app","text":"<ul> <li>Use the following example manifest of a ingress resource to create a ingress for your grpc app. If required, edit it to match your app's details like name, namespace, service, secret etc. Make sure you have the required SSL-Certificate, existing in your Kubernetes cluster in the same namespace where the gRPC app is. The certificate must be available as a kubernetes secret resource, of type \"kubernetes.io/tls\" https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets. This is because we are terminating TLS on the ingress.</li> </ul> <pre><code>cat &lt;&lt;EOF | kubectl apply -f -\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/ssl-redirect: \"true\"\n    nginx.ingress.kubernetes.io/backend-protocol: \"GRPC\"\n  name: fortune-ingress\n  namespace: default\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: grpctest.dev.mydomain.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: go-grpc-greeter-server\n            port:\n              number: 80\n  tls:\n  # This secret must exist beforehand\n  # The cert must also contain the subj-name grpctest.dev.mydomain.com\n  # https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/PREREQUISITES.md#tls-certificates\n  - secretName: wildcard.dev.mydomain.com\n    hosts:\n      - grpctest.dev.mydomain.com\nEOF\n</code></pre> <ul> <li>If you save the above example manifest as a file named <code>ingress.go-grpc-greeter-server.yaml</code> and edit it to match your deployment and service, you can create the ingress like this:</li> </ul> <pre><code>$ kubectl create -f ingress.go-grpc-greeter-server.yaml\n</code></pre> <ul> <li> <p>The takeaway is that we are not doing any TLS configuration on the server (as we are terminating TLS at the ingress level, gRPC traffic will travel unencrypted inside the cluster and arrive \"insecure\").</p> </li> <li> <p>For your own application you may or may not want to do this.  If you prefer to forward encrypted traffic to your POD and terminate TLS at the gRPC server itself, add the ingress annotation <code>nginx.ingress.kubernetes.io/backend-protocol: \"GRPCS\"</code>.</p> </li> <li> <p>A few more things to note:</p> </li> <li> <p>We've tagged the ingress with the annotation <code>nginx.ingress.kubernetes.io/backend-protocol: \"GRPC\"</code>.  This is the magic ingredient that sets up the appropriate nginx configuration to route http/2 traffic to our service.</p> </li> <li> <p>We're terminating TLS at the ingress and have configured an SSL certificate <code>wildcard.dev.mydomain.com</code>.  The ingress matches traffic arriving as <code>https://grpctest.dev.mydomain.com:443</code> and routes unencrypted messages to the backend Kubernetes service.</p> </li> </ul>"},{"location":"examples/grpc/#step-4-test-the-connection","title":"Step 4: test the connection","text":"<ul> <li>Once we've applied our configuration to Kubernetes, it's time to test that we can actually talk to the backend.  To do this, we'll use the grpcurl utility:</li> </ul> <pre><code>$ grpcurl grpctest.dev.mydomain.com:443 helloworld.Greeter/SayHello\n{\n  \"message\": \"Hello \"\n}\n</code></pre>"},{"location":"examples/grpc/#debugging-hints","title":"Debugging Hints","text":"<ol> <li>Obviously, watch the logs on your app.</li> <li>Watch the logs for the ingress-nginx-controller (increasing verbosity as    needed).</li> <li>Double-check your address and ports.</li> <li>Set the <code>GODEBUG=http2debug=2</code> environment variable to get detailed http/2    logging on the client and/or server.</li> <li>Study RFC 7540 (http/2) https://tools.ietf.org/html/rfc7540.</li> </ol> <p>If you are developing public gRPC endpoints, check out https://proto.stack.build, a protocol buffer / gRPC build service that can use to help make it easier for your users to consume your API.</p> <p>See also the specific gRPC settings of NGINX: https://nginx.org/en/docs/http/ngx_http_grpc_module.html</p>"},{"location":"examples/grpc/#notes-on-using-responserequest-streams","title":"Notes on using response/request streams","text":"<ol> <li>If your server only does response streaming and you expect a stream to be open longer than 60 seconds, you will have to change the <code>grpc_read_timeout</code> to accommodate this.</li> <li>If your service only does request streaming and you expect a stream to be open longer than 60 seconds, you have to change the <code>grpc_send_timeout</code> and the <code>client_body_timeout</code>.</li> <li>If you do both response and request streaming with an open stream longer than 60 seconds, you have to change all three timeouts: <code>grpc_read_timeout</code>, <code>grpc_send_timeout</code> and <code>client_body_timeout</code>.</li> </ol> <p>Values for the timeouts must be specified as e.g. <code>\"1200s\"</code>.</p> <p>On the most recent versions of ingress-nginx, changing these timeouts requires using the <code>nginx.ingress.kubernetes.io/server-snippet</code> annotation. There are plans for future releases to allow using the Kubernetes annotations to define each timeout separately.</p>"},{"location":"examples/multi-tls/","title":"Multi TLS certificate termination","text":"<p>This example uses 2 different certificates to terminate SSL for 2 hostnames.</p> <ol> <li>Create tls secrets for foo.bar.com and bar.baz.com as indicated in the yaml</li> <li>Create multi-tls.yaml</li> </ol> <p>This should generate a segment like: <pre><code>$ kubectl exec -it ingress-nginx-controller-6vwd1 -- cat /etc/nginx/nginx.conf | grep \"foo.bar.com\" -B 7 -A 35\n    server {\n        listen 80;\n        listen 443 ssl http2;\n        ssl_certificate /etc/nginx-ssl/default-foobar.pem;\n        ssl_certificate_key /etc/nginx-ssl/default-foobar.pem;\n\n\n        server_name foo.bar.com;\n\n\n        if ($scheme = http) {\n            return 301 https://$host$request_uri;\n        }\n\n\n\n        location / {\n            proxy_set_header Host                   $host;\n\n            # Pass Real IP\n            proxy_set_header X-Real-IP              $remote_addr;\n\n            # Allow websocket connections\n            proxy_set_header                        Upgrade           $http_upgrade;\n            proxy_set_header                        Connection        $connection_upgrade;\n\n            proxy_set_header X-Forwarded-For        $proxy_add_x_forwarded_for;\n            proxy_set_header X-Forwarded-Host       $host;\n            proxy_set_header X-Forwarded-Proto      $pass_access_scheme;\n\n            proxy_connect_timeout                   5s;\n            proxy_send_timeout                      60s;\n            proxy_read_timeout                      60s;\n\n            proxy_redirect                          off;\n            proxy_buffering                         off;\n\n            proxy_http_version                      1.1;\n\n            proxy_pass http://default-http-svc-80;\n        }\n</code></pre></p> <p>And you should be able to reach your nginx service or http-svc service using a hostname switch: <pre><code>$  kubectl get ing\nNAME      RULE          BACKEND   ADDRESS                         AGE\nfoo-tls   -                       104.154.30.67                   13m\n          foo.bar.com\n          /             http-svc:80\n          bar.baz.com\n          /             nginx:80\n\n$ curl https://104.154.30.67 -H 'Host:foo.bar.com' -k\nCLIENT VALUES:\nclient_address=10.245.0.6\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://foo.bar.com:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nconnection=close\nhost=foo.bar.com\nuser-agent=curl/7.35.0\nx-forwarded-for=10.245.0.1\nx-forwarded-host=foo.bar.com\nx-forwarded-proto=https\n\n$ curl https://104.154.30.67 -H 'Host:bar.baz.com' -k\n&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n&lt;head&gt;\n&lt;title&gt;Welcome to nginx on Debian!&lt;/title&gt;\n\n$ curl 104.154.30.67\ndefault backend - 404\n</code></pre></p>"},{"location":"examples/openpolicyagent/","title":"OpenPolicyAgent and pathType enforcing","text":"<p>Ingress API allows users to specify different pathType  on Ingress object. </p> <p>While pathType <code>Exact</code> and <code>Prefix</code> should allow only a small set of characters, pathType <code>ImplementationSpecific</code> allows any characters, as it may contain regexes, variables and other features that may be specific of the Ingress  Controller being used.</p> <p>This means that the Ingress Admins (the persona who deployed the Ingress Controller) should trust the users  allowed to use <code>pathType: ImplementationSpecific</code>, as this may allow arbitrary configuration, and this  configuration may end on the proxy (aka Nginx) configuration.</p>"},{"location":"examples/openpolicyagent/#example","title":"Example","text":"<p>The example in this repo uses Gatekeeper to block the usage of <code>pathType: ImplementationSpecific</code>,  allowing just a specific list of namespaces to use it.</p> <p>It is recommended that the admin modifies this rules to enforce a specific set of characters when the usage of ImplementationSpecific is allowed, or in ways that best suits their needs.</p> <p>First, the <code>ConstraintTemplate</code> from template.yaml will define a rule that validates if the Ingress object  is being created on an excempted namespace, and case not, will validate its pathType.</p> <p>Then, the rule <code>K8sBlockIngressPathType</code> contained in rule.yaml will define the parameters: what kind of  object should be verified (Ingress), what are the excempted namespaces, and what kinds of pathType are blocked.</p>"},{"location":"examples/psp/","title":"Pod Security Policy (PSP)","text":"<p>In most clusters today, by default, all resources (e.g. <code>Deployments</code> and <code>ReplicatSets</code>) have permissions to create pods. Kubernetes however provides a more fine-grained authorization policy called Pod Security Policy (PSP).</p> <p>PSP allows the cluster owner to define the permission of each object, for example creating a pod. If you have PSP enabled on the cluster, and you deploy ingress-nginx, you will need to provide the <code>Deployment</code> with the permissions to create pods.</p> <p>Before applying any objects, first apply the PSP permissions by running: <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/psp/psp.yaml\n</code></pre></p> <p>Note: PSP permissions must be granted before the creation of the <code>Deployment</code> and the <code>ReplicaSet</code>.</p>"},{"location":"examples/rewrite/","title":"Rewrite","text":"<p>This example demonstrates how to use <code>Rewrite</code> annotations.</p>"},{"location":"examples/rewrite/#prerequisites","title":"Prerequisites","text":"<p>You will need to make sure your Ingress targets exactly one Ingress controller by specifying the ingress.class annotation, and that you have an ingress controller running in your cluster.</p>"},{"location":"examples/rewrite/#deployment","title":"Deployment","text":"<p>Rewriting can be controlled using the following annotations:</p> Name Description Values nginx.ingress.kubernetes.io/rewrite-target Target URI where the traffic must be redirected string nginx.ingress.kubernetes.io/ssl-redirect Indicates if the location section is only accessible via SSL (defaults to True when Ingress contains a Certificate) bool nginx.ingress.kubernetes.io/force-ssl-redirect Forces the redirection to HTTPS even if the Ingress is not TLS Enabled bool nginx.ingress.kubernetes.io/app-root Defines the Application Root that the Controller must redirect if it's in <code>/</code> context string nginx.ingress.kubernetes.io/use-regex Indicates if the paths defined on an Ingress use regular expressions bool"},{"location":"examples/rewrite/#examples","title":"Examples","text":""},{"location":"examples/rewrite/#rewrite-target","title":"Rewrite Target","text":"<p>Attention</p> <p>Starting in Version 0.22.0, ingress definitions using the annotation <code>nginx.ingress.kubernetes.io/rewrite-target</code> are not backwards compatible with previous versions. In Version 0.22.0 and beyond, any substrings within the request URI that need to be passed to the rewritten path must explicitly be defined in a capture group.</p> <p>Note</p> <p>Captured groups are saved in numbered placeholders, chronologically, in the form <code>$1</code>, <code>$2</code> ... <code>$n</code>. These placeholders can be used as parameters in the <code>rewrite-target</code> annotation.</p> <p>Note</p> <p>Please see the FAQ for Validation Of <code>path</code></p> <p>Create an Ingress rule with a rewrite annotation:</p> <pre><code>$ echo '\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/use-regex: \"true\"\n    nginx.ingress.kubernetes.io/rewrite-target: /$2\n  name: rewrite\n  namespace: default\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: rewrite.bar.com\n    http:\n      paths:\n      - path: /something(/|$)(.*)\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: http-svc\n            port: \n              number: 80\n' | kubectl create -f -\n</code></pre> <p>In this ingress definition, any characters captured by <code>(.*)</code> will be assigned to the placeholder <code>$2</code>, which is then used as a parameter in the <code>rewrite-target</code> annotation.</p> <p>For example, the ingress definition above will result in the following rewrites:</p> <ul> <li><code>rewrite.bar.com/something</code> rewrites to <code>rewrite.bar.com/</code></li> <li><code>rewrite.bar.com/something/</code> rewrites to <code>rewrite.bar.com/</code></li> <li><code>rewrite.bar.com/something/new</code> rewrites to <code>rewrite.bar.com/new</code></li> </ul>"},{"location":"examples/rewrite/#app-root","title":"App Root","text":"<p>Create an Ingress rule with an app-root annotation: <pre><code>$ echo \"\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/app-root: /app1\n  name: approot\n  namespace: default\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: approot.bar.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: http-svc\n            port: \n              number: 80\n\" | kubectl create -f -\n</code></pre></p> <p>Check the rewrite is working</p> <pre><code>$ curl -I -k http://approot.bar.com/\nHTTP/1.1 302 Moved Temporarily\nServer: nginx/1.11.10\nDate: Mon, 13 Mar 2017 14:57:15 GMT\nContent-Type: text/html\nContent-Length: 162\nLocation: http://approot.bar.com/app1\nConnection: keep-alive\n</code></pre>"},{"location":"examples/static-ip/","title":"Static IPs","text":"<p>This example demonstrates how to assign a static-ip to an Ingress on through the Ingress-NGINX controller.</p>"},{"location":"examples/static-ip/#prerequisites","title":"Prerequisites","text":"<p>You need a TLS cert and a test HTTP service for this example. You will also need to make sure your Ingress targets exactly one Ingress controller by specifying the ingress.class annotation, and that you have an ingress controller running in your cluster.</p>"},{"location":"examples/static-ip/#acquiring-an-ip","title":"Acquiring an IP","text":"<p>Since instances of the ingress nginx controller actually run on nodes in your cluster, by default nginx Ingresses will only get static IPs if your cloudprovider supports static IP assignments to nodes. On GKE/GCE for example, even though nodes get static IPs, the IPs are not retained across upgrades.</p> <p>To acquire a static IP for the ingress-nginx-controller, simply put it behind a Service of <code>Type=LoadBalancer</code>.</p> <p>First, create a loadbalancer Service and wait for it to acquire an IP:</p> <pre><code>$ kubectl create -f static-ip-svc.yaml\nservice \"ingress-nginx-lb\" created\n\n$ kubectl get svc ingress-nginx-lb\nNAME               CLUSTER-IP     EXTERNAL-IP       PORT(S)                      AGE\ningress-nginx-lb   10.0.138.113   104.154.109.191   80:31457/TCP,443:32240/TCP   15m\n</code></pre> <p>Then, update the ingress controller so it adopts the static IP of the Service by passing the <code>--publish-service</code> flag (the example yaml used in the next step already has it set to \"ingress-nginx-lb\").</p> <pre><code>$ kubectl create -f ingress-nginx-controller.yaml\ndeployment \"ingress-nginx-controller\" created\n</code></pre>"},{"location":"examples/static-ip/#assigning-the-ip-to-an-ingress","title":"Assigning the IP to an Ingress","text":"<p>From here on every Ingress created with the <code>ingress.class</code> annotation set to <code>nginx</code> will get the IP allocated in the previous step.</p> <pre><code>$ kubectl create -f ingress-nginx.yaml\ningress \"ingress-nginx\" created\n\n$ kubectl get ing ingress-nginx\nNAME            HOSTS     ADDRESS           PORTS     AGE\ningress-nginx   *         104.154.109.191   80, 443   13m\n\n$ curl 104.154.109.191 -kL\nCLIENT VALUES:\nclient_address=10.180.1.25\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://104.154.109.191:8080/\n...\n</code></pre>"},{"location":"examples/static-ip/#retaining-the-ip","title":"Retaining the IP","text":"<p>You can test retention by deleting the Ingress:</p> <pre><code>$ kubectl delete ing ingress-nginx\ningress \"ingress-nginx\" deleted\n\n$ kubectl create -f ingress-nginx.yaml\ningress \"ingress-nginx\" created\n\n$ kubectl get ing ingress-nginx\nNAME            HOSTS     ADDRESS           PORTS     AGE\ningress-nginx   *         104.154.109.191   80, 443   13m\n</code></pre> <p>Note that unlike the GCE Ingress, the same loadbalancer IP is shared amongst all Ingresses, because all requests are proxied through the same set of nginx controllers.</p>"},{"location":"examples/static-ip/#promote-ephemeral-to-static-ip","title":"Promote ephemeral to static IP","text":"<p>To promote the allocated IP to static, you can update the Service manifest:</p> <pre><code>$ kubectl patch svc ingress-nginx-lb -p '{\"spec\": {\"loadBalancerIP\": \"104.154.109.191\"}}'\n\"ingress-nginx-lb\" patched\n</code></pre> <p>... and promote the IP to static (promotion works differently for cloudproviders, provided example is for GKE/GCE):</p> <pre><code>$ gcloud compute addresses create ingress-nginx-lb --addresses 104.154.109.191 --region us-central1\nCreated [https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/ingress-nginx-lb].\n---\naddress: 104.154.109.191\ncreationTimestamp: '2017-01-31T16:34:50.089-08:00'\ndescription: ''\nid: '5208037144487826373'\nkind: compute#address\nname: ingress-nginx-lb\nregion: us-central1\nselfLink: https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/ingress-nginx-lb\nstatus: IN_USE\nusers:\n- us-central1/forwardingRules/a09f6913ae80e11e6a8c542010af0000\n</code></pre> <p>Now even if the Service is deleted, the IP will persist, so you can recreate the Service with <code>spec.loadBalancerIP</code> set to <code>104.154.109.191</code>.</p>"},{"location":"examples/tls-termination/","title":"TLS termination","text":"<p>This example demonstrates how to terminate TLS through the Ingress-Nginx Controller.</p>"},{"location":"examples/tls-termination/#prerequisites","title":"Prerequisites","text":"<p>You need a TLS cert and a test HTTP service for this example.</p>"},{"location":"examples/tls-termination/#deployment","title":"Deployment","text":"<p>Create a <code>ingress.yaml</code> file.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: nginx-test\nspec:\n  tls:\n    - hosts:\n      - foo.bar.com\n      # This assumes tls-secret exists and the SSL\n      # certificate contains a CN for foo.bar.com\n      secretName: tls-secret\n  ingressClassName: nginx\n  rules:\n    - host: foo.bar.com\n      http:\n        paths:\n        - path: /\n          pathType: Prefix\n          backend:\n            # This assumes http-svc exists and routes to healthy endpoints\n            service:\n              name: http-svc\n              port:\n                number: 80\n</code></pre> <p>The following command instructs the controller to terminate traffic using the provided TLS cert, and forward un-encrypted HTTP traffic to the test HTTP service.</p> <pre><code>kubectl apply -f ingress.yaml\n</code></pre>"},{"location":"examples/tls-termination/#validation","title":"Validation","text":"<p>You can confirm that the Ingress works.</p> <pre><code>$ kubectl describe ing nginx-test\nName:           nginx-test\nNamespace:      default\nAddress:        104.198.183.6\nDefault backend:    default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)\nTLS:\n  tls-secret terminates\nRules:\n  Host  Path    Backends\n  ----  ----    --------\n  *\n            http-svc:80 (&lt;none&gt;)\nAnnotations:\nEvents:\n  FirstSeen LastSeen    Count   From                SubObjectPath   Type        Reason  Message\n  --------- --------    -----   ----                -------------   --------    ------  -------\n  7s        7s      1   {ingress-nginx-controller }         Normal      CREATE  default/nginx-test\n  7s        7s      1   {ingress-nginx-controller }         Normal      UPDATE  default/nginx-test\n  7s        7s      1   {ingress-nginx-controller }         Normal      CREATE  ip: 104.198.183.6\n  7s        7s      1   {ingress-nginx-controller }         Warning     MAPPING Ingress rule 'default/nginx-test' contains no path definition. Assuming /\n\n$ curl 104.198.183.6 -L\ncurl: (60) SSL certificate problem: self signed certificate\nMore details here: http://curl.haxx.se/docs/sslcerts.html\n\n$ curl 104.198.183.6 -Lk\nCLIENT VALUES:\nclient_address=10.240.0.4\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://35.186.221.137:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nconnection=Keep-Alive\nhost=35.186.221.137\nuser-agent=curl/7.46.0\nvia=1.1 google\nx-cloud-trace-context=f708ea7e369d4514fc90d51d7e27e91d/13322322294276298106\nx-forwarded-for=104.132.0.80, 35.186.221.137\nx-forwarded-proto=https\nBODY:\n</code></pre>"},{"location":"user-guide/basic-usage/","title":"Basic usage - host based routing","text":"<p>ingress-nginx can be used for many use cases, inside various cloud providers and supports a lot of configurations. In this section you can find a common usage scenario where a single load balancer powered by ingress-nginx will route traffic to 2 different HTTP backend services based on the host name.</p> <p>First of all follow the instructions to install ingress-nginx. Then imagine that you need to expose 2 HTTP services already installed, <code>myServiceA</code>, <code>myServiceB</code>, and configured as <code>type: ClusterIP</code>. </p> <p>Let's say that you want to expose the first at <code>myServiceA.foo.org</code> and the second at <code>myServiceB.foo.org</code>.</p> <p>If the cluster version is &lt; 1.19, you can create two ingress resources like this:</p> <pre><code>apiVersion: networking.k8s.io/v1beta1\nkind: Ingress\nmetadata:\n  name: ingress-myservicea\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: myservicea.foo.org\n    http:\n      paths:\n      - path: /\n        backend:\n          serviceName: myservicea\n          servicePort: 80\n---\napiVersion: networking.k8s.io/v1beta1\nkind: Ingress\nmetadata:\n  name: ingress-myserviceb\n  annotations:\n    # use the shared ingress-nginx\n    kubernetes.io/ingress.class: \"nginx\"\nspec:\n  rules:\n  - host: myserviceb.foo.org\n    http:\n      paths:\n      - path: /\n        backend:\n          serviceName: myserviceb\n          servicePort: 80\n</code></pre> <p>If the cluster uses Kubernetes version &gt;= 1.19.x, then its suggested to create 2 ingress resources, using yaml examples shown below. These examples are in conformity with the <code>networking.kubernetes.io/v1</code> api.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-myservicea\nspec:\n  rules:\n  - host: myservicea.foo.org\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: myservicea\n            port:\n              number: 80\n  ingressClassName: nginx\n---\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-myserviceb\nspec:\n  rules:\n  - host: myserviceb.foo.org\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: myserviceb\n            port:\n              number: 80\n  ingressClassName: nginx\n</code></pre> <p>When you apply this yaml, 2 ingress resources will be created managed by the ingress-nginx instance. Nginx is configured to automatically discover all ingress with the <code>kubernetes.io/ingress.class: \"nginx\"</code> annotation or where <code>ingressClassName: nginx</code> is present. Please note that the ingress resource should be placed inside the same namespace of the backend resource.</p> <p>On many cloud providers ingress-nginx will also create the corresponding Load Balancer resource. All you have to do is get the external IP and add a DNS <code>A record</code> inside your DNS provider that point myservicea.foo.org and myserviceb.foo.org to the nginx external IP. Get the external IP by running:</p> <pre><code>kubectl get services -n ingress-nginx\n</code></pre> <p>To test inside minikube refer to this documentation: Set up Ingress on Minikube with the NGINX Ingress Controller</p>"},{"location":"user-guide/cli-arguments/","title":"Command line arguments","text":"<p>The following command line arguments are accepted by the Ingress controller executable.</p> <p>They are set in the container spec of the <code>ingress-nginx-controller</code> Deployment manifest</p> Argument Description <code>--annotations-prefix</code> Prefix of the Ingress annotations specific to the NGINX controller. (default \"nginx.ingress.kubernetes.io\") <code>--apiserver-host</code> Address of the Kubernetes API server. Takes the form \"protocol://address:port\". If not specified, it is assumed the program runs inside a Kubernetes cluster and local discovery is attempted. <code>--certificate-authority</code> Path to a cert file for the certificate authority. This certificate is used only when the flag --apiserver-host is specified. <code>--configmap</code> Name of the ConfigMap containing custom global configurations for the controller. <code>--controller-class</code> Ingress Class Controller value this Ingress satisfies. The class of an Ingress object is set using the field IngressClassName in Kubernetes clusters version v1.19.0 or higher. The .spec.controller value of the IngressClass referenced in an Ingress Object should be the same value specified here to make this object be watched. <code>--deep-inspect</code> Enables ingress object security deep inspector. (default true) <code>--default-backend-service</code> Service used to serve HTTP requests not matching any known server name (catch-all). Takes the form \"namespace/name\". The controller configures NGINX to forward requests to the first port of this Service. <code>--default-server-port</code> Port to use for exposing the default server (catch-all). (default 8181) <code>--default-ssl-certificate</code> Secret containing a SSL certificate to be used by the default HTTPS server (catch-all). Takes the form \"namespace/name\". <code>--enable-annotation-validation</code> If true, will enable the annotation validation feature. This value will be defaulted to true on a future release. <code>--disable-catch-all</code> Disable support for catch-all Ingresses. (default false) <code>--disable-full-test</code> Disable full test of all merged ingresses at the admission stage and tests the template of the ingress being created or updated  (full test of all ingresses is enabled by default). <code>--disable-svc-external-name</code> Disable support for Services of type ExternalName. (default false) <code>--disable-sync-events</code> Disables the creation of 'Sync' Event resources, but still logs them <code>--dynamic-configuration-retries</code> Number of times to retry failed dynamic configuration before failing to sync an ingress. (default 15) <code>--election-id</code> Election id to use for Ingress status updates. (default \"ingress-controller-leader\") <code>--election-ttl</code> Duration a leader election is valid before it's getting re-elected, e.g. <code>15s</code>, <code>10m</code> or <code>1h</code>. (Default: 30s) <code>--enable-metrics</code> Enables the collection of NGINX metrics. (default true) <code>--enable-ssl-chain-completion</code> Autocomplete SSL certificate chains with missing intermediate CA certificates. Certificates uploaded to Kubernetes must have the \"Authority Information Access\" X.509 v3 extension for this to succeed. (default false) <code>--enable-ssl-passthrough</code> Enable SSL Passthrough. (default false) <code>--disable-leader-election</code> Disable Leader Election on Nginx Controller. (default false) <code>--enable-topology-aware-routing</code> Enable topology aware routing feature, needs service object annotation service.kubernetes.io/topology-mode sets to auto. (default false) <code>--exclude-socket-metrics</code> Set of socket request metrics to exclude which won't be exported nor being calculated. The possible socket request metrics to exclude are documented in the monitoring guide e.g. 'nginx_ingress_controller_request_duration_seconds,nginx_ingress_controller_response_size' <code>--health-check-path</code> URL path of the health check endpoint. Configured inside the NGINX status server. All requests received on the port defined by the healthz-port parameter are forwarded internally to this path. (default \"/healthz\") <code>--health-check-timeout</code> Time limit, in seconds, for a probe to health-check-path to succeed. (default 10) <code>--healthz-port</code> Port to use for the healthz endpoint. (default 10254) <code>--healthz-host</code> Address to bind the healthz endpoint. <code>--http-port</code> Port to use for servicing HTTP traffic. (default 80) <code>--https-port</code> Port to use for servicing HTTPS traffic. (default 443) <code>--ingress-class</code> Name of the ingress class this controller satisfies. The class of an Ingress object is set using the field IngressClassName in Kubernetes clusters version v1.18.0 or higher or the annotation \"kubernetes.io/ingress.class\" (deprecated). If this parameter is not set, or set to the default value of \"nginx\", it will handle ingresses with either an empty or \"nginx\" class name. <code>--ingress-class-by-name</code> Define if Ingress Controller should watch for Ingress Class by Name together with Controller Class. (default false). <code>--internal-logger-address</code> Address to be used when binding internal syslogger. (default 127.0.0.1:11514) <code>--kubeconfig</code> Path to a kubeconfig file containing authorization and API server information. <code>--length-buckets</code> Set of buckets which will be used for prometheus histogram metrics such as RequestLength, ResponseLength. (default <code>[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]</code>) <code>--maxmind-edition-ids</code> Maxmind edition ids to download GeoLite2 Databases. (default \"GeoLite2-City,GeoLite2-ASN\") <code>--maxmind-retries-timeout</code> Maxmind downloading delay between 1<sup>st</sup> and 2<sup>nd</sup> attempt, 0s - do not retry to download if something went wrong. (default 0s) <code>--maxmind-retries-count</code> Number of attempts to download the GeoIP DB. (default 1) <code>--maxmind-license-key</code> Maxmind license key to download GeoLite2 Databases. https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases . <code>--maxmind-mirror</code> Maxmind mirror url (example: http://geoip.local/databases. <code>--metrics-per-host</code> Export metrics per-host. (default true) <code>--monitor-max-batch-size</code> Max batch size of NGINX metrics. (default 10000) <code>--post-shutdown-grace-period</code> Additional delay in seconds before controller container exits. (default 10) <code>--profiler-port</code> Port to use for expose the ingress controller Go profiler when it is enabled. (default 10245) <code>--profiling</code> Enable profiling via web interface host:port/debug/pprof/ . (default true) <code>--publish-service</code> Service fronting the Ingress controller. Takes the form \"namespace/name\". When used together with update-status, the controller mirrors the address of this service's endpoints to the load-balancer status of all Ingress objects it satisfies. <code>--publish-status-address</code> Customized address (or addresses, separated by comma) to set as the load-balancer status of Ingress objects this controller satisfies. Requires the update-status parameter. <code>--report-node-internal-ip-address</code> Set the load-balancer status of Ingress objects to internal Node addresses instead of external. Requires the update-status parameter. (default false) <code>--report-status-classes</code> If true, report status classes in metrics (2xx, 3xx, 4xx and 5xx) instead of full status codes. (default false) <code>--ssl-passthrough-proxy-port</code> Port to use internally for SSL Passthrough. (default 442) <code>--status-port</code> Port to use for the lua HTTP endpoint configuration. (default 10246) <code>--status-update-interval</code> Time interval in seconds in which the status should check if an update is required. Default is 60 seconds. (default 60) <code>--stream-port</code> Port to use for the lua TCP/UDP endpoint configuration. (default 10247) <code>--sync-period</code> Period at which the controller forces the repopulation of its local object stores. Disabled by default. <code>--sync-rate-limit</code> Define the sync frequency upper limit. (default 0.3) <code>--tcp-services-configmap</code> Name of the ConfigMap containing the definition of the TCP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form \"namespace/name:port\", where \"port\" can either be a port number or name. TCP ports 80 and 443 are reserved by the controller for servicing HTTP traffic. <code>--time-buckets</code> Set of buckets which will be used for prometheus histogram metrics such as RequestTime, ResponseTime. (default <code>[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]</code>) <code>--udp-services-configmap</code> Name of the ConfigMap containing the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form \"namespace/name:port\", where \"port\" can either be a port name or number. <code>--update-status</code> Update the load-balancer status of Ingress objects this controller satisfies. Requires setting the publish-service parameter to a valid Service reference. (default true) <code>--update-status-on-shutdown</code> Update the load-balancer status of Ingress objects when the controller shuts down. Requires the update-status parameter. (default true) <code>--shutdown-grace-period</code> Seconds to wait after receiving the shutdown signal, before stopping the nginx process. (default 0) <code>--size-buckets</code> Set of buckets which will be used for prometheus histogram metrics such as BytesSent. (default <code>[10, 100, 1000, 10000, 100000, 1e+06, 1e+07]</code>) <code>-v, --v Level</code> number for the log level verbosity <code>--validating-webhook</code> The address to start an admission controller on to validate incoming ingresses. Takes the form \":port\". If not provided, no admission controller is started. <code>--validating-webhook-certificate</code> The path of the validating webhook certificate PEM. <code>--validating-webhook-key</code> The path of the validating webhook key PEM. <code>--version</code> Show release information about the Ingress-Nginx Controller and exit. <code>--watch-ingress-without-class</code> Define if Ingress Controller should also watch for Ingresses without an IngressClass or the annotation specified. (default false) <code>--watch-namespace</code> Namespace the controller watches for updates to Kubernetes objects. This includes Ingresses, Services and all configuration resources. All namespaces are watched if this parameter is left empty. <code>--watch-namespace-selector</code> The controller will watch namespaces whose labels match the given selector. This flag only takes effective when <code>--watch-namespace</code> is empty."},{"location":"user-guide/custom-errors/","title":"Custom errors","text":"<p>When the <code>custom-http-errors</code> option is enabled, the Ingress controller configures NGINX so that it passes several HTTP headers down to its <code>default-backend</code> in case of error:</p> Header Value <code>X-Code</code> HTTP status code returned by the request <code>X-Format</code> Value of the <code>Accept</code> header sent by the client <code>X-Original-URI</code> URI that caused the error <code>X-Namespace</code> Namespace where the backend Service is located <code>X-Ingress-Name</code> Name of the Ingress where the backend is defined <code>X-Service-Name</code> Name of the Service backing the backend <code>X-Service-Port</code> Port number of the Service backing the backend <code>X-Request-ID</code> Unique ID that identifies the request - same as for backend service <p>A custom error backend can use this information to return the best possible representation of an error page. For example, if the value of the <code>Accept</code> header send by the client was <code>application/json</code>, a carefully crafted backend could decide to return the error payload as a JSON document instead of HTML.</p> <p>Important</p> <p>The custom backend is expected to return the correct HTTP status code instead of <code>200</code>. NGINX does not change the response from the custom default backend.</p> <p>An example of such custom backend is available inside the source repository at images/custom-error-pages.</p> <p>See also the Custom errors example.</p>"},{"location":"user-guide/default-backend/","title":"Default backend","text":"<p>The default backend is a service which handles all URL paths and hosts the Ingress-NGINX controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).</p> <p>Basically a default backend exposes two URLs:</p> <ul> <li><code>/healthz</code> that returns 200</li> <li><code>/</code> that returns 404</li> </ul> <p>Example</p> <p>The sub-directory <code>/images/custom-error-pages</code> provides an additional service for the purpose of customizing the error pages served via the default backend.</p>"},{"location":"user-guide/exposing-tcp-udp-services/","title":"Exposing TCP and UDP services","text":"<p>While the Kubernetes Ingress resource only officially supports routing external HTTP(s) traffic to services, ingress-nginx can be configured to receive external TCP/UDP traffic from non-HTTP protocols and route them to internal services using TCP/UDP port mappings that are specified within a ConfigMap.</p> <p>To support this, the <code>--tcp-services-configmap</code> and <code>--udp-services-configmap</code> flags can be used to point to an existing config map where the key is the external port to use and the value indicates the service to expose using the format: <code>&lt;service port&gt;:&lt;namespace/service name&gt;:[PROXY]:[PROXY]</code></p> <p>It is also possible to use a number or the name of the port. The two last fields are optional. Adding <code>PROXY</code> in either or both of the two last fields we can use Proxy Protocol decoding (listen) and/or encoding (proxy_pass) in a TCP service.  The first <code>PROXY</code> controls the decode of the proxy protocol and the second <code>PROXY</code> controls the encoding using proxy protocol.  This allows an incoming connection to be decoded or an outgoing connection to be encoded. It is also possible to arbitrate between two different proxies by turning on the decode and encode on a TCP service. </p> <p>The next example shows how to expose the service <code>example-go</code> running in the namespace <code>default</code> in the port <code>8080</code> using the port <code>9000</code></p> <pre><code>apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: tcp-services\n  namespace: ingress-nginx\ndata:\n  9000: \"default/example-go:8080\"\n</code></pre> <p>Since 1.9.13 NGINX provides UDP Load Balancing. The next example shows how to expose the service <code>kube-dns</code> running in the namespace <code>kube-system</code> in the port <code>53</code> using the port <code>53</code></p> <pre><code>apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: udp-services\n  namespace: ingress-nginx\ndata:\n  53: \"kube-system/kube-dns:53\"\n</code></pre> <p>If TCP/UDP proxy support is used, then those ports need to be exposed in the Service defined for the Ingress.</p> <p><pre><code>apiVersion: v1\nkind: Service\nmetadata:\n  name: ingress-nginx\n  namespace: ingress-nginx\n  labels:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\nspec:\n  type: LoadBalancer\n  ports:\n    - name: http\n      port: 80\n      targetPort: 80\n      protocol: TCP\n    - name: https\n      port: 443\n      targetPort: 443\n      protocol: TCP\n    - name: proxied-tcp-9000\n      port: 9000\n      targetPort: 9000\n      protocol: TCP\n  selector:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\n</code></pre> Then, the configmap should be added into ingress controller's deployment args. <pre><code> args:\n    - /nginx-ingress-controller\n    - --tcp-services-configmap=ingress-nginx/tcp-services\n</code></pre></p>"},{"location":"user-guide/external-articles/","title":"External Articles","text":"<ul> <li>Pain(less) NGINX Ingress</li> <li>Accessing Kubernetes Pods from Outside of the Cluster</li> <li>Kubernetes - Redirect HTTP to HTTPS with ELB and the Ingress-Nginx Controller</li> <li>Configure Nginx Ingress Controller for TLS termination on Kubernetes on Azure</li> <li>Secure your Nginx Ingress controller behind Google Cloud Armor or Identity-Aware Proxy (IAP)</li> </ul>"},{"location":"user-guide/fcgi-services/","title":"Exposing FastCGI Servers","text":"<p>FastCGI is a binary protocol for interfacing interactive programs with a web server. [...] (It's) aim is to reduce the overhead related to interfacing between web server and CGI programs, allowing a server to handle more web page requests per unit of time.</p> <p>\u2014 Wikipedia</p> <p>The ingress-nginx ingress controller can be used to directly expose FastCGI servers.  Enabling FastCGI in your Ingress only requires setting the backend-protocol annotation to <code>FCGI</code>, and with a couple more annotations you can customize the way ingress-nginx handles the communication with your FastCGI server.</p>"},{"location":"user-guide/fcgi-services/#example-objects-to-expose-a-fastcgi-pod","title":"Example Objects to Expose a FastCGI Pod","text":"<p>The Pod example object below exposes port <code>9000</code>, which is the conventional FastCGI port.</p> <pre><code>apiVersion: v1\nkind: Pod\nmetadata:\n  name: example-app\nlabels:\n  app: example-app\nspec:\n  containers:\n  - name: example-app\n    image: example-app:1.0\n    ports:\n    - containerPort: 9000\n      name: fastcgi\n</code></pre> <p>The Service object example below matches port <code>9000</code> from the Pod object above.</p> <pre><code>apiVersion: v1\nkind: Service\nmetadata:\n  name: example-service\nspec:\n  selector:\n    app: example-app\n  ports:\n  - port: 9000\n    targetPort: 9000\n    name: fastcgi\n</code></pre> <p>And the Ingress and ConfigMap objects below demonstrates the supported FastCGI specific annotations (NGINX actually has 50 FastCGI directives, all of which have not been exposed in the ingress yet), and matches the service <code>example-service</code>, and the port named <code>fastcgi</code> from above. The ConfigMap must be created first for the Ingress Controller to be able to find it when the Ingress object is created, otherwise you will need to restart the Ingress Controller pods.</p> <pre><code># The ConfigMap MUST be created first for the ingress controller to be able to\n# find it when the Ingress object is created.\n\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: example-cm\ndata:\n  SCRIPT_FILENAME: \"/example/index.php\"\n\n---\n\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/backend-protocol: \"FCGI\"\n    nginx.ingress.kubernetes.io/fastcgi-index: \"index.php\"\n    nginx.ingress.kubernetes.io/fastcgi-params-configmap: \"example-cm\"\n  name: example-app\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: app.example.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: example-service\n            port:\n              name: fastcgi\n</code></pre>"},{"location":"user-guide/fcgi-services/#fastcgi-ingress-annotations","title":"FastCGI Ingress Annotations","text":"<p>To enable FastCGI, the <code>nginx.ingress.kubernetes.io/backend-protocol</code> annotation needs to be set to <code>FCGI</code>, which overrides the default <code>HTTP</code> value.</p> <p><code>nginx.ingress.kubernetes.io/backend-protocol: \"FCGI\"</code></p> <p>This enables the FastCGI mode for all paths defined in the Ingress object</p>"},{"location":"user-guide/fcgi-services/#the-nginxingresskubernetesiofastcgi-index-annotation","title":"The <code>nginx.ingress.kubernetes.io/fastcgi-index</code> Annotation","text":"<p>To specify an index file, the <code>fastcgi-index</code> annotation value can optionally be set.  In the example below, the value is set to <code>index.php</code>.  This annotation corresponds to the NGINX <code>fastcgi_index</code> directive.</p> <p><code>nginx.ingress.kubernetes.io/fastcgi-index: \"index.php\"</code></p>"},{"location":"user-guide/fcgi-services/#the-nginxingresskubernetesiofastcgi-params-configmap-annotation","title":"The <code>nginx.ingress.kubernetes.io/fastcgi-params-configmap</code> Annotation","text":"<p>To specify NGINX <code>fastcgi_param</code> directives, the <code>fastcgi-params-configmap</code> annotation is used, which in turn must lead to a ConfigMap object containing the NGINX <code>fastcgi_param</code> directives as key/values.</p> <p><code>nginx.ingress.kubernetes.io/fastcgi-params-configmap: \"example-configmap\"</code></p> <p>And the ConfigMap object to specify the <code>SCRIPT_FILENAME</code> and <code>HTTP_PROXY</code> NGINX's <code>fastcgi_param</code> directives will look like the following:</p> <p><pre><code>apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: example-configmap\ndata:\n  SCRIPT_FILENAME: \"/example/index.php\"\n  HTTP_PROXY: \"\"\n</code></pre> Using the namespace/ prefix is also supported, for example:</p> <p><code>nginx.ingress.kubernetes.io/fastcgi-params-configmap: \"example-namespace/example-configmap\"</code></p>"},{"location":"user-guide/ingress-path-matching/","title":"Ingress Path Matching","text":""},{"location":"user-guide/ingress-path-matching/#regular-expression-support","title":"Regular Expression Support","text":"<p>Important</p> <p>Regular expressions is not supported in the <code>spec.rules.host</code> field. The wildcard character '*' must appear by itself as the first DNS label and matches only a single label. You cannot have a wildcard label by itself (e.g. Host == \"*\").</p> <p>Note</p> <p>Please see the FAQ for Validation Of <code>path</code></p> <p>The ingress controller supports case insensitive regular expressions in the <code>spec.rules.http.paths.path</code> field. This can be enabled by setting the <code>nginx.ingress.kubernetes.io/use-regex</code> annotation to <code>true</code> (the default is false).</p> <p>Hint</p> <p>Kubernetes only accept expressions that comply with the RE2 engine syntax. It is possible that valid expressions accepted by NGINX cannot be used with ingress-nginx, because the PCRE library (used in NGINX) supports a wider syntax than RE2. See the RE2 Syntax documentation for differences.</p> <p>See the description of the <code>use-regex</code> annotation for more details.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress\n  annotations:\n    nginx.ingress.kubernetes.io/use-regex: \"true\"\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/.*\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: test\n            port:\n              number: 80\n</code></pre> <p>The preceding ingress definition would translate to the following location block within the NGINX configuration for the <code>test.com</code> server:</p> <pre><code>location ~* \"^/foo/.*\" {\n  ...\n}\n</code></pre>"},{"location":"user-guide/ingress-path-matching/#path-priority","title":"Path Priority","text":"<p>In NGINX, regular expressions follow a first match policy. In order to enable more accurate path matching, ingress-nginx first orders the paths by descending length before writing them to the NGINX template as location blocks.</p> <p>Please read the warning before using regular expressions in your ingress definitions.</p>"},{"location":"user-guide/ingress-path-matching/#example","title":"Example","text":"<p>Let the following two ingress definitions be created:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress-1\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/bar\n        pathType: Prefix\n        backend:\n          service:\n            name: service1\n            port:\n              number: 80\n      - path: /foo/bar/\n        pathType: Prefix\n        backend:\n          service:\n            name: service2\n            port:\n              number: 80\n</code></pre> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress-2\n  annotations:\n    nginx.ingress.kubernetes.io/rewrite-target: /$1\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/bar/(.+)\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: service3\n            port: \n              number: 80\n</code></pre> <p>The ingress controller would define the following location blocks, in order of descending length, within the NGINX template for the <code>test.com</code> server:</p> <pre><code>location ~* ^/foo/bar/.+ {\n  ...\n}\n\nlocation ~* \"^/foo/bar/\" {\n  ...\n}\n\nlocation ~* \"^/foo/bar\" {\n  ...\n}\n</code></pre> <p>The following request URI's would match the corresponding location blocks:</p> <ul> <li><code>test.com/foo/bar/1</code> matches <code>~* ^/foo/bar/.+</code> and will go to service 3.</li> <li><code>test.com/foo/bar/</code> matches <code>~* ^/foo/bar/</code> and will go to service 2.</li> <li><code>test.com/foo/bar</code> matches <code>~* ^/foo/bar</code> and will go to service 1.</li> </ul> <p>IMPORTANT NOTES:</p> <ul> <li>If the <code>use-regex</code> OR <code>rewrite-target</code> annotation is used on any Ingress for a given host, then the case insensitive regular expression location modifier will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</li> </ul>"},{"location":"user-guide/ingress-path-matching/#warning","title":"Warning","text":"<p>The following example describes a case that may inflict unwanted path matching behavior.</p> <p>This case is expected and a result of NGINX's a first match policy for paths that use the regular expression location modifier. For more information about how a path is chosen, please read the following article: \"Understanding Nginx Server and Location Block Selection Algorithms\".</p>"},{"location":"user-guide/ingress-path-matching/#example_1","title":"Example","text":"<p>Let the following ingress be defined:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress-3\n  annotations:\n    nginx.ingress.kubernetes.io/use-regex: \"true\"\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/bar/bar\n        pathType: Prefix\n        backend:\n          service:\n            name: test\n            port: \n              number: 80\n      - path: /foo/bar/[A-Z0-9]{3}\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: test\n            port: \n              number: 80\n</code></pre> <p>The ingress controller would define the following location blocks (in this order) within the NGINX template for the <code>test.com</code> server:</p> <pre><code>location ~* \"^/foo/bar/[A-Z0-9]{3}\" {\n  ...\n}\n\nlocation ~* \"^/foo/bar/bar\" {\n  ...\n}\n</code></pre> <p>A request to <code>test.com/foo/bar/bar</code> would match the <code>^/foo/bar/[A-Z0-9]{3}</code> location block instead of the longest EXACT matching path.</p>"},{"location":"user-guide/k8s-122-migration/","title":"FAQ - Migration to Kubernetes 1.22 and apiVersion <code>networking.k8s.io/v1</code>","text":"<p>If you are using Ingress objects in your cluster (running Kubernetes older than v1.22), and you plan to upgrade to Kubernetes v1.22, this page is relevant to you.</p> <ul> <li>Please read this official blog on deprecated Ingress API versions</li> <li>Please read this official documentation on the IngressClass object</li> </ul>"},{"location":"user-guide/k8s-122-migration/#what-is-an-ingressclass-and-why-is-it-important-for-users-of-ingress-nginx-controller-now","title":"What is an IngressClass and why is it important for users of ingress-nginx controller now?","text":"<p>IngressClass is a Kubernetes resource. See the description below. It's important because until now, a default install of the ingress-nginx controller did not require a IngressClass object. From version 1.0.0 of the ingress-nginx controller, an IngressClass object is required.</p> <p>On clusters with more than one instance of the ingress-nginx controller, all instances of the controllers must be aware of which Ingress objects they serve. The <code>ingressClassName</code> field of an Ingress is the way to let the controller know about that.</p> <pre><code>kubectl explain ingressclass\n</code></pre> <pre><code>KIND:     IngressClass\nVERSION:  networking.k8s.io/v1\nDESCRIPTION:\n     IngressClass represents the class of the Ingress, referenced by the Ingress\n     Spec. The `ingressclass.kubernetes.io/is-default-class` annotation can be\n     used to indicate that an IngressClass should be considered default. When a\n     single IngressClass resource has this annotation set to true, new Ingress\n     resources without a class specified will be assigned this default class.\nFIELDS:\n   apiVersion   &lt;string&gt;\n     APIVersion defines the versioned schema of this representation of an\n     object. Servers should convert recognized schemas to the latest internal\n     value, and may reject unrecognized values. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources\n   kind &lt;string&gt;\n     Kind is a string value representing the REST resource this object\n     represents. Servers may infer this from the endpoint the client submits\n     requests to. Cannot be updated. In CamelCase. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds\n   metadata     &lt;Object&gt;\n     Standard object's metadata. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata\n   spec &lt;Object&gt;\n     Spec is the desired state of the IngressClass. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status`\n</code></pre>"},{"location":"user-guide/k8s-122-migration/#what-has-caused-this-change-in-behavior","title":"What has caused this change in behavior?","text":"<p>There are 2 primary reasons.</p>"},{"location":"user-guide/k8s-122-migration/#reason-1","title":"Reason 1","text":"<p>Until K8s version 1.21, it was possible to create an Ingress resource using deprecated versions of the Ingress API, such as:</p> <ul> <li><code>extensions/v1beta1</code></li> <li><code>networking.k8s.io/v1beta1</code>   You would get a message about deprecation, but the Ingress resource would get created.</li> </ul> <p>From K8s version 1.22 onwards, you can only access the Ingress API via the stable, <code>networking.k8s.io/v1</code> API. The reason is explained in the official blog on deprecated ingress API versions.</p>"},{"location":"user-guide/k8s-122-migration/#reason-2","title":"Reason #2","text":"<p>If you are already using the ingress-nginx controller and then upgrade to Kubernetes 1.22, there are several scenarios where your existing Ingress objects will not work how you expect.</p> <p>Read this FAQ to check which scenario matches your use case.</p>"},{"location":"user-guide/k8s-122-migration/#what-is-the-ingressclassname-field","title":"What is the <code>ingressClassName</code> field?","text":"<p><code>ingressClassName</code> is a field in the spec of an Ingress object.</p> <pre><code>kubectl explain ingress.spec.ingressClassName\n</code></pre> <pre><code>KIND:     Ingress\nVERSION:  networking.k8s.io/v1\nFIELD:    ingressClassName &lt;string&gt;\nDESCRIPTION:\n     IngressClassName is the name of the IngressClass cluster resource. The\n     associated IngressClass defines which controller will implement the\n     resource. This replaces the deprecated `kubernetes.io/ingress.class`\n     annotation. For backwards compatibility, when that annotation is set, it\n     must be given precedence over this field. The controller may emit a warning\n     if the field and annotation have different values. Implementations of this\n     API should ignore Ingresses without a class specified. An IngressClass\n     resource may be marked as default, which can be used to set a default value\n     for this field. For more information, refer to the IngressClass\n     documentation.\n</code></pre> <p>The <code>.spec.ingressClassName</code> behavior has precedence over the deprecated <code>kubernetes.io/ingress.class</code> annotation.</p>"},{"location":"user-guide/k8s-122-migration/#i-have-only-one-ingress-controller-in-my-cluster-what-should-i-do","title":"I have only one ingress controller in my cluster. What should I do?","text":"<p>If a single instance of the ingress-nginx controller is the sole Ingress controller running in your cluster, you should add the annotation \"ingressclass.kubernetes.io/is-default-class\" in your IngressClass, so any new Ingress objects will have this one as default IngressClass.</p> <p>When using Helm, you can enable this annotation by setting <code>.controller.ingressClassResource.default: true</code> in your Helm chart installation's values file.</p> <p>If you have any old Ingress objects remaining without an IngressClass set, you can do one or more of the following to make the ingress-nginx controller aware of the old objects:</p> <ul> <li>You can manually set the <code>.spec.ingressClassName</code> field in the manifest of your own Ingress resources.</li> <li>You can re-create them after setting the <code>ingressclass.kubernetes.io/is-default-class</code> annotation to <code>true</code> on the IngressClass</li> <li>Alternatively you can make the ingress-nginx controller watch Ingress objects without the ingressClassName field set by starting your ingress-nginx with the flag --watch-ingress-without-class=true.   When using Helm, you can configure your Helm chart installation's values file with <code>.controller.watchIngressWithoutClass: true</code>.</li> </ul> <p>We recommend that you create the IngressClass as shown below:</p> <pre><code>---\napiVersion: networking.k8s.io/v1\nkind: IngressClass\nmetadata:\n  labels:\n    app.kubernetes.io/component: controller\n  name: nginx\n  annotations:\n    ingressclass.kubernetes.io/is-default-class: \"true\"\nspec:\n  controller: k8s.io/ingress-nginx\n</code></pre> <p>and add the value <code>spec.ingressClassName=nginx</code> in your Ingress objects.</p>"},{"location":"user-guide/k8s-122-migration/#i-have-many-ingress-objects-in-my-cluster-what-should-i-do","title":"I have many ingress objects in my cluster. What should I do?","text":"<p>If you have a lot of ingress objects without ingressClass configuration, you can run the ingress controller with the flag <code>--watch-ingress-without-class=true</code>.</p>"},{"location":"user-guide/k8s-122-migration/#what-is-the-flag-watch-ingress-without-class","title":"What is the flag <code>--watch-ingress-without-class</code>?","text":"<p>It's a flag that is passed, as an argument, to the <code>nginx-ingress-controller</code> executable. In the configuration, it looks like this:</p> <pre><code># ...\nargs:\n  - /nginx-ingress-controller\n  - --watch-ingress-without-class=true\n  - --controller-class=k8s.io/ingress-nginx\n  # ...\n# ...\n</code></pre>"},{"location":"user-guide/k8s-122-migration/#i-have-more-than-one-controller-in-my-cluster-and-im-already-using-the-annotation","title":"I have more than one controller in my cluster, and I'm already using the annotation","text":"<p>No problem. This should still keep working, but we highly recommend you to test! Even though <code>kubernetes.io/ingress.class</code> is deprecated, the ingress-nginx controller still understands that annotation. If you want to follow good practice, you should consider migrating to use IngressClass and <code>.spec.ingressClassName</code>.</p>"},{"location":"user-guide/k8s-122-migration/#i-have-more-than-one-controller-running-in-my-cluster-and-i-want-to-use-the-new-api","title":"I have more than one controller running in my cluster, and I want to use the new API","text":"<p>In this scenario, you need to create multiple IngressClasses (see the example above).</p> <p>Be aware that IngressClass works in a very specific way: you will need to change the <code>.spec.controller</code> value in your IngressClass and configure the controller to expect the exact same value.</p> <p>Let's see an example, supposing that you have three IngressClasses:</p> <ul> <li>IngressClass <code>ingress-nginx-one</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx1</code></li> <li>IngressClass <code>ingress-nginx-two</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx2</code></li> <li>IngressClass <code>ingress-nginx-three</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx1</code></li> </ul> <p>For private use, you can also use a controller name that doesn't contain a <code>/</code>, e.g. <code>ingress-nginx1</code>.</p> <p>When deploying your ingress controllers, you will have to change the <code>--controller-class</code> field as follows:</p> <ul> <li>Ingress-Nginx A, configured to use controller class name <code>example.com/ingress-nginx1</code></li> <li>Ingress-Nginx B, configured to use controller class name <code>example.com/ingress-nginx2</code></li> </ul> <p>When you create an Ingress object with its <code>ingressClassName</code> set to <code>ingress-nginx-two</code>, only controllers looking for the <code>example.com/ingress-nginx2</code> controller class pay attention to the new object.</p> <p>Given that Ingress-Nginx B is set up that way, it will serve that object, whereas Ingress-Nginx A ignores the new Ingress.</p> <p>Bear in mind that if you start Ingress-Nginx B with the command line argument <code>--watch-ingress-without-class=true</code>, it will serve:</p> <ol> <li>Ingresses without any <code>ingressClassName</code> set</li> <li>Ingresses where the deprecated annotation (<code>kubernetes.io/ingress.class</code>) matches the value set in the command line argument <code>--ingress-class</code></li> <li>Ingresses that refer to any IngressClass that has the same <code>spec.controller</code> as configured in <code>--controller-class</code></li> <li>If you start Ingress-Nginx B with the command line argument <code>--watch-ingress-without-class=true</code> and you run Ingress-Nginx A with the command line argument <code>--watch-ingress-without-class=false</code> then this is a supported configuration.    If you have two ingress-nginx controllers for the same cluster, both running with <code>--watch-ingress-without-class=true</code> then there is likely to be a conflict.</li> </ol>"},{"location":"user-guide/k8s-122-migration/#why-am-i-seeing-ingress-class-annotation-is-not-equal-to-the-expected-by-ingress-controller-in-my-controller-logs","title":"Why am I seeing \"ingress class annotation is not equal to the expected by Ingress Controller\" in my controller logs?","text":"<p>It is highly likely that you will also see the name of the ingress resource in the same error message. This error message has been observed on use the deprecated annotation (<code>kubernetes.io/ingress.class</code>) in an Ingress resource manifest. It is recommended to use the <code>.spec.ingressClassName</code> field of the Ingress resource, to specify the name of the IngressClass of the Ingress you are defining.</p>"},{"location":"user-guide/k8s-122-migration/#how-can-i-easily-install-multiple-instances-of-the-ingress-nginx-controller-in-the-same-cluster","title":"How can I easily install multiple instances of the ingress-nginx controller in the same cluster?","text":"<p>You can install them in different namespaces.</p> <ul> <li>Create a new namespace   <pre><code>kubectl create namespace ingress-nginx-2\n</code></pre></li> <li>Use Helm to install the additional instance of the ingress controller</li> <li>Ensure you have Helm working (refer to the Helm documentation)</li> <li>We have to assume that you have the helm repo for the ingress-nginx controller already added to your Helm config.   But, if you have not added the helm repo then you can do this to add the repo to your helm config;   <pre><code>helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx\n</code></pre></li> <li>Make sure you have updated the helm repo data;   <pre><code>helm repo update\n</code></pre></li> <li>Now, install an additional instance of the ingress-nginx controller like this:   <pre><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx  \\\n--namespace ingress-nginx-2 \\\n--set controller.ingressClassResource.name=nginx-two \\\n--set controller.ingressClass=nginx-two \\\n--set controller.ingressClassResource.controllerValue=\"example.com/ingress-nginx-2\" \\\n--set controller.ingressClassResource.enabled=true \\\n--set controller.ingressClassByName=true\n</code></pre></li> </ul> <p>If you need to install yet another instance, then repeat the procedure to create a new namespace, change the values such as names &amp; namespaces (for example from \"-2\" to \"-3\"), or anything else that meets your needs.</p> <p>Note that <code>controller.ingressClassResource.name</code> and <code>controller.ingressClass</code> have to be set correctly. The first is to create the IngressClass object and the other is to modify the deployment of the actual ingress controller pod.</p>"},{"location":"user-guide/k8s-122-migration/#i-cant-use-multiple-namespaces-what-should-i-do","title":"I can't use multiple namespaces, what should I do?","text":"<p>If you need to install all instances in the same namespace, then you need to specify a different election id, like this:</p> <pre><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx  \\\n--namespace kube-system \\\n--set controller.electionID=nginx-two-leader \\\n--set controller.ingressClassResource.name=nginx-two \\\n--set controller.ingressClass=nginx-two \\\n--set controller.ingressClassResource.controllerValue=\"example.com/ingress-nginx-2\" \\\n--set controller.ingressClassResource.enabled=true \\\n--set controller.ingressClassByName=true\n</code></pre>"},{"location":"user-guide/miscellaneous/","title":"Miscellaneous","text":""},{"location":"user-guide/miscellaneous/#source-ip-address","title":"Source IP address","text":"<p>By default NGINX uses the content of the header <code>X-Forwarded-For</code> as the source of truth to get information about the client IP address. This works without issues in L7 if we configure the setting <code>proxy-real-ip-cidr</code> with the correct information of the IP/network address of trusted external load balancer.</p> <p>If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR.</p> <p>Another option is to enable proxy protocol using <code>use-proxy-protocol: \"true\"</code>.</p> <p>In this mode NGINX does not use the content of the header to get the source IP address of the connection.</p>"},{"location":"user-guide/miscellaneous/#path-types","title":"Path types","text":"<p>Each path in an Ingress is required to have a corresponding path type. Paths that do not include an explicit pathType will fail validation. By default NGINX path type is Prefix to not break existing definitions</p>"},{"location":"user-guide/miscellaneous/#proxy-protocol","title":"Proxy Protocol","text":"<p>If you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the Proxy Protocol for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself.</p> <p>Amongst others ELBs in AWS and HAProxy support Proxy Protocol.</p>"},{"location":"user-guide/miscellaneous/#websockets","title":"Websockets","text":"<p>Support for websockets is provided by NGINX out of the box. No special configuration required.</p> <p>The only requirement to avoid the close of connections is the increase of the values of <code>proxy-read-timeout</code> and <code>proxy-send-timeout</code>.</p> <p>The default value of these settings is <code>60 seconds</code>.</p> <p>A more adequate value to support websockets is a value higher than one hour (<code>3600</code>).</p> <p>Important</p> <p>If the Ingress-Nginx Controller is exposed with a service <code>type=LoadBalancer</code> make sure the protocol between the loadbalancer and NGINX is TCP.</p>"},{"location":"user-guide/miscellaneous/#optimizing-tls-time-to-first-byte-tttfb","title":"Optimizing TLS Time To First Byte (TTTFB)","text":"<p>NGINX provides the configuration option ssl_buffer_size to allow the optimization of the TLS record size.</p> <p>This improves the TLS Time To First Byte (TTTFB). The default value in the Ingress controller is <code>4k</code> (NGINX default is <code>16k</code>).</p>"},{"location":"user-guide/miscellaneous/#retries-in-non-idempotent-methods","title":"Retries in non-idempotent methods","text":"<p>Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error. The previous behavior can be restored using <code>retry-non-idempotent=true</code> in the configuration ConfigMap.</p>"},{"location":"user-guide/miscellaneous/#limitations","title":"Limitations","text":"<ul> <li>Ingress rules for TLS require the definition of the field <code>host</code></li> </ul>"},{"location":"user-guide/miscellaneous/#why-endpoints-and-not-services","title":"Why endpoints and not services","text":"<p>The Ingress-Nginx Controller does not use Services to route traffic to the pods. Instead it uses the Endpoints API in order to bypass kube-proxy to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT.</p>"},{"location":"user-guide/monitoring/","title":"Monitoring","text":"<p>Two different methods to install and configure Prometheus and Grafana are described in this doc. * Prometheus and Grafana installation using Pod Annotations. This installs Prometheus and Grafana in the same namespace as NGINX Ingress * Prometheus and Grafana installation using Service Monitors. This installs Prometheus and Grafana in two different namespaces. This is the preferred method, and helm charts supports this by default.</p>"},{"location":"user-guide/monitoring/#prometheus-and-grafana-installation-using-pod-annotations","title":"Prometheus and Grafana installation using Pod Annotations","text":"<p>This tutorial will show you how to install Prometheus and Grafana for scraping the metrics of the Ingress-Nginx Controller.</p> <p>Important</p> <p>This example uses <code>emptyDir</code> volumes for Prometheus and Grafana. This means once the pod gets terminated you will lose all the data.</p>"},{"location":"user-guide/monitoring/#before-you-begin","title":"Before You Begin","text":"<ul> <li> <p>The Ingress-Nginx Controller should already be deployed according to the deployment instructions here.</p> </li> <li> <p>The controller should be configured for exporting metrics. This requires 3 configurations to the controller. These configurations are :</p> </li> <li>controller.metrics.enabled=true</li> <li>controller.podAnnotations.\"prometheus.io/scrape\"=\"true\"</li> <li> <p>controller.podAnnotations.\"prometheus.io/port\"=\"10254\"</p> </li> <li> <p>The easiest way to configure the controller for metrics is via helm upgrade. Assuming you have installed the ingress-nginx controller as a helm release named ingress-nginx, then you can simply type the command shown below :   <pre><code>helm upgrade ingress-nginx ingress-nginx \\\n--repo https://kubernetes.github.io/ingress-nginx \\\n--namespace ingress-nginx \\\n--set controller.metrics.enabled=true \\\n--set-string controller.podAnnotations.\"prometheus\\.io/scrape\"=\"true\" \\\n--set-string controller.podAnnotations.\"prometheus\\.io/port\"=\"10254\"\n</code></pre></p> </li> <li>You can validate that the controller is configured for metrics by looking at the values of the installed release, like this:   <pre><code>helm get values ingress-nginx --namespace ingress-nginx\n</code></pre></li> <li>You should be able to see the values shown below:   <pre><code>..\ncontroller:\n  metrics:\n    enabled: true\n  podAnnotations:\n    prometheus.io/port: \"10254\"\n    prometheus.io/scrape: \"true\"\n..\n</code></pre></li> <li>If you are not using helm, you will have to edit your manifests like this:<ul> <li>Service manifest:    <pre><code>apiVersion: v1\nkind: Service\n..\nspec:\n  ports:\n    - name: prometheus\n      port: 10254\n      targetPort: prometheus\n      ..\n</code></pre></li> <li>Deployment manifest:      <pre><code>apiVersion: v1\nkind: Deployment\n..\nspec:\n  template:\n    metadata:\n      annotations:\n        prometheus.io/scrape: \"true\"\n        prometheus.io/port: \"10254\"\n    spec:\n      containers:\n        - name: controller\n          ports:\n            - name: prometheus\n              containerPort: 10254\n            ..\n</code></pre></li> </ul> </li> </ul>"},{"location":"user-guide/monitoring/#deploy-and-configure-prometheus-server","title":"Deploy and configure Prometheus Server","text":"<p>Note that the kustomize bases used in this tutorial are stored in the deploy folder of the GitHub repository kubernetes/ingress-nginx.</p> <ul> <li> <p>The Prometheus server must be configured so that it can discover endpoints of services. If a Prometheus server is already running in the cluster and if it is configured in a way that it can find the ingress controller pods, no extra configuration is needed.</p> </li> <li> <p>If there is no existing Prometheus server running, the rest of this tutorial will guide you through the steps needed to deploy a properly configured Prometheus server.</p> </li> <li> <p>Running the following command deploys prometheus in Kubernetes:</p> </li> </ul> <pre><code>kubectl apply --kustomize github.com/kubernetes/ingress-nginx/deploy/prometheus/\n</code></pre>"},{"location":"user-guide/monitoring/#prometheus-dashboard","title":"Prometheus Dashboard","text":"<ul> <li>Open Prometheus dashboard in a web browser:</li> </ul> <pre><code>kubectl get svc -n ingress-nginx\nNAME                   TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                      AGE\ndefault-http-backend   ClusterIP   10.103.59.201   &lt;none&gt;        80/TCP                                       3d\ningress-nginx          NodePort    10.97.44.72     &lt;none&gt;        80:30100/TCP,443:30154/TCP,10254:32049/TCP   5h\nprometheus-server      NodePort    10.98.233.86    &lt;none&gt;        9090:32630/TCP                               1m\n</code></pre> <ul> <li>Obtain the IP address of the nodes in the running cluster:</li> </ul> <pre><code>kubectl get nodes -o wide\n</code></pre> <ul> <li>In some cases where the node only have internal IP addresses we need to execute:</li> </ul> <pre><code>kubectl get nodes --selector=kubernetes.io/role!=master -o jsonpath={.items[*].status.addresses[?\\(@.type==\\\"InternalIP\\\"\\)].address}\n10.192.0.2 10.192.0.3 10.192.0.4\n</code></pre> <ul> <li> <p>Open your browser and visit the following URL: http://{node IP address}:{prometheus-svc-nodeport} to load the Prometheus Dashboard.</p> </li> <li> <p>According to the above example, this URL will be http://10.192.0.3:32630</p> </li> </ul> <p></p>"},{"location":"user-guide/monitoring/#grafana","title":"Grafana","text":"<ul> <li>Install grafana using the below command   <pre><code>kubectl apply --kustomize github.com/kubernetes/ingress-nginx/deploy/grafana/\n</code></pre></li> <li> <p>Look at the services   <pre><code>kubectl get svc -n ingress-nginx\nNAME                   TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                      AGE\ndefault-http-backend   ClusterIP   10.103.59.201   &lt;none&gt;        80/TCP                                       3d\ningress-nginx          NodePort    10.97.44.72     &lt;none&gt;        80:30100/TCP,443:30154/TCP,10254:32049/TCP   5h\nprometheus-server      NodePort    10.98.233.86    &lt;none&gt;        9090:32630/TCP                               10m\ngrafana                NodePort    10.98.233.87    &lt;none&gt;        3000:31086/TCP                               10m\n</code></pre></p> </li> <li> <p>Open your browser and visit the following URL: http://{node IP address}:{grafana-svc-nodeport} to load the Grafana Dashboard. According to the above example, this URL will be http://10.192.0.3:31086</p> </li> </ul> <p>The username and password is <code>admin</code></p> <ul> <li> <p>After the login you can import the Grafana dashboard from official dashboards, by following steps given below :</p> <ul> <li>Navigate to lefthand panel of grafana</li> <li>Hover on the gearwheel icon for Configuration and click \"Data Sources\"</li> <li>Click \"Add data source\"</li> <li>Select \"Prometheus\"</li> <li>Enter the details (note: I used http://CLUSTER_IP_PROMETHEUS_SVC:9090)</li> <li>Left menu (hover over +) -&gt; Dashboard</li> <li>Click \"Import\"</li> <li>Enter the copy pasted json from https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/grafana/dashboards/nginx.json</li> <li>Click Import JSON</li> <li>Select the Prometheus data source</li> <li>Click \"Import\"</li> </ul> </li> </ul> <p></p>"},{"location":"user-guide/monitoring/#caveats","title":"Caveats","text":""},{"location":"user-guide/monitoring/#wildcard-ingresses","title":"Wildcard ingresses","text":"<ul> <li>By default request metrics are labeled with the hostname. When you have a wildcard domain ingress, then there will be no metrics for that ingress (to prevent the metrics from exploding in cardinality). To get metrics in this case you need to run the ingress controller with <code>--metrics-per-host=false</code> (you will lose labeling by hostname, but still have labeling by ingress).</li> </ul>"},{"location":"user-guide/monitoring/#grafana-dashboard-using-ingress-resource","title":"Grafana dashboard using ingress resource","text":"<ul> <li>If you want to expose the dashboard for grafana using an ingress resource, then you can :<ul> <li>change the service type of the prometheus-server service and the grafana service to \"ClusterIP\" like this : <pre><code>kubectl -n ingress-nginx edit svc grafana\n</code></pre></li> <li>This will open the currently deployed service grafana in the default editor configured in your shell (vi/nvim/nano/other)</li> <li>scroll down to line 34 that looks like \"type: NodePort\"</li> <li>change it to look like \"type: ClusterIP\". Save and exit.</li> <li>create an ingress resource with backend as \"grafana\" and port as \"3000\"</li> </ul> </li> <li>Similarly, you can edit the service \"prometheus-server\" and add an ingress resource.</li> </ul>"},{"location":"user-guide/monitoring/#prometheus-and-grafana-installation-using-service-monitors","title":"Prometheus and Grafana installation using Service Monitors","text":"<p>This document assumes you're using helm and using the kube-prometheus-stack package to install Prometheus and Grafana.</p>"},{"location":"user-guide/monitoring/#verify-ingress-nginx-controller-is-installed","title":"Verify Ingress-Nginx Controller is installed","text":"<ul> <li> <p>The Ingress-Nginx Controller should already be deployed according to the deployment instructions here.</p> </li> <li> <p>To check if Ingress controller is deployed,   <pre><code>kubectl get pods -n ingress-nginx\n</code></pre></p> </li> <li>The result should look something like:   <code>NAME                                        READY   STATUS    RESTARTS   AGE   ingress-nginx-controller-7c489dc7b7-ccrf6   1/1     Running   0          19h</code></li> </ul>"},{"location":"user-guide/monitoring/#verify-prometheus-is-installed","title":"Verify Prometheus is installed","text":"<ul> <li>To check if Prometheus is already deployed, run the following command:</li> </ul> <p><pre><code>helm ls -A\n</code></pre> <pre><code>NAME          NAMESPACE       REVISION    UPDATED                                 STATUS      CHART                           APP VERSION\ningress-nginx ingress-nginx   10          2022-01-20 18:08:55.267373 -0800 PST    deployed    ingress-nginx-4.0.16            1.1.1\nprometheus    prometheus      1           2022-01-20 16:07:25.086828 -0800 PST    deployed    kube-prometheus-stack-30.1.0    0.53.1\n</code></pre> - Notice that prometheus is installed in a differenet namespace than ingress-nginx</p> <ul> <li>If prometheus is not installed, then you can install from here</li> </ul>"},{"location":"user-guide/monitoring/#re-configure-ingress-nginx-controller","title":"Re-configure Ingress-Nginx Controller","text":"<ul> <li>The Ingress NGINX controller needs to be reconfigured for exporting metrics. This requires 3 additional configurations to the controller. These configurations are :   <pre><code>controller.metrics.enabled=true\ncontroller.metrics.serviceMonitor.enabled=true\ncontroller.metrics.serviceMonitor.additionalLabels.release=\"prometheus\"\n</code></pre></li> <li>The easiest way of doing this is to helm upgrade   <pre><code>helm upgrade ingress-nginx ingress-nginx/ingress-nginx \\\n--namespace ingress-nginx \\\n--set controller.metrics.enabled=true \\\n--set controller.metrics.serviceMonitor.enabled=true \\\n--set controller.metrics.serviceMonitor.additionalLabels.release=\"prometheus\"\n</code></pre></li> <li> <p>Here <code>controller.metrics.serviceMonitor.additionalLabels.release=\"prometheus\"</code> should match the name of the helm release of the <code>kube-prometheus-stack</code></p> </li> <li> <p>You can validate that the controller has been successfully reconfigured to export metrics by looking at the values of the installed release, like this:   <pre><code>helm get values ingress-nginx --namespace ingress-nginx\n</code></pre> <pre><code>controller:\n  metrics:\n    enabled: true\n    serviceMonitor:\n      additionalLabels:\n        release: prometheus\n      enabled: true\n</code></pre></p> </li> </ul>"},{"location":"user-guide/monitoring/#configure-prometheus","title":"Configure Prometheus","text":"<ul> <li>Since Prometheus is running in a different namespace and not in the ingress-nginx namespace, it would not be able to discover ServiceMonitors in other namespaces when installed. Reconfigure your kube-prometheus-stack Helm installation to set <code>serviceMonitorSelectorNilUsesHelmValues</code> flag to false. By default, Prometheus only discovers PodMonitors within its own namespace. This should be disabled by setting <code>podMonitorSelectorNilUsesHelmValues</code> to false</li> <li>The configurations required are:   <pre><code>prometheus.prometheusSpec.podMonitorSelectorNilUsesHelmValues=false\nprometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues=false\n</code></pre></li> <li>The easiest way of doing this is to use <code>helm upgrade ...</code> <pre><code>helm upgrade prometheus prometheus-community/kube-prometheus-stack \\\n--namespace prometheus  \\\n--set prometheus.prometheusSpec.podMonitorSelectorNilUsesHelmValues=false \\\n--set prometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues=false\n</code></pre></li> <li>You can validate that Prometheus has been reconfigured by looking at the values of the installed release, like this:   <pre><code>helm get values prometheus --namespace prometheus\n</code></pre></li> <li>You should be able to see the values shown below:   <pre><code>prometheus:\n  prometheusSpec:\n    podMonitorSelectorNilUsesHelmValues: false\n    serviceMonitorSelectorNilUsesHelmValues: false\n</code></pre></li> </ul>"},{"location":"user-guide/monitoring/#connect-and-view-prometheus-dashboard","title":"Connect and view Prometheus dashboard","text":"<ul> <li>Port forward to Prometheus service. Find out the name of the prometheus service by using the following command:   <pre><code>kubectl get svc -n prometheus\n</code></pre></li> </ul> <p>The result of this command would look like:   <pre><code>NAME                                      TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE\nalertmanager-operated                     ClusterIP   None             &lt;none&gt;        9093/TCP,9094/TCP,9094/UDP   7h46m\nprometheus-grafana                        ClusterIP   10.106.28.162    &lt;none&gt;        80/TCP                       7h46m\nprometheus-kube-prometheus-alertmanager   ClusterIP   10.108.125.245   &lt;none&gt;        9093/TCP                     7h46m\nprometheus-kube-prometheus-operator       ClusterIP   10.110.220.1     &lt;none&gt;        443/TCP                      7h46m\nprometheus-kube-prometheus-prometheus     ClusterIP   10.102.72.134    &lt;none&gt;        9090/TCP                     7h46m\nprometheus-kube-state-metrics             ClusterIP   10.104.231.181   &lt;none&gt;        8080/TCP                     7h46m\nprometheus-operated                       ClusterIP   None             &lt;none&gt;        9090/TCP                     7h46m\nprometheus-prometheus-node-exporter       ClusterIP   10.96.247.128    &lt;none&gt;        9100/TCP                     7h46m\n</code></pre>   prometheus-kube-prometheus-prometheus is the service we want to port forward to. We can do so using the following command:   <pre><code>kubectl port-forward svc/prometheus-kube-prometheus-prometheus -n prometheus 9090:9090\n</code></pre>   When you run the above command, you should see something like:   <pre><code>Forwarding from 127.0.0.1:9090 -&gt; 9090\nForwarding from [::1]:9090 -&gt; 9090\n</code></pre> - Open your browser and visit the following URL http://localhost:{port-forwarded-port} according to the above example it would be, http://localhost:9090</p> <p></p>"},{"location":"user-guide/monitoring/#connect-and-view-grafana-dashboard","title":"Connect and view Grafana dashboard","text":"<ul> <li>Port forward to Grafana service. Find out the name of the Grafana service by using the following command:   <pre><code>kubectl get svc -n prometheus\n</code></pre></li> </ul> <p>The result of this command would look like:   <pre><code>NAME                                      TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE\nalertmanager-operated                     ClusterIP   None             &lt;none&gt;        9093/TCP,9094/TCP,9094/UDP   7h46m\nprometheus-grafana                        ClusterIP   10.106.28.162    &lt;none&gt;        80/TCP                       7h46m\nprometheus-kube-prometheus-alertmanager   ClusterIP   10.108.125.245   &lt;none&gt;        9093/TCP                     7h46m\nprometheus-kube-prometheus-operator       ClusterIP   10.110.220.1     &lt;none&gt;        443/TCP                      7h46m\nprometheus-kube-prometheus-prometheus     ClusterIP   10.102.72.134    &lt;none&gt;        9090/TCP                     7h46m\nprometheus-kube-state-metrics             ClusterIP   10.104.231.181   &lt;none&gt;        8080/TCP                     7h46m\nprometheus-operated                       ClusterIP   None             &lt;none&gt;        9090/TCP                     7h46m\nprometheus-prometheus-node-exporter       ClusterIP   10.96.247.128    &lt;none&gt;        9100/TCP                     7h46m\n</code></pre>   prometheus-grafana is the service we want to port forward to. We can do so using the following command:   <pre><code>kubectl port-forward svc/prometheus-grafana  3000:80 -n prometheus\n</code></pre>   When you run the above command, you should see something like:   <pre><code>Forwarding from 127.0.0.1:3000 -&gt; 3000\nForwarding from [::1]:3000 -&gt; 3000\n</code></pre> - Open your browser and visit the following URL http://localhost:{port-forwarded-port} according to the above example it would be, http://localhost:3000   The default username/ password is admin/prom-operator - After the login you can import the Grafana dashboard from official dashboards, by following steps given below :</p> <ul> <li>Navigate to lefthand panel of grafana</li> <li>Hover on the gearwheel icon for Configuration and click \"Data Sources\"</li> <li>Click \"Add data source\"</li> <li>Select \"Prometheus\"</li> <li>Enter the details (note: I used http://10.102.72.134:9090 which is the CLUSTER-IP for Prometheus service)</li> <li>Left menu (hover over +) -&gt; Dashboard</li> <li>Click \"Import\"</li> <li>Enter the copy pasted json from https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/grafana/dashboards/nginx.json</li> <li>Click Import JSON</li> <li>Select the Prometheus data source</li> <li>Click \"Import\"</li> </ul> <p></p>"},{"location":"user-guide/monitoring/#exposed-metrics","title":"Exposed metrics","text":"<p>Prometheus metrics are exposed on port 10254.</p>"},{"location":"user-guide/monitoring/#request-metrics","title":"Request metrics","text":"<ul> <li> <p><code>nginx_ingress_controller_request_duration_seconds</code> Histogram\\   The request processing (time elapsed between the first bytes were read from the client and the log write after the last bytes were sent to the client) time in seconds (affected by client speed).\\   nginx var: <code>request_time</code></p> </li> <li> <p><code>nginx_ingress_controller_response_duration_seconds</code> Histogram\\   The time spent on receiving the response from the upstream server in seconds (affected by client speed when the response is bigger than proxy buffers).\\   Note: can be up to several millis bigger than the <code>nginx_ingress_controller_request_duration_seconds</code> because of the different measuring method.   nginx var: <code>upstream_response_time</code></p> </li> <li> <p><code>nginx_ingress_controller_header_duration_seconds</code> Histogram\\   The time spent on receiving first header from the upstream server\\   nginx var: <code>upstream_header_time</code></p> </li> <li> <p><code>nginx_ingress_controller_connect_duration_seconds</code> Histogram\\   The time spent on establishing a connection with the upstream server\\   nginx var: <code>upstream_connect_time</code></p> </li> <li> <p><code>nginx_ingress_controller_response_size</code> Histogram\\   The response length (including request line, header, and request body)\\   nginx var: <code>bytes_sent</code></p> </li> <li> <p><code>nginx_ingress_controller_request_size</code> Histogram\\   The request length (including request line, header, and request body)\\   nginx var: <code>request_length</code></p> </li> <li> <p><code>nginx_ingress_controller_requests</code> Counter\\   The total number of client requests</p> </li> <li> <p><code>nginx_ingress_controller_bytes_sent</code> Histogram\\   The number of bytes sent to a client. Deprecated, use <code>nginx_ingress_controller_response_size</code>\\   nginx var: <code>bytes_sent</code></p> </li> <li> <p><code>nginx_ingress_controller_ingress_upstream_latency_seconds</code> Summary\\   Upstream service latency per Ingress. Deprecated, use <code>nginx_ingress_controller_connect_duration_seconds</code>\\   nginx var: <code>upstream_connect_time</code></p> </li> </ul> <pre><code># HELP nginx_ingress_controller_bytes_sent The number of bytes sent to a client. DEPRECATED! Use nginx_ingress_controller_response_size\n# TYPE nginx_ingress_controller_bytes_sent histogram\n# HELP nginx_ingress_controller_connect_duration_seconds The time spent on establishing a connection with the upstream server\n# TYPE nginx_ingress_controller_connect_duration_seconds nginx_ingress_controller_connect_duration_seconds\n* HELP nginx_ingress_controller_header_duration_seconds The time spent on receiving first header from the upstream server\n# TYPE nginx_ingress_controller_header_duration_seconds histogram\n# HELP nginx_ingress_controller_ingress_upstream_latency_seconds Upstream service latency per Ingress DEPRECATED! Use nginx_ingress_controller_connect_duration_seconds\n# TYPE nginx_ingress_controller_ingress_upstream_latency_seconds summary\n# HELP nginx_ingress_controller_request_duration_seconds The request processing time in milliseconds\n# TYPE nginx_ingress_controller_request_duration_seconds histogram\n# HELP nginx_ingress_controller_request_size The request length (including request line, header, and request body)\n# TYPE nginx_ingress_controller_request_size histogram\n# HELP nginx_ingress_controller_requests The total number of client requests.\n# TYPE nginx_ingress_controller_requests counter\n# HELP nginx_ingress_controller_response_duration_seconds The time spent on receiving the response from the upstream server\n# TYPE nginx_ingress_controller_response_duration_seconds histogram\n# HELP nginx_ingress_controller_response_size The response length (including request line, header, and request body)\n# TYPE nginx_ingress_controller_response_size histogram\n</code></pre>"},{"location":"user-guide/monitoring/#nginx-process-metrics","title":"Nginx process metrics","text":"<pre><code># HELP nginx_ingress_controller_nginx_process_connections current number of client connections with state {active, reading, writing, waiting}\n# TYPE nginx_ingress_controller_nginx_process_connections gauge\n# HELP nginx_ingress_controller_nginx_process_connections_total total number of connections with state {accepted, handled}\n# TYPE nginx_ingress_controller_nginx_process_connections_total counter\n# HELP nginx_ingress_controller_nginx_process_cpu_seconds_total Cpu usage in seconds\n# TYPE nginx_ingress_controller_nginx_process_cpu_seconds_total counter\n# HELP nginx_ingress_controller_nginx_process_num_procs number of processes\n# TYPE nginx_ingress_controller_nginx_process_num_procs gauge\n# HELP nginx_ingress_controller_nginx_process_oldest_start_time_seconds start time in seconds since 1970/01/01\n# TYPE nginx_ingress_controller_nginx_process_oldest_start_time_seconds gauge\n# HELP nginx_ingress_controller_nginx_process_read_bytes_total number of bytes read\n# TYPE nginx_ingress_controller_nginx_process_read_bytes_total counter\n# HELP nginx_ingress_controller_nginx_process_requests_total total number of client requests\n# TYPE nginx_ingress_controller_nginx_process_requests_total counter\n# HELP nginx_ingress_controller_nginx_process_resident_memory_bytes number of bytes of memory in use\n# TYPE nginx_ingress_controller_nginx_process_resident_memory_bytes gauge\n# HELP nginx_ingress_controller_nginx_process_virtual_memory_bytes number of bytes of memory in use\n# TYPE nginx_ingress_controller_nginx_process_virtual_memory_bytes gauge\n# HELP nginx_ingress_controller_nginx_process_write_bytes_total number of bytes written\n# TYPE nginx_ingress_controller_nginx_process_write_bytes_total counter\n</code></pre>"},{"location":"user-guide/monitoring/#controller-metrics","title":"Controller metrics","text":"<pre><code># HELP nginx_ingress_controller_build_info A metric with a constant '1' labeled with information about the build.\n# TYPE nginx_ingress_controller_build_info gauge\n# HELP nginx_ingress_controller_check_success Cumulative number of Ingress controller syntax check operations\n# TYPE nginx_ingress_controller_check_success counter\n# HELP nginx_ingress_controller_config_hash Running configuration hash actually running\n# TYPE nginx_ingress_controller_config_hash gauge\n# HELP nginx_ingress_controller_config_last_reload_successful Whether the last configuration reload attempt was successful\n# TYPE nginx_ingress_controller_config_last_reload_successful gauge\n# HELP nginx_ingress_controller_config_last_reload_successful_timestamp_seconds Timestamp of the last successful configuration reload.\n# TYPE nginx_ingress_controller_config_last_reload_successful_timestamp_seconds gauge\n# HELP nginx_ingress_controller_ssl_certificate_info Hold all labels associated to a certificate\n# TYPE nginx_ingress_controller_ssl_certificate_info gauge\n# HELP nginx_ingress_controller_success Cumulative number of Ingress controller reload operations\n# TYPE nginx_ingress_controller_success counter\n# HELP nginx_ingress_controller_orphan_ingress Gauge reporting status of ingress orphanity, 1 indicates orphaned ingress. 'namespace' is the string used to identify namespace of ingress, 'ingress' for ingress name and 'type' for 'no-service' or 'no-endpoint' of orphanity\n# TYPE nginx_ingress_controller_orphan_ingress gauge\n</code></pre>"},{"location":"user-guide/monitoring/#admission-metrics","title":"Admission metrics","text":"<pre><code># HELP nginx_ingress_controller_admission_config_size The size of the tested configuration\n# TYPE nginx_ingress_controller_admission_config_size gauge\n# HELP nginx_ingress_controller_admission_render_duration The processing duration of ingresses rendering by the admission controller (float seconds)\n# TYPE nginx_ingress_controller_admission_render_duration gauge\n# HELP nginx_ingress_controller_admission_render_ingresses The length of ingresses rendered by the admission controller\n# TYPE nginx_ingress_controller_admission_render_ingresses gauge\n# HELP nginx_ingress_controller_admission_roundtrip_duration The complete duration of the admission controller at the time to process a new event (float seconds)\n# TYPE nginx_ingress_controller_admission_roundtrip_duration gauge\n# HELP nginx_ingress_controller_admission_tested_duration The processing duration of the admission controller tests (float seconds)\n# TYPE nginx_ingress_controller_admission_tested_duration gauge\n# HELP nginx_ingress_controller_admission_tested_ingresses The length of ingresses processed by the admission controller\n# TYPE nginx_ingress_controller_admission_tested_ingresses gauge\n</code></pre>"},{"location":"user-guide/monitoring/#histogram-buckets","title":"Histogram buckets","text":"<p>You can configure buckets for histogram metrics using these command line options (here are their default values): * <code>--time-buckets=[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]</code> * <code>--length-buckets=[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]</code> * <code>--size-buckets=[10, 100, 1000, 10000, 100000, 1e+06, 1e+07]</code></p>"},{"location":"user-guide/multiple-ingress/","title":"Multiple Ingress controllers","text":"<p>By default, deploying multiple Ingress controllers (e.g., <code>ingress-nginx</code> &amp; <code>gce</code>) will result in all controllers simultaneously racing to update Ingress status fields in confusing ways.</p> <p>To fix this problem, use IngressClasses. The <code>kubernetes.io/ingress.class</code> annotation is not being preferred or suggested to use as it can be deprecated in the future. Better to use the field <code>ingress.spec.ingressClassName</code>. But, when user has deployed with <code>scope.enabled</code>, then the ingress class resource field is not used.</p>"},{"location":"user-guide/multiple-ingress/#using-ingressclasses","title":"Using IngressClasses","text":"<p>If all ingress controllers respect IngressClasses (e.g. multiple instances of ingress-nginx v1.0), you can deploy two Ingress controllers by granting them control over two different IngressClasses, then selecting one of the two IngressClasses with <code>ingressClassName</code>.</p> <p>First, ensure the <code>--controller-class=</code> and <code>--ingress-class</code> are set to something different on each ingress controller, If your additional ingress controller is to be installed in a namespace, where there is/are one/more-than-one ingress-nginx-controller(s) already installed, then you need to specify a different unique <code>--election-id</code> for the new instance of the controller.</p> <pre><code># ingress-nginx Deployment/Statefulset\nspec:\n  template:\n     spec:\n       containers:\n         - name: ingress-nginx-internal-controller\n           args:\n             - /nginx-ingress-controller\n             - '--election-id=ingress-controller-leader'\n             - '--controller-class=k8s.io/internal-ingress-nginx'\n             - '--ingress-class=k8s.io/internal-nginx'\n            ...\n</code></pre> <p>Then use the same value in the IngressClass:</p> <pre><code># ingress-nginx IngressClass\napiVersion: networking.k8s.io/v1\nkind: IngressClass\nmetadata:\n  name: internal-nginx\nspec:\n  controller: k8s.io/internal-ingress-nginx\n  ...\n</code></pre> <p>And refer to that IngressClass in your Ingress:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: my-ingress\nspec:\n  ingressClassName: internal-nginx\n  ...\n</code></pre> <p>or if installing with Helm:</p> <pre><code>controller:\n  electionID: ingress-controller-leader\n  ingressClassResource:\n    name: internal-nginx  # default: nginx\n    enabled: true\n    default: false\n    controllerValue: \"k8s.io/internal-ingress-nginx\"  # default: k8s.io/ingress-nginx\n</code></pre> <p>Important</p> <p>When running multiple ingress-nginx controllers, it will only process an unset class annotation if one of the controllers uses the default <code>--controller-class</code> value (see <code>IsValid</code> method in <code>internal/ingress/annotations/class/main.go</code>), otherwise the class annotation becomes required.</p> <p>If <code>--controller-class</code> is set to the default value of <code>k8s.io/ingress-nginx</code>, the controller will monitor Ingresses with no class annotation and Ingresses with annotation class set to <code>nginx</code>. Use a non-default value for <code>--controller-class</code>, to ensure that the controller only satisfied the specific class of Ingresses.</p>"},{"location":"user-guide/multiple-ingress/#using-the-kubernetesioingressclass-annotation-in-deprecation","title":"Using the kubernetes.io/ingress.class annotation (in deprecation)","text":"<p>If you're running multiple ingress controllers where one or more do not support IngressClasses, you must specify the annotation <code>kubernetes.io/ingress.class: \"nginx\"</code> in all ingresses that you would like ingress-nginx to claim.</p> <p>For instance,</p> <pre><code>metadata:\n  name: foo\n  annotations:\n    kubernetes.io/ingress.class: \"gce\"\n</code></pre> <p>will target the GCE controller, forcing the Ingress-NGINX controller to ignore it, while an annotation like:</p> <pre><code>metadata:\n  name: foo\n  annotations:\n    kubernetes.io/ingress.class: \"nginx\"\n</code></pre> <p>will target the Ingress-NGINX controller, forcing the GCE controller to ignore it.</p> <p>You can change the value \"nginx\" to something else by setting the <code>--ingress-class</code> flag:</p> <pre><code>spec:\n  template:\n     spec:\n       containers:\n         - name: ingress-nginx-internal-controller\n           args:\n             - /nginx-ingress-controller\n             - --ingress-class=internal-nginx\n</code></pre> <p>then setting the corresponding <code>kubernetes.io/ingress.class: \"internal-nginx\"</code> annotation on your Ingresses.</p> <p>To reiterate, setting the annotation to any value which does not match a valid ingress class will force the Ingress-Nginx Controller to ignore your Ingress. If you are only running a single Ingress-Nginx Controller, this can be achieved by setting the annotation to any value except \"nginx\" or an empty string.</p> <p>Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.</p>"},{"location":"user-guide/retaining-client-ipaddress/","title":"Retaining client ipaddress","text":""},{"location":"user-guide/retaining-client-ipaddress/#retaining-client-ipaddress","title":"Retaining Client IPAddress","text":"<p>Please read this https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/#source-ip-address , to get details of retaining the client IPAddress.</p>"},{"location":"user-guide/retaining-client-ipaddress/#using-proxy-protocol","title":"Using proxy-protocol","text":"<p>Please read this https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/#proxy-protocol , to use proxy-protocol for retaining client IPAddress</p>"},{"location":"user-guide/retaining-client-ipaddress/#using-the-k8s-spec-servicespecexternaltrafficpolicy","title":"Using the K8S spec service.spec.externalTrafficPolicy","text":"<pre><code>% kubectl explain service.spec.externalTrafficPolicy\nKIND:       Service\nVERSION:    v1\n\nFIELD: externalTrafficPolicy &lt;string&gt;\n\nDESCRIPTION:\n    externalTrafficPolicy describes how nodes distribute service traffic they\n    receive on one of the Service's \"externally-facing\" addresses (NodePorts,\n    ExternalIPs, and LoadBalancer IPs). If set to \"Local\", the proxy will\n    configure the service in a way that assumes that external load balancers\n    will take care of balancing the service traffic between nodes, and so each\n    node will deliver traffic only to the node-local endpoints of the service,\n    without masquerading the client source IP. (Traffic mistakenly sent to a\n    node with no endpoints will be dropped.) The default value, \"Cluster\", uses\n    the standard behavior of routing to all endpoints evenly (possibly modified\n    by topology and other features). Note that traffic sent to an External IP or\n    LoadBalancer IP from within the cluster will always get \"Cluster\" semantics,\n    but clients sending to a NodePort from within the cluster may need to take\n    traffic policy into account when picking a node.\n\n    Possible enum values:\n     - `\"Cluster\"` routes traffic to all endpoints.\n     - `\"Local\"` preserves the source IP of the traffic by routing only to\n    endpoints on the same node as the traffic was received on (dropping the\n    traffic if there are no local endpoints).\n</code></pre> <ul> <li>Setting the field <code>externalTrafficPolicy</code>, in the ingress-controller service, to a value of <code>Local</code> retains the client's ipaddress, within the scope explained above</li> </ul>"},{"location":"user-guide/tls/","title":"TLS/HTTPS","text":""},{"location":"user-guide/tls/#tls-secrets","title":"TLS Secrets","text":"<p>Anytime we reference a TLS secret, we mean a PEM-encoded X.509, RSA (2048) secret.</p> <p>Warning</p> <p>Ensure that the certificate order is leaf-&gt;intermediate-&gt;root, otherwise the controller will not be able to import the certificate, and you'll see this error in the logs <code>W1012 09:15:45.920000       6 backend_ssl.go:46] Error obtaining X.509 certificate: unexpected error creating SSL Cert: certificate and private key does not have a matching public key: tls: private key does not match public key</code></p> <p>You can generate a self-signed certificate and private key with:</p> <pre><code>$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${CERT_FILE} -subj \"/CN=${HOST}/O=${HOST}\" -addext \"subjectAltName = DNS:${HOST}\"\n</code></pre> <p>Then create the secret in the cluster via:</p> <pre><code>kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE}\n</code></pre> <p>The resulting secret will be of type <code>kubernetes.io/tls</code>.</p>"},{"location":"user-guide/tls/#host-names","title":"Host names","text":"<p>Ensure that the relevant ingress rules specify a matching host name.</p>"},{"location":"user-guide/tls/#default-ssl-certificate","title":"Default SSL Certificate","text":"<p>NGINX provides the option to configure a server as a catch-all with server_name for requests that do not match any of the configured server names. This configuration works out-of-the-box for HTTP traffic. For HTTPS, a certificate is naturally required.</p> <p>For this reason the Ingress controller provides the flag <code>--default-ssl-certificate</code>. The secret referred to by this flag contains the default certificate to be used when accessing the catch-all server. If this flag is not provided NGINX will use a self-signed certificate.</p> <p>For instance, if you have a TLS secret <code>foo-tls</code> in the <code>default</code> namespace, add <code>--default-ssl-certificate=default/foo-tls</code> in the <code>nginx-controller</code> deployment.</p> <p>The default certificate will also be used for ingress <code>tls:</code> sections that do not have a <code>secretName</code> option.</p> <p>To force redirects for Ingresses that do not specify a TLS-block at all, take a look at <code>force-ssl-redirect</code> in ConfigMap.</p>"},{"location":"user-guide/tls/#ssl-passthrough","title":"SSL Passthrough","text":"<p>The <code>--enable-ssl-passthrough</code> flag enables the SSL Passthrough feature, which is disabled by default. This is required to enable passthrough backends in Ingress objects.</p> <p>Warning</p> <p>This feature is implemented by intercepting all traffic on the configured HTTPS port (default: 443) and handing it over to a local TCP proxy. This bypasses NGINX completely and introduces a non-negligible performance penalty.</p> <p>SSL Passthrough leverages SNI and reads the virtual domain from the TLS negotiation, which requires compatible clients. After a connection has been accepted by the TLS listener, it is handled by the controller itself and piped back and forth between the backend and the client.</p> <p>If there is no hostname matching the requested host name, the request is handed over to NGINX on the configured passthrough proxy port (default: 442), which proxies the request to the default backend.</p> <p>Note</p> <p>Unlike HTTP backends, traffic to Passthrough backends is sent to the clusterIP of the backing Service instead of individual Endpoints.</p>"},{"location":"user-guide/tls/#http-strict-transport-security","title":"HTTP Strict Transport Security","text":"<p>HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS.</p> <p>HSTS is enabled by default.</p> <p>To disable this behavior use <code>hsts: \"false\"</code> in the configuration ConfigMap.</p>"},{"location":"user-guide/tls/#server-side-https-enforcement-through-redirect","title":"Server-side HTTPS enforcement through redirect","text":"<p>By default the controller redirects HTTP clients to the HTTPS port 443 using a 308 Permanent Redirect response if TLS is enabled for that Ingress.</p> <p>This can be disabled globally using <code>ssl-redirect: \"false\"</code> in the NGINX config map, or per-Ingress with the <code>nginx.ingress.kubernetes.io/ssl-redirect: \"false\"</code> annotation in the particular resource.</p> <p>Tip</p> <p>When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is no TLS certificate available. This can be achieved by using the <code>nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"</code> annotation in the particular resource.</p>"},{"location":"user-guide/tls/#automated-certificate-management-with-cert-manager","title":"Automated Certificate Management with cert-manager","text":"<p>cert-manager automatically requests missing or expired certificates from a range of  supported issuers (including Let's Encrypt) by monitoring  ingress resources.</p> <p>To set up cert-manager you should take a look at this full example.</p> <p>To enable it for an ingress resource you have to deploy cert-manager, configure a certificate  issuer update the manifest:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-demo\n  annotations:\n    cert-manager.io/issuer: \"letsencrypt-staging\" # Replace this with a production issuer once you've tested it\n    [..]\nspec:\n  tls:\n    - hosts:\n        - ingress-demo.example.com\n      secretName: ingress-demo-tls\n    [...]\n</code></pre>"},{"location":"user-guide/tls/#default-tls-version-and-ciphers","title":"Default TLS Version and Ciphers","text":"<p>To provide the most secure baseline configuration possible,</p> <p>ingress-nginx defaults to using TLS 1.2 and 1.3 only, with a secure set of TLS ciphers.</p>"},{"location":"user-guide/tls/#legacy-tls","title":"Legacy TLS","text":"<p>The default configuration, though secure, does not support some older browsers and operating systems.</p> <p>For instance, TLS 1.1+ is only enabled by default from Android 5.0 on. At the time of writing, May 2018, approximately 15% of Android devices are not compatible with ingress-nginx's default configuration.</p> <p>To change this default behavior, use a ConfigMap.</p> <p>A sample ConfigMap fragment to allow these older clients to connect could look something like the following (generated using the Mozilla SSL Configuration Generator)mozilla-ssl-config-old:</p> <pre><code>kind: ConfigMap\napiVersion: v1\nmetadata:\n  name: nginx-config\ndata:\n  ssl-ciphers: \"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA\"\n  ssl-protocols: \"TLSv1 TLSv1.1 TLSv1.2 TLSv1.3\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/","title":"NGINX Configuration","text":"<p>There are three ways to customize NGINX:</p> <ol> <li>ConfigMap: using a Configmap to set global configurations in NGINX.</li> <li>Annotations: use this if you want a specific configuration for a particular Ingress rule.</li> <li>Custom template: when more specific settings are required, like open_file_cache, adjust listen options as <code>rcvbuf</code> or when is not possible to change the configuration through the ConfigMap.</li> </ol>"},{"location":"user-guide/nginx-configuration/annotations/","title":"Annotations","text":"<p>You can add these Kubernetes annotations to specific Ingress objects to customize their behavior.</p> <p>Tip</p> <p>Annotation keys and values can only be strings. Other types, such as boolean or numeric values must be quoted, i.e. <code>\"true\"</code>, <code>\"false\"</code>, <code>\"100\"</code>.</p> <p>Note</p> <p>The annotation prefix can be changed using the <code>--annotations-prefix</code> command line argument, but the default is <code>nginx.ingress.kubernetes.io</code>, as described in the table below.</p> Name type nginx.ingress.kubernetes.io/app-root string nginx.ingress.kubernetes.io/affinity cookie nginx.ingress.kubernetes.io/affinity-mode \"balanced\" or \"persistent\" nginx.ingress.kubernetes.io/affinity-canary-behavior \"sticky\" or \"legacy\" nginx.ingress.kubernetes.io/auth-realm string nginx.ingress.kubernetes.io/auth-secret string nginx.ingress.kubernetes.io/auth-secret-type string nginx.ingress.kubernetes.io/auth-type \"basic\" or \"digest\" nginx.ingress.kubernetes.io/auth-tls-secret string nginx.ingress.kubernetes.io/auth-tls-verify-depth number nginx.ingress.kubernetes.io/auth-tls-verify-client string nginx.ingress.kubernetes.io/auth-tls-error-page string nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/auth-tls-match-cn string nginx.ingress.kubernetes.io/auth-url string nginx.ingress.kubernetes.io/auth-cache-key string nginx.ingress.kubernetes.io/auth-cache-duration string nginx.ingress.kubernetes.io/auth-keepalive number nginx.ingress.kubernetes.io/auth-keepalive-share-vars \"true\" or \"false\" nginx.ingress.kubernetes.io/auth-keepalive-requests number nginx.ingress.kubernetes.io/auth-keepalive-timeout number nginx.ingress.kubernetes.io/auth-proxy-set-headers string nginx.ingress.kubernetes.io/auth-snippet string nginx.ingress.kubernetes.io/enable-global-auth \"true\" or \"false\" nginx.ingress.kubernetes.io/backend-protocol string nginx.ingress.kubernetes.io/canary \"true\" or \"false\" nginx.ingress.kubernetes.io/canary-by-header string nginx.ingress.kubernetes.io/canary-by-header-value string nginx.ingress.kubernetes.io/canary-by-header-pattern string nginx.ingress.kubernetes.io/canary-by-cookie string nginx.ingress.kubernetes.io/canary-weight number nginx.ingress.kubernetes.io/canary-weight-total number nginx.ingress.kubernetes.io/client-body-buffer-size string nginx.ingress.kubernetes.io/configuration-snippet string nginx.ingress.kubernetes.io/custom-http-errors []int nginx.ingress.kubernetes.io/custom-headers string nginx.ingress.kubernetes.io/default-backend string nginx.ingress.kubernetes.io/enable-cors \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-allow-origin string nginx.ingress.kubernetes.io/cors-allow-methods string nginx.ingress.kubernetes.io/cors-allow-headers string nginx.ingress.kubernetes.io/cors-expose-headers string nginx.ingress.kubernetes.io/cors-allow-credentials \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-max-age number nginx.ingress.kubernetes.io/force-ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/from-to-www-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/http2-push-preload \"true\" or \"false\" nginx.ingress.kubernetes.io/limit-connections number nginx.ingress.kubernetes.io/limit-rps number nginx.ingress.kubernetes.io/global-rate-limit number nginx.ingress.kubernetes.io/global-rate-limit-window duration nginx.ingress.kubernetes.io/global-rate-limit-key string nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs string nginx.ingress.kubernetes.io/permanent-redirect string nginx.ingress.kubernetes.io/permanent-redirect-code number nginx.ingress.kubernetes.io/temporal-redirect string nginx.ingress.kubernetes.io/preserve-trailing-slash \"true\" or \"false\" nginx.ingress.kubernetes.io/proxy-body-size string nginx.ingress.kubernetes.io/proxy-cookie-domain string nginx.ingress.kubernetes.io/proxy-cookie-path string nginx.ingress.kubernetes.io/proxy-connect-timeout number nginx.ingress.kubernetes.io/proxy-send-timeout number nginx.ingress.kubernetes.io/proxy-read-timeout number nginx.ingress.kubernetes.io/proxy-next-upstream string nginx.ingress.kubernetes.io/proxy-next-upstream-timeout number nginx.ingress.kubernetes.io/proxy-next-upstream-tries number nginx.ingress.kubernetes.io/proxy-request-buffering string nginx.ingress.kubernetes.io/proxy-redirect-from string nginx.ingress.kubernetes.io/proxy-redirect-to string nginx.ingress.kubernetes.io/proxy-http-version \"1.0\" or \"1.1\" nginx.ingress.kubernetes.io/proxy-ssl-secret string nginx.ingress.kubernetes.io/proxy-ssl-ciphers string nginx.ingress.kubernetes.io/proxy-ssl-name string nginx.ingress.kubernetes.io/proxy-ssl-protocols string nginx.ingress.kubernetes.io/proxy-ssl-verify string nginx.ingress.kubernetes.io/proxy-ssl-verify-depth number nginx.ingress.kubernetes.io/proxy-ssl-server-name string nginx.ingress.kubernetes.io/enable-rewrite-log \"true\" or \"false\" nginx.ingress.kubernetes.io/rewrite-target URI nginx.ingress.kubernetes.io/satisfy string nginx.ingress.kubernetes.io/server-alias string nginx.ingress.kubernetes.io/server-snippet string nginx.ingress.kubernetes.io/service-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-change-on-failure \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-domain string nginx.ingress.kubernetes.io/session-cookie-expires string nginx.ingress.kubernetes.io/session-cookie-max-age string nginx.ingress.kubernetes.io/session-cookie-name string nginx.ingress.kubernetes.io/session-cookie-path string nginx.ingress.kubernetes.io/session-cookie-samesite string nginx.ingress.kubernetes.io/session-cookie-secure string nginx.ingress.kubernetes.io/ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/ssl-passthrough \"true\" or \"false\" nginx.ingress.kubernetes.io/stream-snippet string nginx.ingress.kubernetes.io/upstream-hash-by string nginx.ingress.kubernetes.io/x-forwarded-prefix string nginx.ingress.kubernetes.io/load-balance string nginx.ingress.kubernetes.io/upstream-vhost string nginx.ingress.kubernetes.io/denylist-source-range CIDR nginx.ingress.kubernetes.io/whitelist-source-range CIDR nginx.ingress.kubernetes.io/proxy-buffering string nginx.ingress.kubernetes.io/proxy-buffers-number number nginx.ingress.kubernetes.io/proxy-buffer-size string nginx.ingress.kubernetes.io/proxy-max-temp-file-size string nginx.ingress.kubernetes.io/ssl-ciphers string nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers \"true\" or \"false\" nginx.ingress.kubernetes.io/connection-proxy-header string nginx.ingress.kubernetes.io/enable-access-log \"true\" or \"false\" nginx.ingress.kubernetes.io/enable-opentelemetry \"true\" or \"false\" nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span \"true\" or \"false\" nginx.ingress.kubernetes.io/use-regex bool nginx.ingress.kubernetes.io/enable-modsecurity bool nginx.ingress.kubernetes.io/enable-owasp-core-rules bool nginx.ingress.kubernetes.io/modsecurity-transaction-id string nginx.ingress.kubernetes.io/modsecurity-snippet string nginx.ingress.kubernetes.io/mirror-request-body string nginx.ingress.kubernetes.io/mirror-target string nginx.ingress.kubernetes.io/mirror-host string"},{"location":"user-guide/nginx-configuration/annotations/#canary","title":"Canary","text":"<p>In some cases, you may want to \"canary\" a new set of changes by sending a small number of requests to a different service than the production service. The canary annotation enables the Ingress spec to act as an alternative service for requests to route to depending on the rules applied. The following annotations to configure canary can be enabled after <code>nginx.ingress.kubernetes.io/canary: \"true\"</code> is set:</p> <ul> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-header</code>: The header to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the request header is set to <code>always</code>, it will be routed to the canary. When the header is set to <code>never</code>, it will never be routed to the canary. For any other value, the header will be ignored and the request compared against the other canary rules by precedence.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-header-value</code>: The header value to match for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the request header is set to this value, it will be routed to the canary. For any other header value, the header will be ignored and the request compared against the other canary rules by precedence. This annotation has to be used together with <code>nginx.ingress.kubernetes.io/canary-by-header</code>. The annotation is an extension of the <code>nginx.ingress.kubernetes.io/canary-by-header</code> to allow customizing the header value instead of using hardcoded values. It doesn't have any effect if the <code>nginx.ingress.kubernetes.io/canary-by-header</code> annotation is not defined.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-header-pattern</code>: This works the same way as <code>canary-by-header-value</code> except it does PCRE Regex matching. Note that when <code>canary-by-header-value</code> is set this annotation will be ignored. When the given Regex causes error during request processing, the request will be considered as not matching.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-cookie</code>: The cookie to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the cookie value is set to <code>always</code>, it will be routed to the canary. When the cookie is set to <code>never</code>, it will never be routed to the canary. For any other value, the cookie will be ignored and the request compared against the other canary rules by precedence.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-weight</code>: The integer based (0 - ) percent of random requests that should be routed to the service specified in the canary Ingress. A weight of 0 implies that no requests will be sent to the service in the Canary ingress by this canary rule. A weight of <code>&lt;weight-total&gt;</code> means implies all requests will be sent to the alternative service specified in the Ingress. <code>&lt;weight-total&gt;</code> defaults to 100, and can be increased via <code>nginx.ingress.kubernetes.io/canary-weight-total</code>. <li> <p><code>nginx.ingress.kubernetes.io/canary-weight-total</code>: The total weight of traffic. If unspecified, it defaults to 100.</p> </li> <p>Canary rules are evaluated in order of precedence. Precedence is as follows: <code>canary-by-header -&gt; canary-by-cookie -&gt; canary-weight</code></p> <p>Note that when you mark an ingress as canary, then all the other non-canary annotations will be ignored (inherited from the corresponding main ingress) except <code>nginx.ingress.kubernetes.io/load-balance</code>, <code>nginx.ingress.kubernetes.io/upstream-hash-by</code>, and annotations related to session affinity. If you want to restore the original behavior of canaries when session affinity was ignored, set <code>nginx.ingress.kubernetes.io/affinity-canary-behavior</code> annotation with value <code>legacy</code> on the canary ingress definition.</p> <p>Known Limitations</p> <p>Currently a maximum of one canary ingress can be applied per Ingress rule.</p>"},{"location":"user-guide/nginx-configuration/annotations/#rewrite","title":"Rewrite","text":"<p>In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404. Set the annotation <code>nginx.ingress.kubernetes.io/rewrite-target</code> to the path expected by the service.</p> <p>If the Application Root is exposed in a different path and needs to be redirected, set the annotation <code>nginx.ingress.kubernetes.io/app-root</code> to redirect requests for <code>/</code>.</p> <p>Example</p> <p>Please check the rewrite example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#session-affinity","title":"Session Affinity","text":"<p>The annotation <code>nginx.ingress.kubernetes.io/affinity</code> enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server. The only affinity type available for NGINX is <code>cookie</code>.</p> <p>The annotation <code>nginx.ingress.kubernetes.io/affinity-mode</code> defines the stickiness of a session. Setting this to <code>balanced</code> (default) will redistribute some sessions if a deployment gets scaled up, therefore rebalancing the load on the servers. Setting this to <code>persistent</code> will not rebalance sessions to new servers, therefore providing maximum stickiness.</p> <p>The annotation <code>nginx.ingress.kubernetes.io/affinity-canary-behavior</code> defines the behavior of canaries when session affinity is enabled. Setting this to <code>sticky</code> (default) will ensure that users that were served by canaries, will continue to be served by canaries. Setting this to <code>legacy</code> will restore original canary behavior, when session affinity was ignored.</p> <p>Attention</p> <p>If more than one Ingress is defined for a host and at least one Ingress uses <code>nginx.ingress.kubernetes.io/affinity: cookie</code>, then only paths on the Ingress using <code>nginx.ingress.kubernetes.io/affinity</code> will use session cookie affinity. All paths defined on other Ingresses for the host will be load balanced through the random selection of a backend server.</p> <p>Example</p> <p>Please check the affinity example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#cookie-affinity","title":"Cookie affinity","text":"<p>If you use the <code>cookie</code> affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation <code>nginx.ingress.kubernetes.io/session-cookie-name</code>. The default is to create a cookie named 'INGRESSCOOKIE'.</p> <p>The NGINX annotation <code>nginx.ingress.kubernetes.io/session-cookie-path</code> defines the path that will be set on the cookie. This is optional unless the annotation <code>nginx.ingress.kubernetes.io/use-regex</code> is set to true; Session cookie paths do not support regex.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-domain</code> to set the <code>Domain</code> attribute of the sticky cookie.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-samesite</code> to apply a <code>SameSite</code> attribute to the sticky cookie. Browser accepted values are <code>None</code>, <code>Lax</code>, and <code>Strict</code>. Some browsers reject cookies with <code>SameSite=None</code>, including those created before the <code>SameSite=None</code> specification (e.g. Chrome 5X). Other browsers mistakenly treat <code>SameSite=None</code> cookies as <code>SameSite=Strict</code> (e.g. Safari running on OSX 14). To omit <code>SameSite=None</code> from browsers with these incompatibilities, add the annotation <code>nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: \"true\"</code>.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-expires</code> to control the cookie expires, its value is a number of seconds until the cookie expires.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-path</code> to control the cookie path when use-regex is set to true.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-change-on-failure</code> to control the cookie change after request failure.</p>"},{"location":"user-guide/nginx-configuration/annotations/#authentication","title":"Authentication","text":"<p>It is possible to add authentication by adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords.</p> <p>The annotations are: <pre><code>nginx.ingress.kubernetes.io/auth-type: [basic|digest]\n</code></pre></p> <p>Indicates the HTTP Authentication Type: Basic or Digest Access Authentication.</p> <pre><code>nginx.ingress.kubernetes.io/auth-secret: secretName\n</code></pre> <p>The name of the Secret that contains the usernames and passwords which are granted access to the <code>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> <pre><code>nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]\n</code></pre> <p>The <code>auth-secret</code> can have two forms:</p> <ul> <li><code>auth-file</code> - default, an htpasswd file in the key <code>auth</code> within the secret</li> <li><code>auth-map</code> - the keys of the secret are the usernames, and the values are the hashed passwords</li> </ul> <pre><code>nginx.ingress.kubernetes.io/auth-realm: \"realm string\"\n</code></pre> <p>Example</p> <p>Please check the auth example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-nginx-upstream-hashing","title":"Custom NGINX upstream hashing","text":"<p>NGINX supports load balancing by client-server mapping based on consistent hashing 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 ketama consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.</p> <p>There is a special mode of upstream hashing called subset. In this mode, upstream servers are grouped into subsets, and stickiness works by mapping keys to a subset instead of individual upstream servers. Specific server is chosen uniformly at random from the selected sticky subset. It provides a balance between stickiness and load distribution.</p> <p>To enable consistent hashing for a backend:</p> <p><code>nginx.ingress.kubernetes.io/upstream-hash-by</code>: the nginx variable, text value or any combination thereof to use for consistent hashing. For example: <code>nginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri\"</code> or <code>nginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri$host\"</code> or <code>nginx.ingress.kubernetes.io/upstream-hash-by: \"${request_uri}-text-value\"</code> to consistently hash upstream requests by the current request URI.</p> <p>\"subset\" hashing can be enabled setting <code>nginx.ingress.kubernetes.io/upstream-hash-by-subset</code>: \"true\". This maps requests to subset of nodes instead of a single one. <code>nginx.ingress.kubernetes.io/upstream-hash-by-subset-size</code> determines the size of each subset (default 3).</p> <p>Please check the chashsubset example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-nginx-load-balancing","title":"Custom NGINX load balancing","text":"<p>This is similar to <code>load-balance</code> in ConfigMap, but configures load balancing algorithm per ingress.</p> <p>Note that <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> takes preference over this. If this and <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> are not set then we fallback to using globally configured load balancing algorithm.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-nginx-upstream-vhost","title":"Custom NGINX upstream vhost","text":"<p>This configuration setting allows you to control the value for host in the following statement: <code>proxy_set_header Host $host</code>, which forms part of the location block.  This is useful if you need to call the upstream server by something other than <code>$host</code>.</p>"},{"location":"user-guide/nginx-configuration/annotations/#client-certificate-authentication","title":"Client Certificate Authentication","text":"<p>It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.</p> <p>Client Certificate Authentication is applied per host and it is not possible to specify rules that differ for individual paths.</p> <p>To enable, add the annotation <code>nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName</code>. This secret must have a file named <code>ca.crt</code> containing the full Certificate Authority chain <code>ca.crt</code> that is enabled to authenticate against this Ingress.</p> <p>You can further customize client certificate authentication and behavior with these annotations:</p> <ul> <li><code>nginx.ingress.kubernetes.io/auth-tls-verify-depth</code>: The validation depth between the provided client certificate and the Certification Authority chain. (default: 1)</li> <li><code>nginx.ingress.kubernetes.io/auth-tls-verify-client</code>: Enables verification of client certificates. Possible values are:<ul> <li><code>on</code>: Request a client certificate that must be signed by a certificate that is included in the secret key <code>ca.crt</code> of the secret specified by <code>nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName</code>. Failed certificate verification will result in a status code 400 (Bad Request) (default)</li> <li><code>off</code>: Don't request client certificates and don't do client certificate verification.</li> <li><code>optional</code>: Do optional client certificate validation against the CAs from <code>auth-tls-secret</code>. The request fails with status code 400 (Bad Request) when a certificate is provided that is not signed by the CA. When no or an otherwise invalid certificate is provided, the request does not fail, but instead the verification result is sent to the upstream service.</li> <li><code>optional_no_ca</code>: Do optional client certificate validation, but do not fail the request when the client certificate is not signed by the CAs from <code>auth-tls-secret</code>. Certificate verification result is sent to the upstream service.</li> </ul> </li> <li><code>nginx.ingress.kubernetes.io/auth-tls-error-page</code>: The URL/Page that user should be redirected in case of a Certificate Authentication Error</li> <li><code>nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream</code>: Indicates if the received certificates should be passed or not to the upstream server in the header <code>ssl-client-cert</code>. Possible values are \"true\" or \"false\" (default).</li> <li><code>nginx.ingress.kubernetes.io/auth-tls-match-cn</code>: Adds a sanity check for the CN of the client certificate that is sent over using a string / regex starting with \"CN=\", example: <code>\"CN=myvalidclient\"</code>. If the certificate CN sent during mTLS does not match your string / regex it will fail with status code 403. Another way of using this is by adding multiple options in your regex, example: <code>\"CN=(option1|option2|myvalidclient)\"</code>. In this case, as long as one of the options in the brackets matches the certificate CN then you will receive a 200 status code. </li> </ul> <p>The following headers are sent to the upstream service according to the <code>auth-tls-*</code> annotations:</p> <ul> <li><code>ssl-client-issuer-dn</code>: The issuer information of the client certificate. Example: \"CN=My CA\"</li> <li><code>ssl-client-subject-dn</code>: The subject information of the client certificate. Example: \"CN=My Client\"</li> <li><code>ssl-client-verify</code>: The result of the client verification. Possible values: \"SUCCESS\", \"FAILED: \" <li><code>ssl-client-cert</code>: The full client certificate in PEM format. Will only be sent when <code>nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream</code> is set to \"true\". Example: <code>-----BEGIN%20CERTIFICATE-----%0A...---END%20CERTIFICATE-----%0A</code></li> <p>Example</p> <p>Please check the client-certs example.</p> <p>Attention</p> <p>TLS with Client Authentication is not possible in Cloudflare and might result in unexpected behavior.</p> <p>Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/</p> <p>Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls</p>"},{"location":"user-guide/nginx-configuration/annotations/#backend-certificate-authentication","title":"Backend Certificate Authentication","text":"<p>It is possible to authenticate to a proxied HTTPS backend with certificate using additional annotations in Ingress Rule.</p> <ul> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-secret: secretName</code>:   Specifies a Secret with the certificate <code>tls.crt</code>, key <code>tls.key</code> in PEM format used for authentication to a proxied HTTPS server. It should also contain trusted CA certificates <code>ca.crt</code> in PEM format used to verify the certificate of the proxied HTTPS server.   This annotation expects the Secret name in the form \"namespace/secretName\".</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-verify</code>:   Enables or disables verification of the proxied HTTPS server certificate. (default: off)</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-verify-depth</code>:   Sets the verification depth in the proxied HTTPS server certificates chain. (default: 1)</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-ciphers</code>:   Specifies the enabled ciphers for requests to a proxied HTTPS server. The ciphers are specified in the format understood by the OpenSSL library.</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-name</code>:   Allows to set proxy_ssl_name. This allows overriding the server name used to verify the certificate of the proxied HTTPS server. This value is also passed through SNI when a connection is established to the proxied HTTPS server.</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-protocols</code>:   Enables the specified protocols for requests to a proxied HTTPS server.</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-server-name</code>:   Enables passing of the server name through TLS Server Name Indication extension (SNI, RFC 6066) when establishing a connection with the proxied HTTPS server.</li> </ul>"},{"location":"user-guide/nginx-configuration/annotations/#configuration-snippet","title":"Configuration snippet","text":"<p>Using this annotation you can add additional configuration to the NGINX location. For example:</p> <pre><code>nginx.ingress.kubernetes.io/configuration-snippet: |\n  more_set_headers \"Request-Id: $req_id\";\n</code></pre> <p>Be aware this can be dangerous in multi-tenant clusters, as it can lead to people with otherwise limited permissions being able to retrieve all secrets on the cluster. The recommended mitigation for this threat is to disable this feature, so it may not work for you. See CVE-2021-25742 and the related issue on github for more information.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-http-errors","title":"Custom HTTP Errors","text":"<p>Like the <code>custom-http-errors</code> value in the ConfigMap, this annotation will set NGINX <code>proxy-intercept-errors</code>, but only for the NGINX location associated with this ingress. If a default backend annotation is specified on the ingress, the errors will be routed to that annotation's default backend service (instead of the global default backend). Different ingresses can specify different sets of error codes. Even if multiple ingress objects share the same hostname, this annotation can be used to intercept different error codes for each ingress (for example, different error codes to be intercepted for different paths on the same hostname, if each path is on a different ingress). If <code>custom-http-errors</code> is also specified globally, the error values specified in this annotation will override the global value for the given ingress' hostname and path.</p> <p>Example usage: <pre><code>nginx.ingress.kubernetes.io/custom-http-errors: \"404,415\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-headers","title":"Custom Headers","text":"<p>This annotation is of the form <code>nginx.ingress.kubernetes.io/custom-headers: custom-headers-configmap</code> to specify a configmap name that contains custom headers. This annotation uses <code>more_set_headers</code> nginx directive.</p> <p>Example configmap: <pre><code>apiVersion: v1\ndata:\n  Content-Type: application/json\nkind: ConfigMap\nmetadata:\n  name: custom-headers-configmap\n</code></pre></p> <p>Attention</p> <p>First define the allowed response headers in global-allowed-response-headers.</p>"},{"location":"user-guide/nginx-configuration/annotations/#default-backend","title":"Default Backend","text":"<p>This annotation is of the form <code>nginx.ingress.kubernetes.io/default-backend: &lt;svc name&gt;</code> to specify a custom default backend.  This <code>&lt;svc name&gt;</code> is a reference to a service inside of the same namespace in which you are applying this annotation. This annotation overrides the global default backend. In case the service has multiple ports, the first one is the one which will receive the backend traffic. </p> <p>This service will be used to handle the response when the configured service in the Ingress rule does not have any active endpoints. It will also be used to handle the error responses if both this annotation and the custom-http-errors annotation are set.</p>"},{"location":"user-guide/nginx-configuration/annotations/#enable-cors","title":"Enable CORS","text":"<p>To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule, add the annotation <code>nginx.ingress.kubernetes.io/enable-cors: \"true\"</code>. This will add a section in the server location enabling this functionality.</p> <p>CORS can be controlled with the following annotations:</p> <ul> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-methods</code>: Controls which methods are accepted.</p> <p>This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).</p> <ul> <li>Default: <code>GET, PUT, POST, DELETE, PATCH, OPTIONS</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-headers</code>: Controls which headers are accepted.</p> <p>This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.</p> <ul> <li>Default: <code>DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-expose-headers</code>: Controls which headers are exposed to response.</p> <p>This is a multi-valued field, separated by ',' and accepts letters, numbers, _, - and *.</p> <ul> <li>Default: empty</li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-expose-headers: \"*, X-CustomResponseHeader\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-origin</code>: Controls what's the accepted Origin for CORS.</p> <p>This is a multi-valued field, separated by ','. It must follow this format: <code>http(s)://origin-site.com</code> or <code>http(s)://origin-site.com:port</code></p> <ul> <li>Default: <code>*</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443, http://origin-site.com, https://example.org:1199\"</code></li> </ul> <p>It also supports single level wildcard subdomains and follows this format: <code>http(s)://*.foo.bar</code>, <code>http(s)://*.bar.foo:8080</code> or <code>http(s)://*.abc.bar.foo:9000</code> - Example: <code>nginx.ingress.kubernetes.io/cors-allow-origin: \"https://*.origin-site.com:4443, http://*.origin-site.com, https://example.org:1199\"</code></p> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-credentials</code>: Controls if credentials can be passed during CORS operations.</p> <ul> <li>Default: <code>true</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-credentials: \"false\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-max-age</code>: Controls how long preflight requests can be cached.</p> <ul> <li>Default: <code>1728000</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-max-age: 600</code></li> </ul> </li> </ul> <p>Note</p> <p>For more information please see https://enable-cors.org</p>"},{"location":"user-guide/nginx-configuration/annotations/#http2-push-preload","title":"HTTP2 Push Preload.","text":"<p>Enables automatic conversion of preload links specified in the \u201cLink\u201d response header fields into push requests.</p> <p>Example</p> <ul> <li><code>nginx.ingress.kubernetes.io/http2-push-preload: \"true\"</code></li> </ul>"},{"location":"user-guide/nginx-configuration/annotations/#server-alias","title":"Server Alias","text":"<p>Allows the definition of one or more aliases in the server definition of the NGINX configuration using the annotation <code>nginx.ingress.kubernetes.io/server-alias: \"&lt;alias 1&gt;,&lt;alias 2&gt;\"</code>. This will create a server with the same configuration, but adding new values to the <code>server_name</code> directive.</p> <p>Note</p> <p>A server-alias name cannot conflict with the hostname of an existing server. If it does, the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created, the new server configuration will take place over the alias configuration.</p> <p>For more information please see the <code>server_name</code> documentation.</p>"},{"location":"user-guide/nginx-configuration/annotations/#server-snippet","title":"Server snippet","text":"<p>Using the annotation <code>nginx.ingress.kubernetes.io/server-snippet</code> it is possible to add custom configuration in the server configuration block.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/server-snippet: |\n        set $agentflag 0;\n\n        if ($http_user_agent ~* \"(Mobile)\" ){\n          set $agentflag 1;\n        }\n\n        if ( $agentflag = 1 ) {\n          return 301 https://m.example.com;\n        }\n</code></pre> <p>Attention</p> <p>This annotation can be used only once per host.</p>"},{"location":"user-guide/nginx-configuration/annotations/#client-body-buffer-size","title":"Client Body Buffer Size","text":"<p>Sets buffer size for reading client request body per location. In case the request body is larger than the buffer, the whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages. This is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is applied to each location provided in the ingress rule.</p> <p>Note</p> <p>The annotation value must be given in a format understood by Nginx.</p> <p>Example</p> <ul> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\"</code> # 1000 bytes</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1k</code> # 1 kilobyte</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1K</code> # 1 kilobyte</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1m</code> # 1 megabyte</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1M</code> # 1 megabyte</li> </ul> <p>For more information please see https://nginx.org</p>"},{"location":"user-guide/nginx-configuration/annotations/#external-authentication","title":"External Authentication","text":"<p>To use an existing service that provides authentication the Ingress rule can be annotated with <code>nginx.ingress.kubernetes.io/auth-url</code> to indicate the URL where the HTTP request should be sent.</p> <pre><code>nginx.ingress.kubernetes.io/auth-url: \"URL to the authentication service\"\n</code></pre> <p>Additionally it is possible to set:</p> <ul> <li><code>nginx.ingress.kubernetes.io/auth-keepalive</code>:   <code>&lt;Connections&gt;</code> to specify the maximum number of keepalive connections to <code>auth-url</code>. Only takes effect    when no variables are used in the host part of the URL. Defaults to <code>0</code> (keepalive disabled).</li> </ul> <p>Note: does not work with HTTP/2 listener because of a limitation in Lua subrequests. UseHTTP2 configuration should be disabled!</p> <ul> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-share-vars</code>:   Whether to share Nginx variables among the current request and the auth request. Example use case is to track requests: when set to \"true\" X-Request-ID HTTP header will be the same for the backend and the auth request.   Defaults to \"false\".</li> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-requests</code>:   <code>&lt;Requests&gt;</code> to specify the maximum number of requests that can be served through one keepalive connection.   Defaults to <code>1000</code> and only applied if <code>auth-keepalive</code> is set to higher than <code>0</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-timeout</code>:   <code>&lt;Timeout&gt;</code> to specify a duration in seconds which an idle keepalive connection to an upstream server will stay open.   Defaults to <code>60</code> and only applied if <code>auth-keepalive</code> is set to higher than <code>0</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-method</code>:   <code>&lt;Method&gt;</code> to specify the HTTP method to use.</li> <li><code>nginx.ingress.kubernetes.io/auth-signin</code>:   <code>&lt;SignIn_URL&gt;</code> to specify the location of the error page.</li> <li><code>nginx.ingress.kubernetes.io/auth-signin-redirect-param</code>:   <code>&lt;SignIn_URL&gt;</code> to specify the URL parameter in the error page which should contain the original URL for a failed signin request.</li> <li><code>nginx.ingress.kubernetes.io/auth-response-headers</code>:   <code>&lt;Response_Header_1, ..., Response_Header_n&gt;</code> to specify headers to pass to backend once authentication request completes.</li> <li><code>nginx.ingress.kubernetes.io/auth-proxy-set-headers</code>:   <code>&lt;ConfigMap&gt;</code> the name of a ConfigMap that specifies headers to pass to the authentication service</li> <li><code>nginx.ingress.kubernetes.io/auth-request-redirect</code>:   <code>&lt;Request_Redirect_URL&gt;</code>  to specify the X-Auth-Request-Redirect header value.</li> <li><code>nginx.ingress.kubernetes.io/auth-cache-key</code>:   <code>&lt;Cache_Key&gt;</code> this enables caching for auth requests. specify a lookup key for auth responses. e.g. <code>$remote_user$http_authorization</code>. Each server and location has it's own keyspace. Hence a cached response is only valid on a per-server and per-location basis.</li> <li><code>nginx.ingress.kubernetes.io/auth-cache-duration</code>:   <code>&lt;Cache_duration&gt;</code> to specify a caching time for auth responses based on their response codes, e.g. <code>200 202 30m</code>. See proxy_cache_valid for details. You may specify multiple, comma-separated values: <code>200 202 10m, 401 5m</code>. defaults to <code>200 202 401 5m</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-always-set-cookie</code>:   <code>&lt;Boolean_Flag&gt;</code> to set a cookie returned by auth request. By default, the cookie will be set only if an upstream reports with the code 200, 201, 204, 206, 301, 302, 303, 304, 307, or 308.</li> <li><code>nginx.ingress.kubernetes.io/auth-snippet</code>:   <code>&lt;Auth_Snippet&gt;</code> to specify a custom snippet to use with external authentication, e.g.</li> </ul> <pre><code>nginx.ingress.kubernetes.io/auth-url: http://foo.com/external-auth\nnginx.ingress.kubernetes.io/auth-snippet: |\n    proxy_set_header Foo-Header 42;\n</code></pre> <p>Note: <code>nginx.ingress.kubernetes.io/auth-snippet</code> is an optional annotation. However, it may only be used in conjunction with <code>nginx.ingress.kubernetes.io/auth-url</code> and will be ignored if <code>nginx.ingress.kubernetes.io/auth-url</code> is not set</p> <p>Example</p> <p>Please check the external-auth example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#global-external-authentication","title":"Global External Authentication","text":"<p>By default the controller redirects all requests to an existing service that provides authentication if <code>global-auth-url</code> is set in the NGINX ConfigMap. If you want to disable this behavior for that ingress, you can use <code>enable-global-auth: \"false\"</code> in the NGINX ConfigMap. <code>nginx.ingress.kubernetes.io/enable-global-auth</code>:    indicates if GlobalExternalAuth configuration should be applied or not to this Ingress rule. Default values is set to <code>\"true\"</code>.</p> <p>Note</p> <p>For more information please see global-auth-url.</p>"},{"location":"user-guide/nginx-configuration/annotations/#rate-limiting","title":"Rate Limiting","text":"<p>These annotations define limits on connections and transmission rates.  These can be used to mitigate DDoS Attacks.</p> <ul> <li><code>nginx.ingress.kubernetes.io/limit-connections</code>: number of concurrent connections allowed from a single IP address. A 503 error is returned when exceeding this limit.</li> <li><code>nginx.ingress.kubernetes.io/limit-rps</code>: number of requests accepted from a given IP each second. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit,  limit-req-status-code default: 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rpm</code>: number of requests accepted from a given IP each minute. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit,  limit-req-status-code default: 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-burst-multiplier</code>: multiplier of the limit rate for burst size. The default burst multiplier is 5, this annotation override the default multiplier. When clients exceed this limit,  limit-req-status-code default: 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate-after</code>: initial number of kilobytes after which the further transmission of a response to a given connection will be rate limited. This feature must be used with proxy-buffering enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate</code>: number of kilobytes per second allowed to send to a given connection.  The zero value disables rate limiting. This feature must be used with proxy-buffering enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-whitelist</code>: client IP source ranges to be excluded from rate-limiting. The value is a comma separated list of CIDRs.</li> </ul> <p>If you specify multiple annotations in a single Ingress rule, limits are applied in the order <code>limit-connections</code>, <code>limit-rpm</code>, <code>limit-rps</code>.</p> <p>To configure settings globally for all Ingress rules, the <code>limit-rate-after</code> and <code>limit-rate</code> values may be set in the NGINX ConfigMap.  The value set in an Ingress annotation will override the global setting.</p> <p>The client IP address will be set based on the use of PROXY protocol or from the <code>X-Forwarded-For</code> header value when use-forwarded-headers is enabled.</p>"},{"location":"user-guide/nginx-configuration/annotations/#global-rate-limiting","title":"Global Rate Limiting","text":"<p>Note: Be careful when configuring both (Local) Rate Limiting and Global Rate Limiting at the same time. They are two completely different rate limiting implementations. Whichever limit exceeds first will reject the requests. It might be a good idea to configure both of them to ease load on Global Rate Limiting backend in cases of spike in traffic.</p> <p>The stock NGINX rate limiting does not share its counters among different NGINX instances. Given that most ingress-nginx deployments are elastic and number of replicas can change any day it is impossible to configure a proper rate limit using stock NGINX functionalities. Global Rate Limiting overcome this by using lua-resty-global-throttle. <code>lua-resty-global-throttle</code> shares its counters via a central store such as <code>memcached</code>. The obvious shortcoming of this is users have to deploy and operate a <code>memcached</code> instance in order to benefit from this functionality. Configure the <code>memcached</code> using these configmap settings.</p> <p>Here are a few remarks for ingress-nginx integration of <code>lua-resty-global-throttle</code>:</p> <ol> <li>We minimize <code>memcached</code> access by caching exceeding limit decisions. The expiry of cache entry is the desired delay <code>lua-resty-global-throttle</code> calculates for us. The Lua Shared Dictionary used for that is <code>global_throttle_cache</code>. Currently its size defaults to 10M. Customize it as per your needs using lua-shared-dicts. When we fail to cache the exceeding limit decision then we log an NGINX error. You can monitor for that error to decide if you need to bump the cache size. Without cache the cost of processing a request is two memcached commands: <code>GET</code>, and <code>INCR</code>. With the cache it is only <code>INCR</code>.</li> <li>Log NGINX variable <code>$global_rate_limit_exceeding</code>'s value to have some visibility into what portion of requests are rejected (value <code>y</code>), whether they are rejected using cached decision (value <code>c</code>), or if they are not rejected (default value <code>n</code>). You can use log-format-upstream to include that in access logs.</li> <li>In case of an error it will log the error message and fail open.</li> <li> <p>The annotations below creates Global Rate Limiting instance per ingress. That means if there are multiple paths configured under the same ingress, the Global Rate Limiting will count requests to all the paths under the same counter. Extract a path out into its own ingress if you need to isolate a certain path.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/global-rate-limit</code>: Configures maximum allowed number of requests per window. Required.</p> </li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-window</code>: Configures a time window (i.e <code>1m</code>) that the limit is applied. Required.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-key</code>: Configures a key for counting the samples. Defaults to <code>$remote_addr</code>. You can also combine multiple NGINX variables here, like <code>${remote_addr}-${http_x_api_client}</code> which would mean the limit will be applied to requests coming from the same API client (indicated by <code>X-API-Client</code> HTTP request header) with the same source IP address.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs</code>: comma separated list of IPs and CIDRs to match client IP against. When there's a match request is not considered for rate limiting.</li> </ol>"},{"location":"user-guide/nginx-configuration/annotations/#permanent-redirect","title":"Permanent Redirect","text":"<p>This annotation allows to return a permanent redirect (Return Code 301) instead of sending data to the upstream.  For example <code>nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com</code> would redirect everything to Google.</p>"},{"location":"user-guide/nginx-configuration/annotations/#permanent-redirect-code","title":"Permanent Redirect Code","text":"<p>This annotation allows you to modify the status code used for permanent redirects.  For example <code>nginx.ingress.kubernetes.io/permanent-redirect-code: '308'</code> would return your permanent-redirect with a 308.</p>"},{"location":"user-guide/nginx-configuration/annotations/#temporal-redirect","title":"Temporal Redirect","text":"<p>This annotation allows you to return a temporal redirect (Return Code 302) instead of sending data to the upstream. For example <code>nginx.ingress.kubernetes.io/temporal-redirect: https://www.google.com</code> would redirect everything to Google with a Return Code of 302 (Moved Temporarily)</p>"},{"location":"user-guide/nginx-configuration/annotations/#ssl-passthrough","title":"SSL Passthrough","text":"<p>The annotation <code>nginx.ingress.kubernetes.io/ssl-passthrough</code> instructs the controller to send TLS connections directly to the backend instead of letting NGINX decrypt the communication. See also TLS/HTTPS in the User guide.</p> <p>Note</p> <p>SSL Passthrough is disabled by default and requires starting the controller with the <code>--enable-ssl-passthrough</code> flag.</p> <p>Attention</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>"},{"location":"user-guide/nginx-configuration/annotations/#service-upstream","title":"Service Upstream","text":"<p>By default the Ingress-Nginx Controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.</p> <p>The <code>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> <p>This can be desirable for things like zero-downtime deployments . See issue #257.</p>"},{"location":"user-guide/nginx-configuration/annotations/#known-issues","title":"Known Issues","text":"<p>If the <code>service-upstream</code> annotation is specified the following things should be taken into consideration:</p> <ul> <li>Sticky Sessions will not work as only round-robin load balancing is supported.</li> <li>The <code>proxy_next_upstream</code> directive will not have any effect meaning on error the request will not be dispatched to another upstream.</li> </ul>"},{"location":"user-guide/nginx-configuration/annotations/#server-side-https-enforcement-through-redirect","title":"Server-side HTTPS enforcement through redirect","text":"<p>By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress. If you want to disable this behavior globally, you can use <code>ssl-redirect: \"false\"</code> in the NGINX ConfigMap.</p> <p>To configure this feature for specific ingress resources, you can use the <code>nginx.ingress.kubernetes.io/ssl-redirect: \"false\"</code> annotation in the particular resource.</p> <p>When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is no TLS certificate available. This can be achieved by using the <code>nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"</code> annotation in the particular resource.</p> <p>To preserve the trailing slash in the URI with <code>ssl-redirect</code>, set <code>nginx.ingress.kubernetes.io/preserve-trailing-slash: \"true\"</code> annotation for that particular resource.</p>"},{"location":"user-guide/nginx-configuration/annotations/#redirect-fromto-www","title":"Redirect from/to www","text":"<p>In some scenarios is required to redirect from <code>www.domain.com</code> to <code>domain.com</code> or vice versa. To enable this feature use the annotation <code>nginx.ingress.kubernetes.io/from-to-www-redirect: \"true\"</code></p> <p>Attention</p> <p>If at some point a new Ingress is created with a host equal to one of the options (like <code>domain.com</code>) the annotation will be omitted.</p> <p>Attention</p> <p>For HTTPS to HTTPS redirects is mandatory the SSL Certificate defined in the Secret, located in the TLS section of Ingress, contains both FQDN in the common name of the certificate.</p>"},{"location":"user-guide/nginx-configuration/annotations/#denylist-source-range","title":"Denylist source range","text":"<p>You can specify blocked client IP source ranges through the <code>nginx.ingress.kubernetes.io/denylist-source-range</code> annotation. The value is a comma separated list of CIDRs, e.g.  <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>denylist-source-range</code> value may be set in the NGINX ConfigMap.</p> <p>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p>"},{"location":"user-guide/nginx-configuration/annotations/#whitelist-source-range","title":"Whitelist source range","text":"<p>You can specify allowed client IP source ranges through the <code>nginx.ingress.kubernetes.io/whitelist-source-range</code> annotation. The value is a comma separated list of CIDRs, e.g.  <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>whitelist-source-range</code> value may be set in the NGINX ConfigMap.</p> <p>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-timeouts","title":"Custom timeouts","text":"<p>Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers. In some scenarios is required to have different values. To allow this we provide annotations that allows this customization:</p> <ul> <li><code>nginx.ingress.kubernetes.io/proxy-connect-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-send-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-read-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-tries</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-request-buffering</code></li> </ul> <p>Note: All timeout values are unitless and in seconds e.g. <code>nginx.ingress.kubernetes.io/proxy-read-timeout: \"120\"</code> sets a valid 120 seconds proxy read timeout.</p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-redirect","title":"Proxy redirect","text":"<p>The annotations <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> and <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code> will set the first and second parameters of NGINX's proxy_redirect directive respectively. It is possible to set the text that should be changed in the <code>Location</code> and <code>Refresh</code> header fields of a proxied server response</p> <p>Setting \"off\" or \"default\" in the annotation <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> disables <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code>, otherwise, both annotations must be used in unison. Note that each annotation must be a string without spaces.</p> <p>By default the value of each annotation is \"off\".</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-max-body-size","title":"Custom max body size","text":"<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 <code>client_max_body_size</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-body-size</code> value may be set in the NGINX ConfigMap. To use custom values in an Ingress rule define these annotation:</p> <pre><code>nginx.ingress.kubernetes.io/proxy-body-size: 8m\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-cookie-domain","title":"Proxy cookie domain","text":"<p>Sets a text that should be changed in the domain attribute of the \"Set-Cookie\" header fields of a proxied server response.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-cookie-domain</code> value may be set in the NGINX ConfigMap.</p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-cookie-path","title":"Proxy cookie path","text":"<p>Sets a text that should be changed in the path attribute of the \"Set-Cookie\" header fields of a proxied server response.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-cookie-path</code> value may be set in the NGINX ConfigMap.</p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-buffering","title":"Proxy buffering","text":"<p>Enable or disable proxy buffering <code>proxy_buffering</code>. By default proxy buffering is disabled in the NGINX config.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-buffering</code> value may be set in the NGINX ConfigMap. To use custom values in an Ingress rule define these annotation:</p> <pre><code>nginx.ingress.kubernetes.io/proxy-buffering: \"on\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-buffers-number","title":"Proxy buffers Number","text":"<p>Sets the number of the buffers in <code>proxy_buffers</code> used for reading the first part of the response received from the proxied server. By default proxy buffers number is set as 4</p> <p>To configure this setting globally, set <code>proxy-buffers-number</code> in NGINX ConfigMap. To use custom values in an Ingress rule, define this annotation: <pre><code>nginx.ingress.kubernetes.io/proxy-buffers-number: \"4\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-buffer-size","title":"Proxy buffer size","text":"<p>Sets the size of the buffer <code>proxy_buffer_size</code> 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>proxy-buffer-size</code> in NGINX ConfigMap. To use custom values in an Ingress rule, define this annotation: <pre><code>nginx.ingress.kubernetes.io/proxy-buffer-size: \"8k\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-max-temp-file-size","title":"Proxy max temp file size","text":"<p>When <code>buffering</code> of responses from the proxied server is enabled, and the whole response does not fit into the buffers set by the <code>proxy_buffer_size</code> and <code>proxy_buffers</code> directives, a part of the response can be saved to a temporary file. This directive sets the maximum <code>size</code> of the temporary file setting the <code>proxy_max_temp_file_size</code>. The size of data written to the temporary file at a time is set by the <code>proxy_temp_file_write_size</code> directive.</p> <p>The zero value disables buffering of responses to temporary files.</p> <p>To use custom values in an Ingress rule, define this annotation: <pre><code>nginx.ingress.kubernetes.io/proxy-max-temp-file-size: \"1024m\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-http-version","title":"Proxy HTTP version","text":"<p>Using this annotation sets the <code>proxy_http_version</code> that the Nginx reverse proxy will use to communicate with the backend. By default this is set to \"1.1\".</p> <pre><code>nginx.ingress.kubernetes.io/proxy-http-version: \"1.0\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#ssl-ciphers","title":"SSL ciphers","text":"<p>Specifies the enabled ciphers.</p> <p>Using this annotation will set the <code>ssl_ciphers</code> directive at the server level. This configuration is active for all the paths in the host.</p> <pre><code>nginx.ingress.kubernetes.io/ssl-ciphers: \"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP\"\n</code></pre> <p>The following annotation will set the <code>ssl_prefer_server_ciphers</code> directive at the server level. This configuration specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols.</p> <pre><code>nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#connection-proxy-header","title":"Connection proxy header","text":"<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> <pre><code>nginx.ingress.kubernetes.io/connection-proxy-header: \"keep-alive\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#enable-access-log","title":"Enable Access Log","text":"<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> <pre><code>nginx.ingress.kubernetes.io/enable-access-log: \"false\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#enable-rewrite-log","title":"Enable Rewrite Log","text":"<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> <pre><code>nginx.ingress.kubernetes.io/enable-rewrite-log: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#enable-opentelemetry","title":"Enable Opentelemetry","text":"<p>Opentelemetry can be enabled or disabled globally through the ConfigMap but this will sometimes need to be overridden to enable it or disable it for a specific ingress (e.g. to turn off telemetry of external health check endpoints)</p> <pre><code>nginx.ingress.kubernetes.io/enable-opentelemetry: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#opentelemetry-trust-incoming-span","title":"Opentelemetry Trust Incoming Span","text":"<p>The option to trust incoming trace spans can be enabled or disabled globally through the ConfigMap but this will sometimes need to be overridden to enable it or disable it for a specific ingress (e.g. only enable on a private endpoint)</p> <pre><code>nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-spans: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#x-forwarded-prefix-header","title":"X-Forwarded-Prefix Header","text":"<p>To add the non-standard <code>X-Forwarded-Prefix</code> header to the upstream request with a string value, the following annotation can be used:</p> <pre><code>nginx.ingress.kubernetes.io/x-forwarded-prefix: \"/path\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#modsecurity","title":"ModSecurity","text":"<p>ModSecurity is an OpenSource Web Application firewall. It can be enabled for a particular set of ingress locations. The ModSecurity module must first be enabled by enabling ModSecurity in the ConfigMap. Note this will enable ModSecurity for all paths, and each path must be disabled manually.</p> <p>It can be enabled using the following annotation: <pre><code>nginx.ingress.kubernetes.io/enable-modsecurity: \"true\"\n</code></pre> ModSecurity will run in \"Detection-Only\" mode using the recommended configuration.</p> <p>You can enable the OWASP Core Rule Set by setting the following annotation: <pre><code>nginx.ingress.kubernetes.io/enable-owasp-core-rules: \"true\"\n</code></pre></p> <p>You can pass transactionIDs from nginx by setting up the following: <pre><code>nginx.ingress.kubernetes.io/modsecurity-transaction-id: \"$request_id\"\n</code></pre></p> <p>You can also add your own set of modsecurity rules via a snippet: <pre><code>nginx.ingress.kubernetes.io/modsecurity-snippet: |\nSecRuleEngine On\nSecDebugLog /tmp/modsec_debug.log\n</code></pre></p> <p>Note: If you use both <code>enable-owasp-core-rules</code> and <code>modsecurity-snippet</code> annotations together, only the <code>modsecurity-snippet</code> will take effect. If you wish to include the OWASP Core Rule Set or recommended configuration simply use the include statement:</p> <p>nginx 0.24.1 and below <pre><code>nginx.ingress.kubernetes.io/modsecurity-snippet: |\nInclude /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf\nInclude /etc/nginx/modsecurity/modsecurity.conf\n</code></pre> nginx 0.25.0 and above <pre><code>nginx.ingress.kubernetes.io/modsecurity-snippet: |\nInclude /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#backend-protocol","title":"Backend Protocol","text":"<p>Using <code>backend-protocol</code> annotations is possible to indicate how NGINX should communicate with the backend service. (Replaces <code>secure-backends</code> in older versions) Valid Values: HTTP, HTTPS, AUTO_HTTP, GRPC, GRPCS and FCGI</p> <p>By default NGINX uses <code>HTTP</code>.</p> <p>Example:</p> <pre><code>nginx.ingress.kubernetes.io/backend-protocol: \"HTTPS\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#use-regex","title":"Use Regex","text":"<p>Attention</p> <p>When using this annotation with the NGINX annotation <code>nginx.ingress.kubernetes.io/affinity</code> of type <code>cookie</code>,  <code>nginx.ingress.kubernetes.io/session-cookie-path</code> must be also set; Session cookie paths do not support regex.</p> <p>Using the <code>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>false</code>.</p> <p>The following will indicate that regular expression paths are being used: <pre><code>nginx.ingress.kubernetes.io/use-regex: \"true\"\n</code></pre></p> <p>The following will indicate that regular expression paths are not being used: <pre><code>nginx.ingress.kubernetes.io/use-regex: \"false\"\n</code></pre></p> <p>When this annotation is set to <code>true</code>, the case insensitive regular expression location modifier will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p> <p>Additionally, if the <code>rewrite-target</code> annotation is used on any Ingress for a given host, then the case insensitive regular expression location modifier will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p> <p>Please read about ingress path matching before using this modifier.</p>"},{"location":"user-guide/nginx-configuration/annotations/#satisfy","title":"Satisfy","text":"<p>By default, a request would need to satisfy all authentication requirements in order to be allowed. By using this annotation, requests that satisfy either any or all authentication requirements are allowed, based on the configuration value.</p> <pre><code>nginx.ingress.kubernetes.io/satisfy: \"any\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#mirror","title":"Mirror","text":"<p>Enables a request to be mirrored to a mirror backend. Responses by mirror backends are ignored. This feature is useful, to see how requests will react in \"test\" backends.</p> <p>The mirror backend can be set by applying:</p> <pre><code>nginx.ingress.kubernetes.io/mirror-target: https://test.env.com/$request_uri\n</code></pre> <p>By default the request-body is sent to the mirror backend, but can be turned off by applying:</p> <pre><code>nginx.ingress.kubernetes.io/mirror-request-body: \"off\"\n</code></pre> <p>Also by default header Host for mirrored requests will be set the same as a host part of uri in the \"mirror-target\" annotation. You can override it by \"mirror-host\" annotation:</p> <pre><code>nginx.ingress.kubernetes.io/mirror-target: https://1.2.3.4/$request_uri\nnginx.ingress.kubernetes.io/mirror-host: \"test.env.com\"\n</code></pre> <p>Note: The mirror directive will be applied to all paths within the ingress resource.</p> <p>The request sent to the mirror is linked to the original request. If you have a slow mirror backend, then the original request will throttle.</p> <p>For more information on the mirror module see ngx_http_mirror_module</p>"},{"location":"user-guide/nginx-configuration/annotations/#stream-snippet","title":"Stream snippet","text":"<p>Using the annotation <code>nginx.ingress.kubernetes.io/stream-snippet</code> it is possible to add custom stream configuration.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/stream-snippet: |\n      server {\n        listen 8000;\n        proxy_pass 127.0.0.1:80;\n      }\n</code></pre>"},{"location":"user-guide/nginx-configuration/configmap/","title":"ConfigMaps","text":"<p>ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable.</p> <p>The ConfigMap API resource stores configuration data as key-value pairs. The data provides the configurations for system components for the nginx-controller.</p> <p>In order to overwrite nginx-controller configuration values as seen in config.go, you can add key-value pairs to the data section of the config-map. For Example:</p> <pre><code>data:\n  map-hash-bucket-size: \"128\"\n  ssl-protocols: SSLv2\n</code></pre> <p>Important</p> <p>The key and values in a ConfigMap can only be strings. This means that we want a value with boolean values we need to quote the values, like \"true\" or \"false\". Same for numbers, like \"100\".</p> <p>\"Slice\" types (defined below as <code>[]string</code> or <code>[]int</code>) can be provided as a comma-delimited string.</p>"},{"location":"user-guide/nginx-configuration/configmap/#configuration-options","title":"Configuration options","text":"<p>The following table shows a configuration option's name, type, and the default value:</p> name type default notes add-headers string \"\" allow-backend-server-header bool \"false\" allow-cross-namespace-resources bool \"true\" allow-snippet-annotations bool false annotations-risk-level string Critical annotation-value-word-blocklist string array \"\" hide-headers string array empty access-log-params string \"\" access-log-path string \"/var/log/nginx/access.log\" http-access-log-path string \"\" stream-access-log-path string \"\" enable-access-log-for-default-backend bool \"false\" error-log-path string \"/var/log/nginx/error.log\" enable-modsecurity bool \"false\" modsecurity-snippet string \"\" enable-owasp-modsecurity-crs bool \"false\" client-header-buffer-size string \"1k\" client-header-timeout int 60 client-body-buffer-size string \"8k\" client-body-timeout int 60 disable-access-log bool false disable-ipv6 bool false disable-ipv6-dns bool false enable-underscores-in-headers bool false enable-ocsp bool false ignore-invalid-headers bool true retry-non-idempotent bool \"false\" error-log-level string \"notice\" http2-max-field-size string \"\" DEPRECATED in favour of large_client_header_buffers http2-max-header-size string \"\" DEPRECATED in favour of large_client_header_buffers http2-max-requests int 0 DEPRECATED in favour of keepalive_requests http2-max-concurrent-streams int 128 hsts bool \"true\" hsts-include-subdomains bool \"true\" hsts-max-age string \"31536000\" hsts-preload bool \"false\" keep-alive int 75 keep-alive-requests int 1000 large-client-header-buffers string \"4 8k\" log-format-escape-none bool \"false\" log-format-escape-json bool \"false\" log-format-upstream string <code>$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id</code> log-format-stream string <code>[$remote_addr] [$time_local] $protocol $status $bytes_sent $bytes_received $session_time</code> enable-multi-accept bool \"true\" max-worker-connections int 16384 max-worker-open-files int 0 map-hash-bucket-size int 64 nginx-status-ipv4-whitelist []string \"127.0.0.1\" nginx-status-ipv6-whitelist []string \"::1\" proxy-real-ip-cidr []string \"0.0.0.0/0\" proxy-set-headers string \"\" server-name-hash-max-size int 1024 server-name-hash-bucket-size int <code>&lt;size of the processor\u2019s cache line&gt;</code> proxy-headers-hash-max-size int 512 proxy-headers-hash-bucket-size int 64 plugins []string reuse-port bool \"true\" server-tokens bool \"false\" ssl-ciphers string \"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384\" ssl-ecdh-curve string \"auto\" ssl-dh-param string \"\" ssl-protocols string \"TLSv1.2 TLSv1.3\" ssl-session-cache bool \"true\" ssl-session-cache-size string \"10m\" ssl-session-tickets bool \"false\" ssl-session-ticket-key string <code>&lt;Randomly Generated&gt;</code> ssl-session-timeout string \"10m\" ssl-buffer-size string \"4k\" use-proxy-protocol bool \"false\" proxy-protocol-header-timeout string \"5s\" enable-aio-write bool \"true\" use-gzip bool \"false\" use-geoip bool \"true\" use-geoip2 bool \"false\" geoip2-autoreload-in-minutes int \"0\" enable-brotli bool \"false\" brotli-level int 4 brotli-min-length int 20 brotli-types string \"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component\" use-http2 bool \"true\" gzip-disable string \"\" gzip-level int 1 gzip-min-length int 256 gzip-types string \"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component\" worker-processes string <code>&lt;Number of CPUs&gt;</code> worker-cpu-affinity string \"\" worker-shutdown-timeout string \"240s\" enable-serial-reloads bool \"false\" load-balance string \"round_robin\" variables-hash-bucket-size int 128 variables-hash-max-size int 2048 upstream-keepalive-connections int 320 upstream-keepalive-time string \"1h\" upstream-keepalive-timeout int 60 upstream-keepalive-requests int 10000 limit-conn-zone-variable string \"$binary_remote_addr\" proxy-stream-timeout string \"600s\" proxy-stream-next-upstream bool \"true\" proxy-stream-next-upstream-timeout string \"600s\" proxy-stream-next-upstream-tries int 3 proxy-stream-responses int 1 bind-address []string \"\" use-forwarded-headers bool \"false\" enable-real-ip bool \"false\" forwarded-for-header string \"X-Forwarded-For\" compute-full-forwarded-for bool \"false\" proxy-add-original-uri-header bool \"false\" generate-request-id bool \"true\" jaeger-collector-host string \"\" jaeger-collector-port int 6831 jaeger-endpoint string \"\" jaeger-service-name string \"nginx\" jaeger-propagation-format string \"jaeger\" jaeger-sampler-type string \"const\" jaeger-sampler-param string \"1\" jaeger-sampler-host string \"http://127.0.0.1\" jaeger-sampler-port int 5778 jaeger-trace-context-header-name string uber-trace-id jaeger-debug-header string uber-debug-id jaeger-baggage-header string jaeger-baggage jaeger-trace-baggage-header-prefix string uberctx- datadog-collector-host string \"\" datadog-collector-port int 8126 datadog-service-name string \"nginx\" datadog-environment string \"prod\" datadog-operation-name-override string \"nginx.handle\" datadog-priority-sampling bool \"true\" datadog-sample-rate float 1.0 enable-opentelemetry bool \"false\" opentelemetry-trust-incoming-span bool \"true\" opentelemetry-operation-name string \"\" opentelemetry-config string \"/etc/nginx/opentelemetry.toml\" otlp-collector-host string \"\" otlp-collector-port int 4317 otel-max-queuesize int otel-schedule-delay-millis int otel-max-export-batch-size int otel-service-name string \"nginx\" otel-sampler string \"AlwaysOff\" otel-sampler-parent-based bool \"false\" otel-sampler-ratio float 0.01 main-snippet string \"\" http-snippet string \"\" server-snippet string \"\" stream-snippet string \"\" location-snippet string \"\" custom-http-errors []int []int{} proxy-body-size string \"1m\" proxy-connect-timeout int 5 proxy-read-timeout int 60 proxy-send-timeout int 60 proxy-buffers-number int 4 proxy-buffer-size string \"4k\" proxy-cookie-path string \"off\" proxy-cookie-domain string \"off\" proxy-next-upstream string \"error timeout\" proxy-next-upstream-timeout int 0 proxy-next-upstream-tries int 3 proxy-redirect-from string \"off\" proxy-request-buffering string \"on\" ssl-redirect bool \"true\" force-ssl-redirect bool \"false\" denylist-source-range []string []string{} whitelist-source-range []string []string{} skip-access-log-urls []string []string{} limit-rate int 0 limit-rate-after int 0 lua-shared-dicts string \"\" http-redirect-code int 308 proxy-buffering string \"off\" limit-req-status-code int 503 limit-conn-status-code int 503 enable-syslog bool false syslog-host string \"\" syslog-port int 514 no-tls-redirect-locations string \"/.well-known/acme-challenge\" global-allowed-response-headers string \"\" global-auth-url string \"\" global-auth-method string \"\" global-auth-signin string \"\" global-auth-signin-redirect-param string \"rd\" global-auth-response-headers string \"\" global-auth-request-redirect string \"\" global-auth-snippet string \"\" global-auth-cache-key string \"\" global-auth-cache-duration string \"200 202 401 5m\" no-auth-locations string \"/.well-known/acme-challenge\" block-cidrs []string \"\" block-user-agents []string \"\" block-referers []string \"\" proxy-ssl-location-only bool \"false\" default-type string \"text/html\" global-rate-limit-memcached-host string \"\" global-rate-limit-memcached-port int 11211 global-rate-limit-memcached-connect-timeout int 50 global-rate-limit-memcached-max-idle-timeout int 10000 global-rate-limit-memcached-pool-size int 50 global-rate-limit-status-code int 429 service-upstream bool \"false\" ssl-reject-handshake bool \"false\" debug-connections []string \"127.0.0.1,1.1.1.1/24\" strict-validate-path-type bool \"false\" (v1.7.x) grpc-buffer-size-kb int 0"},{"location":"user-guide/nginx-configuration/configmap/#add-headers","title":"add-headers","text":"<p>Sets custom headers from named configmap before sending traffic to the client. See proxy-set-headers. example</p>"},{"location":"user-guide/nginx-configuration/configmap/#allow-backend-server-header","title":"allow-backend-server-header","text":"<p>Enables the return of the header Server from the backend instead of the generic nginx string. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#allow-cross-namespace-resources","title":"allow-cross-namespace-resources","text":"<p>Enables users to consume cross namespace resource on annotations, when was previously enabled . default: true</p> <p>Annotations that may be impacted with this change: * <code>auth-secret</code> * <code>auth-proxy-set-header</code> * <code>auth-tls-secret</code> * <code>fastcgi-params-configmap</code> * <code>proxy-ssl-secret</code></p> <p>This option will be defaulted to false in the next major release</p>"},{"location":"user-guide/nginx-configuration/configmap/#allow-snippet-annotations","title":"allow-snippet-annotations","text":"<p>Enables Ingress to parse and add -snippet annotations/directives created by the user. _**default:*_ <code>false</code></p> <p>Warning: We recommend enabling this option only if you TRUST users with permission to create Ingress objects, as this may allow a user to add restricted configurations to the final nginx.conf file</p> <p>This option will be defaulted to false in the next major release</p>"},{"location":"user-guide/nginx-configuration/configmap/#annotations-risk-level","title":"annotations-risk-level","text":"<p>Represents the risk accepted on an annotation. If the risk is, for instance <code>Medium</code>, annotations with risk High and Critical will not be accepted.</p> <p>Accepted values are <code>Critical</code>, <code>High</code>, <code>Medium</code> and <code>Low</code>.</p> <p>Defaults to <code>Critical</code> but will be changed to <code>High</code> on the next minor release</p>"},{"location":"user-guide/nginx-configuration/configmap/#annotation-value-word-blocklist","title":"annotation-value-word-blocklist","text":"<p>Contains a comma-separated value of chars/words that are well known of being used to abuse Ingress configuration and must be blocked. Related to CVE-2021-25742</p> <p>When an annotation is detected with a value that matches one of the blocked bad words, the whole Ingress won't be configured.</p> <p>default: <code>\"\"</code></p> <p>When doing this, the default blocklist is override, which means that the Ingress admin should add all the words that should be blocked, here is a suggested block list.</p> <p>suggested: <code>\"load_module,lua_package,_by_lua,location,root,proxy_pass,serviceaccount,{,},',\\\"\"</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#hide-headers","title":"hide-headers","text":"<p>Sets additional header that will not be passed from the upstream server to the client response. default: empty</p> <p>References: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header</p>"},{"location":"user-guide/nginx-configuration/configmap/#access-log-params","title":"access-log-params","text":"<p>Additional params for access_log. For example, buffer=16k, gzip, flush=1m</p> <p>References: https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#access-log-path","title":"access-log-path","text":"<p>Access log path for both http and stream context. Goes to <code>/var/log/nginx/access.log</code> by default.</p> <p>Note: the file <code>/var/log/nginx/access.log</code> is a symlink to <code>/dev/stdout</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#http-access-log-path","title":"http-access-log-path","text":"<p>Access log path for http context globally. default: \"\"</p> <p>Note: If not specified, the <code>access-log-path</code> will be used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#stream-access-log-path","title":"stream-access-log-path","text":"<p>Access log path for stream context globally. default: \"\"</p> <p>Note: If not specified, the <code>access-log-path</code> will be used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-access-log-for-default-backend","title":"enable-access-log-for-default-backend","text":"<p>Enables logging access to default backend. default: is disabled.</p>"},{"location":"user-guide/nginx-configuration/configmap/#error-log-path","title":"error-log-path","text":"<p>Error log path. Goes to <code>/var/log/nginx/error.log</code> by default.</p> <p>Note: the file <code>/var/log/nginx/error.log</code> is a symlink to <code>/dev/stderr</code></p> <p>References: https://nginx.org/en/docs/ngx_core_module.html#error_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-modsecurity","title":"enable-modsecurity","text":"<p>Enables the modsecurity module for NGINX. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-owasp-modsecurity-crs","title":"enable-owasp-modsecurity-crs","text":"<p>Enables the OWASP ModSecurity Core Rule Set (CRS). default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#modsecurity-snippet","title":"modsecurity-snippet","text":"<p>Adds custom rules to modsecurity section of nginx configuration</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-header-buffer-size","title":"client-header-buffer-size","text":"<p>Allows to configure a custom buffer size for reading client request header.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_buffer_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-header-timeout","title":"client-header-timeout","text":"<p>Defines a timeout for reading client request header, in seconds.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-body-buffer-size","title":"client-body-buffer-size","text":"<p>Sets buffer size for reading client request body.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-body-timeout","title":"client-body-timeout","text":"<p>Defines a timeout for reading client request body, in seconds.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#disable-access-log","title":"disable-access-log","text":"<p>Disables the Access Log from the entire Ingress Controller. default: <code>false</code></p> <p>References: https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#disable-ipv6","title":"disable-ipv6","text":"<p>Disable listening on IPV6. default: <code>false</code>; IPv6 listening is enabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#disable-ipv6-dns","title":"disable-ipv6-dns","text":"<p>Disable IPV6 for nginx DNS resolver. default: <code>false</code>; IPv6 resolving enabled.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-underscores-in-headers","title":"enable-underscores-in-headers","text":"<p>Enables underscores in header names. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-ocsp","title":"enable-ocsp","text":"<p>Enables Online Certificate Status Protocol stapling (OCSP) support. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#ignore-invalid-headers","title":"ignore-invalid-headers","text":"<p>Set if header fields with invalid names should be ignored. default: is enabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#retry-non-idempotent","title":"retry-non-idempotent","text":"<p>Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error in the upstream server. The previous behavior can be restored using the value \"true\".</p>"},{"location":"user-guide/nginx-configuration/configmap/#error-log-level","title":"error-log-level","text":"<p>Configures the logging level of errors. Log levels above are listed in the order of increasing severity.</p> <p>References: https://nginx.org/en/docs/ngx_core_module.html#error_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-field-size","title":"http2-max-field-size","text":"<p>Warning</p> <p>This feature was deprecated in 1.1.3 and will be removed in 1.3.0. Use large-client-header-buffers instead.</p> <p>Limits the maximum size of an HPACK-compressed request header field.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_field_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-header-size","title":"http2-max-header-size","text":"<p>Warning</p> <p>This feature was deprecated in 1.1.3 and will be removed in 1.3.0. Use large-client-header-buffers instead.</p> <p>Limits the maximum size of the entire request header list after HPACK decompression.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_header_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-requests","title":"http2-max-requests","text":"<p>Warning</p> <p>This feature was deprecated in 1.1.3 and will be removed in 1.3.0. Use upstream-keepalive-requests instead.</p> <p>Sets the maximum number of requests (including push requests) that can be served through one HTTP/2 connection, after which the next client request will lead to connection closing and the need of establishing a new connection.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_requests</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-concurrent-streams","title":"http2-max-concurrent-streams","text":"<p>Sets the maximum number of concurrent HTTP/2 streams in a connection.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_concurrent_streams</p>"},{"location":"user-guide/nginx-configuration/configmap/#hsts","title":"hsts","text":"<p>Enables or disables the header HSTS in servers running SSL. HTTP Strict Transport Security (often abbreviated as HSTS) is a security feature (HTTP header) that tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. It provides protection against protocol downgrade attacks and cookie theft.</p> <p>References:</p> <ul> <li>https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security</li> <li>https://blog.qualys.com/securitylabs/2016/03/28/the-importance-of-a-proper-http-strict-transport-security-implementation-on-your-web-server</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#hsts-include-subdomains","title":"hsts-include-subdomains","text":"<p>Enables or disables the use of HSTS in all the subdomains of the server-name.</p>"},{"location":"user-guide/nginx-configuration/configmap/#hsts-max-age","title":"hsts-max-age","text":"<p>Sets the time, in seconds, that the browser should remember that this site is only to be accessed using HTTPS.</p>"},{"location":"user-guide/nginx-configuration/configmap/#hsts-preload","title":"hsts-preload","text":"<p>Enables or disables the preload attribute in the HSTS feature (when it is enabled).</p>"},{"location":"user-guide/nginx-configuration/configmap/#keep-alive","title":"keep-alive","text":"<p>Sets the time, in seconds, during which a keep-alive client connection will stay open on the server side. The zero value disables keep-alive client connections.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout</p> <p>Important</p> <p>Setting <code>keep-alive: '0'</code> will most likely break concurrent http/2 requests due to changes introduced with nginx 1.19.7</p> <pre><code>Changes with nginx 1.19.7                                        16 Feb 2021\n\n    *) Change: connections handling in HTTP/2 has been changed to better\n       match HTTP/1.x; the \"http2_recv_timeout\", \"http2_idle_timeout\", and\n       \"http2_max_requests\" directives have been removed, the\n       \"keepalive_timeout\" and \"keepalive_requests\" directives should be\n       used instead.\n</code></pre> <p>References: nginx change log nginx issue tracker nginx mailing list</p>"},{"location":"user-guide/nginx-configuration/configmap/#keep-alive-requests","title":"keep-alive-requests","text":"<p>Sets the maximum number of requests that can be served through one keep-alive connection.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests</p>"},{"location":"user-guide/nginx-configuration/configmap/#large-client-header-buffers","title":"large-client-header-buffers","text":"<p>Sets the maximum number and size of buffers used for reading large client request header. default: 4 8k</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-escape-none","title":"log-format-escape-none","text":"<p>Sets if the escape parameter is disabled entirely for character escaping in variables (\"true\") or controlled by log-format-escape-json (\"false\") Sets the nginx log format.</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-escape-json","title":"log-format-escape-json","text":"<p>Sets if the escape parameter allows JSON (\"true\") or default characters escaping in variables (\"false\") Sets the nginx log format.</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-upstream","title":"log-format-upstream","text":"<p>Sets the nginx log format. Example for json output:</p> <pre><code>log-format-upstream: '{\"time\": \"$time_iso8601\", \"remote_addr\": \"$proxy_protocol_addr\", \"x_forwarded_for\": \"$proxy_add_x_forwarded_for\", \"request_id\": \"$req_id\",\n  \"remote_user\": \"$remote_user\", \"bytes_sent\": $bytes_sent, \"request_time\": $request_time, \"status\": $status, \"vhost\": \"$host\", \"request_proto\": \"$server_protocol\",\n  \"path\": \"$uri\", \"request_query\": \"$args\", \"request_length\": $request_length, \"duration\": $request_time,\"method\": \"$request_method\", \"http_referrer\": \"$http_referer\",\n  \"http_user_agent\": \"$http_user_agent\" }'\n</code></pre> <p>Please check the log-format for definition of each field.</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-stream","title":"log-format-stream","text":"<p>Sets the nginx stream format.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-multi-accept","title":"enable-multi-accept","text":"<p>If disabled, a worker process will accept one new connection at a time. Otherwise, a worker process will accept all new connections at a time. default: true</p> <p>References: https://nginx.org/en/docs/ngx_core_module.html#multi_accept</p>"},{"location":"user-guide/nginx-configuration/configmap/#max-worker-connections","title":"max-worker-connections","text":"<p>Sets the maximum number of simultaneous connections that can be opened by each worker process. 0 will use the value of max-worker-open-files. default: 16384</p> <p>Tip</p> <p>Using 0 in scenarios of high load improves performance at the cost of increasing RAM utilization (even on idle).</p>"},{"location":"user-guide/nginx-configuration/configmap/#max-worker-open-files","title":"max-worker-open-files","text":"<p>Sets the maximum number of files that can be opened by each worker process. The default of 0 means \"max open files (system's limit) - 1024\". default: 0</p>"},{"location":"user-guide/nginx-configuration/configmap/#map-hash-bucket-size","title":"map-hash-bucket-size","text":"<p>Sets the bucket size for the map variables hash tables. The details of setting up hash tables are provided in a separate document.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-real-ip-cidr","title":"proxy-real-ip-cidr","text":"<p>If <code>use-forwarded-headers</code> or <code>use-proxy-protocol</code> is enabled, <code>proxy-real-ip-cidr</code> defines the default IP/network address of your external load balancer. Can be a comma-separated list of CIDR blocks. default: \"0.0.0.0/0\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-set-headers","title":"proxy-set-headers","text":"<p>Sets custom headers from named configmap before sending traffic to backends. The value format is namespace/name.  See example</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-name-hash-max-size","title":"server-name-hash-max-size","text":"<p>Sets the maximum size of the server names hash tables used in server names,map directive\u2019s values, MIME types, names of request header strings, etc.</p> <p>References: https://nginx.org/en/docs/hash.html</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-name-hash-bucket-size","title":"server-name-hash-bucket-size","text":"<p>Sets the size of the bucket for the server names hash tables.</p> <p>References:</p> <ul> <li>https://nginx.org/en/docs/hash.html</li> <li>https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-headers-hash-max-size","title":"proxy-headers-hash-max-size","text":"<p>Sets the maximum size of the proxy headers hash tables.</p> <p>References:</p> <ul> <li>https://nginx.org/en/docs/hash.html</li> <li>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#reuse-port","title":"reuse-port","text":"<p>Instructs NGINX to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-headers-hash-bucket-size","title":"proxy-headers-hash-bucket-size","text":"<p>Sets the size of the bucket for the proxy headers hash tables.</p> <p>References:</p> <ul> <li>https://nginx.org/en/docs/hash.html</li> <li>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#plugins","title":"plugins","text":"<p>Activates plugins installed in <code>/etc/nginx/lua/plugins</code>. Refer to ingress-nginx plugins README for more information on how to write and install a plugin.</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-tokens","title":"server-tokens","text":"<p>Send NGINX Server header in responses and display NGINX version in error pages. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-ciphers","title":"ssl-ciphers","text":"<p>Sets the ciphers list to enable. The ciphers are specified in the format understood by the OpenSSL library.</p> <p>The default cipher list is:  <code>ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384</code>.</p> <p>The ordering of a ciphersuite is very important because it decides which algorithms are going to be selected in priority. The recommendation above prioritizes algorithms that provide perfect forward secrecy.</p> <p>DHE-based cyphers will not be available until DH parameter is configured Custom DH parameters for perfect forward secrecy</p> <p>Please check the Mozilla SSL Configuration Generator.</p> <p>Note: ssl_prefer_server_ciphers directive will be enabled by default for http context.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-ecdh-curve","title":"ssl-ecdh-curve","text":"<p>Specifies a curve for ECDHE ciphers.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-dh-param","title":"ssl-dh-param","text":"<p>Sets the name of the secret that contains Diffie-Hellman key to help with \"Perfect Forward Secrecy\".</p> <p>References:</p> <ul> <li>https://wiki.openssl.org/index.php/Diffie-Hellman_parameters</li> <li>https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam</li> <li>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-protocols","title":"ssl-protocols","text":"<p>Sets the SSL protocols to use. The default is: <code>TLSv1.2 TLSv1.3</code>.</p> <p>Please check the result of the configuration using <code>https://ssllabs.com/ssltest/analyze.html</code> or <code>https://testssl.sh</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-early-data","title":"ssl-early-data","text":"<p>Enables or disables TLS 1.3 early data, also known as Zero Round Trip Time Resumption (0-RTT).</p> <p>This requires <code>ssl-protocols</code> to have <code>TLSv1.3</code> enabled. Enable this with caution, because requests sent within early data are subject to replay attacks.</p> <p>ssl_early_data. The default is: <code>false</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-cache","title":"ssl-session-cache","text":"<p>Enables or disables the use of shared SSL cache among worker processes.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-cache-size","title":"ssl-session-cache-size","text":"<p>Sets the size of the SSL shared session cache between all worker processes.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-tickets","title":"ssl-session-tickets","text":"<p>Enables or disables session resumption through TLS session tickets.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-ticket-key","title":"ssl-session-ticket-key","text":"<p>Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string. To create a ticket: <code>openssl rand 80 | openssl enc -A -base64</code></p> <p>TLS session ticket-key, by default, a randomly generated key is used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-timeout","title":"ssl-session-timeout","text":"<p>Sets the time during which a client may reuse the session parameters stored in a cache.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-buffer-size","title":"ssl-buffer-size","text":"<p>Sets the size of the SSL buffer used for sending data. The default of 4k helps NGINX to improve TLS Time To First Byte (TTTFB).</p> <p>References: https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-proxy-protocol","title":"use-proxy-protocol","text":"<p>Enables or disables the PROXY protocol to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-protocol-header-timeout","title":"proxy-protocol-header-timeout","text":"<p>Sets the timeout value for receiving the proxy-protocol headers. The default of 5 seconds prevents the TLS passthrough handler from waiting indefinitely on a dropped connection. default: 5s</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-aio-write","title":"enable-aio-write","text":"<p>Enables or disables the directive aio_write that writes files asynchronously. default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-gzip","title":"use-gzip","text":"<p>Enables or disables compression of HTTP responses using the \"gzip\" module. MIME types to compress are controlled by gzip-types. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-geoip","title":"use-geoip","text":"<p>Enables or disables \"geoip\" module that creates variables with values depending on the client IP address, using the precompiled MaxMind databases. default: true</p> <p>Note: MaxMind legacy databases are discontinued and will not receive updates after 2019-01-02, cf. discontinuation notice. Consider use-geoip2 below.</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-geoip2","title":"use-geoip2","text":"<p>Enables the geoip2 module for NGINX. Since <code>0.27.0</code> and due to a change in the MaxMind databases a license is required to have access to the databases. For this reason, it is required to define a new flag <code>--maxmind-license-key</code> in the ingress controller deployment to download the databases needed during the initialization of the ingress controller. Alternatively, it is possible to use a volume to mount the files <code>/etc/ingress-controller/geoip/GeoLite2-City.mmdb</code> and <code>/etc/ingress-controller/geoip/GeoLite2-ASN.mmdb</code>, avoiding the overhead of the download.</p> <p>Important</p> <p>If the feature is enabled but the files are missing, GeoIP2 will not be enabled.</p> <p>default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#geoip2-autoreload-in-minutes","title":"geoip2-autoreload-in-minutes","text":"<p>Enables the geoip2 module autoreload in MaxMind databases setting the interval in minutes.</p> <p>default: 0</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-brotli","title":"enable-brotli","text":"<p>Enables or disables compression of HTTP responses using the \"brotli\" module. The default mime type list to compress is: <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>.  default: false</p> <p>Note: Brotli does not works in Safari &lt; 11. For more information see https://caniuse.com/#feat=brotli</p>"},{"location":"user-guide/nginx-configuration/configmap/#brotli-level","title":"brotli-level","text":"<p>Sets the Brotli Compression Level that will be used. default: 4</p>"},{"location":"user-guide/nginx-configuration/configmap/#brotli-min-length","title":"brotli-min-length","text":"<p>Minimum length of responses, in bytes, that will be eligible for brotli compression. default: 20</p>"},{"location":"user-guide/nginx-configuration/configmap/#brotli-types","title":"brotli-types","text":"<p>Sets the MIME Types that will be compressed on-the-fly by brotli. default: <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#use-http2","title":"use-http2","text":"<p>Enables or disables HTTP/2 support in secure connections.</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-disable","title":"gzip-disable","text":"<p>Disables gzipping of responses for requests with \"User-Agent\" header fields matching any of the specified regular expressions.</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-level","title":"gzip-level","text":"<p>Sets the gzip Compression Level that will be used. default: 1</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-min-length","title":"gzip-min-length","text":"<p>Minimum length of responses to be returned to the client before it is eligible for gzip compression, in bytes. default: 256</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-types","title":"gzip-types","text":"<p>Sets the MIME types in addition to \"text/html\" to compress. The special value \"*\" matches any MIME type. Responses with the \"text/html\" type are always compressed if <code>use-gzip</code> is enabled. default: <code>application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#worker-processes","title":"worker-processes","text":"<p>Sets the number of worker processes. The default of \"auto\" means number of available CPU cores.</p>"},{"location":"user-guide/nginx-configuration/configmap/#worker-cpu-affinity","title":"worker-cpu-affinity","text":"<p>Binds worker processes to the sets of CPUs. worker_cpu_affinity. By default worker processes are not bound to any specific CPUs. The value can be:</p> <ul> <li>\"\": empty string indicate no affinity is applied.</li> <li>cpumask: e.g. <code>0001 0010 0100 1000</code> to bind processes to specific cpus.</li> <li>auto: binding worker processes automatically to available CPUs.</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#worker-shutdown-timeout","title":"worker-shutdown-timeout","text":"<p>Sets a timeout for Nginx to wait for worker to gracefully shutdown. default: \"240s\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#load-balance","title":"load-balance","text":"<p>Sets the algorithm to use for load balancing. The value can either be:</p> <ul> <li>round_robin: to use the default round robin loadbalancer</li> <li>ewma: to use the Peak EWMA method for routing (implementation)</li> </ul> <p>The default is <code>round_robin</code>.</p> <ul> <li>To load balance using consistent hashing of IP or other variables, consider the <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> annotation.</li> <li>To load balance using session cookies, consider the <code>nginx.ingress.kubernetes.io/affinity</code> annotation.</li> </ul> <p>References: https://nginx.org/en/docs/http/load_balancing.html</p>"},{"location":"user-guide/nginx-configuration/configmap/#variables-hash-bucket-size","title":"variables-hash-bucket-size","text":"<p>Sets the bucket size for the variables hash table.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#variables-hash-max-size","title":"variables-hash-max-size","text":"<p>Sets the maximum size of the variables hash table.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-connections","title":"upstream-keepalive-connections","text":"<p>Activates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed. default: 320</p> <p>References: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-time","title":"upstream-keepalive-time","text":"<p>Sets the maximum time during which requests can be processed through one keepalive connection.  default: \"1h\"</p> <p>References: http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-timeout","title":"upstream-keepalive-timeout","text":"<p>Sets a timeout during which an idle keepalive connection to an upstream server will stay open.  default: 60</p> <p>References: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-requests","title":"upstream-keepalive-requests","text":"<p>Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of requests is made, the connection is closed. default: 10000</p> <p>References: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-conn-zone-variable","title":"limit-conn-zone-variable","text":"<p>Sets parameters for a shared memory zone that will keep states for various keys of limit_conn_zone. The default of \"$binary_remote_addr\" variable\u2019s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-timeout","title":"proxy-stream-timeout","text":"<p>Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-next-upstream","title":"proxy-stream-next-upstream","text":"<p>When a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-next-upstream-timeout","title":"proxy-stream-next-upstream-timeout","text":"<p>Limits the time allowed to pass a connection to the next server. The 0 value turns off this limitation.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-next-upstream-tries","title":"proxy-stream-next-upstream-tries","text":"<p>Limits the number of possible tries a request should be passed to the next server. The 0 value turns off this limitation.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_tries</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-responses","title":"proxy-stream-responses","text":"<p>Sets the number of datagrams expected from the proxied server in response to the client request if the UDP protocol is used.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses</p>"},{"location":"user-guide/nginx-configuration/configmap/#bind-address","title":"bind-address","text":"<p>Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-forwarded-headers","title":"use-forwarded-headers","text":"<p>If true, NGINX passes the incoming <code>X-Forwarded-*</code> headers to upstreams. Use this option when NGINX is behind another L7 proxy / load balancer that is setting these headers.</p> <p>If false, NGINX ignores incoming <code>X-Forwarded-*</code> headers, filling them with the request information it sees. Use this option if NGINX is exposed directly to the internet, or it's behind a L3/packet-based load balancer that doesn't alter the source IP in the packets.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-real-ip","title":"enable-real-ip","text":"<p><code>enable-real-ip</code> enables the configuration of https://nginx.org/en/docs/http/ngx_http_realip_module.html. Specific attributes of the module can be configured further by using <code>forwarded-for-header</code> and <code>proxy-real-ip-cidr</code> settings.</p>"},{"location":"user-guide/nginx-configuration/configmap/#forwarded-for-header","title":"forwarded-for-header","text":"<p>Sets the header field for identifying the originating IP address of a client. default: X-Forwarded-For</p>"},{"location":"user-guide/nginx-configuration/configmap/#compute-full-forwarded-for","title":"compute-full-forwarded-for","text":"<p>Append the remote address to the X-Forwarded-For header instead of replacing it. When this option is enabled, the upstream application is responsible for extracting the client IP based on its own list of trusted proxies.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-add-original-uri-header","title":"proxy-add-original-uri-header","text":"<p>Adds an X-Original-Uri header with the original request URI to the backend request</p>"},{"location":"user-guide/nginx-configuration/configmap/#generate-request-id","title":"generate-request-id","text":"<p>Ensures that X-Request-ID is defaulted to a random value, if no X-Request-ID is present in the request</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-collector-host","title":"jaeger-collector-host","text":"<p>Specifies the host to use when uploading traces. It must be a valid URL.</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-collector-port","title":"jaeger-collector-port","text":"<p>Specifies the port to use when uploading traces. default: 6831</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-endpoint","title":"jaeger-endpoint","text":"<p>Specifies the endpoint to use when uploading traces to a collector. This takes priority over <code>jaeger-collector-host</code> if both are specified.</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-service-name","title":"jaeger-service-name","text":"<p>Specifies the service name to use for any traces created. default: nginx</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-propagation-format","title":"jaeger-propagation-format","text":"<p>Specifies the traceparent/tracestate propagation format. default: jaeger</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-type","title":"jaeger-sampler-type","text":"<p>Specifies the sampler to be used when sampling traces. The available samplers are: const, probabilistic, ratelimiting, remote. default: const</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-param","title":"jaeger-sampler-param","text":"<p>Specifies the argument to be passed to the sampler constructor. Must be a number. For const this should be 0 to never sample and 1 to always sample. default: 1</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-host","title":"jaeger-sampler-host","text":"<p>Specifies the custom remote sampler host to be passed to the sampler constructor. Must be a valid URL. Leave blank to use default value (localhost). default: http://127.0.0.1</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-port","title":"jaeger-sampler-port","text":"<p>Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. default: 5778</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-trace-context-header-name","title":"jaeger-trace-context-header-name","text":"<p>Specifies the header name used for passing trace context. default: uber-trace-id</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-debug-header","title":"jaeger-debug-header","text":"<p>Specifies the header name used for force sampling. default: jaeger-debug-id</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-baggage-header","title":"jaeger-baggage-header","text":"<p>Specifies the header name used to submit baggage if there is no root span. default: jaeger-baggage</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-tracer-baggage-header-prefix","title":"jaeger-tracer-baggage-header-prefix","text":"<p>Specifies the header prefix used to propagate baggage. default: uberctx-</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-collector-host","title":"datadog-collector-host","text":"<p>Specifies the datadog agent host to use when uploading traces. It must be a valid URL.</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-collector-port","title":"datadog-collector-port","text":"<p>Specifies the port to use when uploading traces. default: 8126</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-service-name","title":"datadog-service-name","text":"<p>Specifies the service name to use for any traces created. default: nginx</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-environment","title":"datadog-environment","text":"<p>Specifies the environment this trace belongs to. default: prod</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-operation-name-override","title":"datadog-operation-name-override","text":"<p>Overrides the operation name to use for any traces crated. default: nginx.handle</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-priority-sampling","title":"datadog-priority-sampling","text":"<p>Specifies to use client-side sampling. If true disables client-side sampling (thus ignoring <code>sample_rate</code>) and enables distributed priority sampling, where traces are sampled based on a combination of user-assigned priorities and configuration from the agent. default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-sample-rate","title":"datadog-sample-rate","text":"<p>Specifies sample rate for any traces created. This is effective only when <code>datadog-priority-sampling</code> is <code>false</code> default: 1.0</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-opentelemetry","title":"enable-opentelemetry","text":"<p>Enables the nginx OpenTelemetry extension. default: is disabled</p> <p>References: https://github.com/open-telemetry/opentelemetry-cpp-contrib</p>"},{"location":"user-guide/nginx-configuration/configmap/#opentelemetry-operation-name","title":"opentelemetry-operation-name","text":"<p>Specifies a custom name for the server span. default: is empty</p> <p>For example, set to \"HTTP $request_method $uri\".</p>"},{"location":"user-guide/nginx-configuration/configmap/#otlp-collector-host","title":"otlp-collector-host","text":"<p>Specifies the host to use when uploading traces. It must be a valid URL.</p>"},{"location":"user-guide/nginx-configuration/configmap/#otlp-collector-port","title":"otlp-collector-port","text":"<p>Specifies the port to use when uploading traces. default: 4317</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-service-name","title":"otel-service-name","text":"<p>Specifies the service name to use for any traces created. default: nginx</p>"},{"location":"user-guide/nginx-configuration/configmap/#opentelemetry-trust-incoming-span-true","title":"opentelemetry-trust-incoming-span: \"true\"","text":"<p>Enables or disables using spans from incoming requests as parent for created ones. default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-sampler-parent-based","title":"otel-sampler-parent-based","text":"<p>Uses sampler implementation which by default will take a sample if parent Activity is sampled. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-sampler-ratio","title":"otel-sampler-ratio","text":"<p>Specifies sample rate for any traces created. default: 0.01</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-sampler","title":"otel-sampler","text":"<p>Specifies the sampler to be used when sampling traces. The available samplers are: AlwaysOff, AlwaysOn, TraceIdRatioBased, remote. default: AlwaysOff</p>"},{"location":"user-guide/nginx-configuration/configmap/#main-snippet","title":"main-snippet","text":"<p>Adds custom configuration to the main section of the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#http-snippet","title":"http-snippet","text":"<p>Adds custom configuration to the http section of the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-snippet","title":"server-snippet","text":"<p>Adds custom configuration to all the servers in the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#stream-snippet","title":"stream-snippet","text":"<p>Adds custom configuration to the stream section of the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#location-snippet","title":"location-snippet","text":"<p>Adds custom configuration to all the locations in the nginx configuration.</p> <p>You can not use this to add new locations that proxy to the Kubernetes pods, as the snippet does not have access to the Go template functions. If you want to add custom locations you will have to provide your own nginx.tmpl.</p>"},{"location":"user-guide/nginx-configuration/configmap/#custom-http-errors","title":"custom-http-errors","text":"<p>Enables which HTTP codes should be passed for processing with the error_page directive</p> <p>Setting at least one code also enables proxy_intercept_errors which are required to process error_page.</p> <p>Example usage: <code>custom-http-errors: 404,415</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-body-size","title":"proxy-body-size","text":"<p>Sets the maximum allowed size of the client request body. See NGINX client_max_body_size.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-connect-timeout","title":"proxy-connect-timeout","text":"<p>Sets the timeout for establishing a connection with a proxied server. It should be noted that this timeout cannot usually exceed 75 seconds.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-read-timeout","title":"proxy-read-timeout","text":"<p>Sets the timeout in seconds for reading a response from the proxied server. The timeout is set only between two successive read operations, not for the transmission of the whole response.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-send-timeout","title":"proxy-send-timeout","text":"<p>Sets the timeout in seconds for transmitting a request to the proxied server. The timeout is set only between two successive write operations, not for the transmission of the whole request.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-buffers-number","title":"proxy-buffers-number","text":"<p>Sets the number of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-buffer-size","title":"proxy-buffer-size","text":"<p>Sets the size of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-cookie-path","title":"proxy-cookie-path","text":"<p>Sets a text that should be changed in the path attribute of the \u201cSet-Cookie\u201d header fields of a proxied server response.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-cookie-domain","title":"proxy-cookie-domain","text":"<p>Sets a text that should be changed in the domain attribute of the \u201cSet-Cookie\u201d header fields of a proxied server response.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-next-upstream","title":"proxy-next-upstream","text":"<p>Specifies in which cases a request should be passed to the next server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-next-upstream-timeout","title":"proxy-next-upstream-timeout","text":"<p>Limits the time in seconds during which a request can be passed to the next server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-next-upstream-tries","title":"proxy-next-upstream-tries","text":"<p>Limit the number of possible tries a request should be passed to the next server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-redirect-from","title":"proxy-redirect-from","text":"<p>Sets the original text that should be changed in the \"Location\" and \"Refresh\" header fields of a proxied server response. default: off</p> <p>References: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-request-buffering","title":"proxy-request-buffering","text":"<p>Enables or disables buffering of a client request body.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-redirect","title":"ssl-redirect","text":"<p>Sets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule). default: \"true\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#force-ssl-redirect","title":"force-ssl-redirect","text":"<p>Sets the global value of redirects (308) to HTTPS if the server has a default TLS certificate (defined in extra-args). default: \"false\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#denylist-source-range","title":"denylist-source-range","text":"<p>Sets the default denylisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See ngx_http_access_module.</p>"},{"location":"user-guide/nginx-configuration/configmap/#whitelist-source-range","title":"whitelist-source-range","text":"<p>Sets the default whitelisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See ngx_http_access_module.</p>"},{"location":"user-guide/nginx-configuration/configmap/#skip-access-log-urls","title":"skip-access-log-urls","text":"<p>Sets a list of URLs that should not appear in the NGINX access log. This is useful with urls like <code>/health</code> or <code>health-check</code> that make \"complex\" reading the logs. default: is empty</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-rate","title":"limit-rate","text":"<p>Limits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-rate-after","title":"limit-rate-after","text":"<p>Sets the initial amount after which the further transmission of a response to a client will be rate limited.</p>"},{"location":"user-guide/nginx-configuration/configmap/#lua-shared-dicts","title":"lua-shared-dicts","text":"<p>Customize default Lua shared dictionaries or define more. You can use the following syntax to do so:</p> <pre><code>lua-shared-dicts: \"&lt;my dict name&gt;: &lt;my dict size&gt;, [&lt;my dict name&gt;: &lt;my dict size&gt;], ...\"\n</code></pre> <p>For example following will set default <code>certificate_data</code> dictionary to <code>100M</code> and will introduce a new dictionary called <code>my_custom_plugin</code>:</p> <pre><code>lua-shared-dicts: \"certificate_data: 100, my_custom_plugin: 5\"\n</code></pre> <p>You can optionally set a size unit to allow for kilobyte-granularity. Allowed units are 'm' or 'k' (case-insensitive), and it defaults to MB if no unit is provided. Here is a similar example, but the <code>my_custom_plugin</code> dict is only 512KB.</p> <pre><code>lua-shared-dicts: \"certificate_data: 100, my_custom_plugin: 512k\"\n</code></pre> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after</p>"},{"location":"user-guide/nginx-configuration/configmap/#http-redirect-code","title":"http-redirect-code","text":"<p>Sets the HTTP status code to be used in redirects. Supported codes are 301,302,307 and 308 default: 308</p> <p>Why the default code is 308?</p> <p>RFC 7238 was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if we send a redirect in methods like POST.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-buffering","title":"proxy-buffering","text":"<p>Enables or disables buffering of responses from the proxied server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-req-status-code","title":"limit-req-status-code","text":"<p>Sets the status code to return in response to rejected requests. default: 503</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-conn-status-code","title":"limit-conn-status-code","text":"<p>Sets the status code to return in response to rejected connections. default: 503</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-syslog","title":"enable-syslog","text":"<p>Enable syslog feature for access log and error log. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#syslog-host","title":"syslog-host","text":"<p>Sets the address of syslog server. The address can be specified as a domain name or IP address.</p>"},{"location":"user-guide/nginx-configuration/configmap/#syslog-port","title":"syslog-port","text":"<p>Sets the port of syslog server. default: 514</p>"},{"location":"user-guide/nginx-configuration/configmap/#no-tls-redirect-locations","title":"no-tls-redirect-locations","text":"<p>A comma-separated list of locations on which http requests will never get redirected to their https counterpart. default: \"/.well-known/acme-challenge\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-allowed-response-headers","title":"global-allowed-response-headers","text":"<p>A comma-separated list of allowed response headers inside the custom headers annotations</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-url","title":"global-auth-url","text":"<p>A url to an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-url</code>. Locations that should not get authenticated can be listed using <code>no-auth-locations</code> See no-auth-locations. In addition, each service can be excluded from authentication via annotation <code>enable-global-auth</code> set to \"false\". default: \"\"</p> <p>References: https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#external-authentication</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-method","title":"global-auth-method","text":"<p>A HTTP method to use for an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-method</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-signin","title":"global-auth-signin","text":"<p>Sets the location of the error page for an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-signin</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-signin-redirect-param","title":"global-auth-signin-redirect-param","text":"<p>Sets the query parameter in the error page signin URL which contains the original URL of the request that failed authentication. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-signin-redirect-param</code>. default: \"rd\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-response-headers","title":"global-auth-response-headers","text":"<p>Sets the headers to pass to backend once authentication request completes. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-response-headers</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-request-redirect","title":"global-auth-request-redirect","text":"<p>Sets the X-Auth-Request-Redirect header value. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-request-redirect</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-snippet","title":"global-auth-snippet","text":"<p>Sets a custom snippet to use with external authentication. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-snippet</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-cache-key","title":"global-auth-cache-key","text":"<p>Enables caching for global auth requests. Specify a lookup key for auth responses, e.g. <code>$remote_user$http_authorization</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-cache-duration","title":"global-auth-cache-duration","text":"<p>Set a caching time for auth responses based on their response codes, e.g. <code>200 202 30m</code>. See proxy_cache_valid for details. You may specify multiple, comma-separated values: <code>200 202 10m, 401 5m</code>. defaults to <code>200 202 401 5m</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-always-set-cookie","title":"global-auth-always-set-cookie","text":"<p>Always set a cookie returned by auth request. By default, the cookie will be set only if an upstream reports with the code 200, 201, 204, 206, 301, 302, 303, 304, 307, or 308. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#no-auth-locations","title":"no-auth-locations","text":"<p>A comma-separated list of locations that should not get authenticated. default: \"/.well-known/acme-challenge\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#block-cidrs","title":"block-cidrs","text":"<p>A comma-separated list of IP addresses (or subnets), request from which have to be blocked globally.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_access_module.html#deny</p>"},{"location":"user-guide/nginx-configuration/configmap/#block-user-agents","title":"block-user-agents","text":"<p>A comma-separated list of User-Agent, request from which have to be blocked globally. It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code>map</code> Nginx directive documentation.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#map</p>"},{"location":"user-guide/nginx-configuration/configmap/#block-referers","title":"block-referers","text":"<p>A comma-separated list of Referers, request from which have to be blocked globally. It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code>map</code> Nginx directive documentation.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#map</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-ssl-location-only","title":"proxy-ssl-location-only","text":"<p>Set if proxy-ssl parameters should be applied only on locations and not on servers. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#default-type","title":"default-type","text":"<p>Sets the default MIME type of a response. default: text/html</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#default_type</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-rate-limit","title":"global-rate-limit","text":"<ul> <li><code>global-rate-limit-status-code</code>: configure HTTP status code to return when rejecting requests. Defaults to 429.</li> </ul> <p>Configure <code>memcached</code> client for Global Rate Limiting.</p> <ul> <li><code>global-rate-limit-memcached-host</code>: IP/FQDN of memcached server to use. Required to enable Global Rate Limiting.</li> <li><code>global-rate-limit-memcached-port</code>: port of memcached server to use. Defaults default memcached port of <code>11211</code>.</li> <li><code>global-rate-limit-memcached-connect-timeout</code>: configure timeout for connect, send and receive operations. Unit is millisecond. Defaults to 50ms.</li> <li><code>global-rate-limit-memcached-max-idle-timeout</code>: configure timeout for cleaning idle connections. Unit is millisecond. Defaults to 50ms.</li> <li><code>global-rate-limit-memcached-pool-size</code>: configure number of max connections to keep alive. Make sure your <code>memcached</code> server can handle <code>global-rate-limit-memcached-pool-size * worker-processes * &lt;number of ingress-nginx replicas&gt;</code> simultaneous connections.</li> </ul> <p>These settings get used by lua-resty-global-throttle that ingress-nginx includes. Refer to the link to learn more about <code>lua-resty-global-throttle</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#service-upstream","title":"service-upstream","text":"<p>Set if the service's Cluster IP and port should be used instead of a list of all endpoints. This can be overwritten by an annotation on an Ingress rule. default: \"false\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-reject-handshake","title":"ssl-reject-handshake","text":"<p>Set to reject SSL handshake to an unknown virtualhost. This parameter helps to mitigate the fingerprinting using default certificate of ingress. default: \"false\"</p> <p>References: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_reject_handshake</p>"},{"location":"user-guide/nginx-configuration/configmap/#debug-connections","title":"debug-connections","text":"<p>Enables debugging log for selected client connections. default: \"\"</p> <p>References: http://nginx.org/en/docs/ngx_core_module.html#debug_connection</p>"},{"location":"user-guide/nginx-configuration/configmap/#strict-validate-path-type","title":"strict-validate-path-type","text":"<p>Ingress objects contains a field called pathType that defines the proxy behavior. It can be <code>Exact</code>, <code>Prefix</code> and <code>ImplementationSpecific</code>.</p> <p>When pathType is configured as <code>Exact</code> or <code>Prefix</code>, there should be a more strict validation, allowing only paths starting with \"/\" and containing only alphanumeric characters and \"-\", \"_\" and additional \"/\".</p> <p>When this option is enabled, the validation will happen on the Admission Webhook, making any Ingress not using pathType <code>ImplementationSpecific</code> and containing invalid characters to be denied.</p> <p>This means that Ingress objects that rely on paths containing regex characters should use <code>ImplementationSpecific</code> pathType.</p> <p>The cluster admin should establish validation rules using mechanisms like Open Policy Agent to  validate that only authorized users can use <code>ImplementationSpecific</code> pathType and that only the authorized characters can be used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#grpc-buffer-size-kb","title":"grpc-buffer-size-kb","text":"<p>Sets the configuration for the GRPC Buffer Size parameter. If not set it will use the default from NGINX.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size</p>"},{"location":"user-guide/nginx-configuration/custom-template/","title":"Custom NGINX template","text":"<p>The NGINX template is located in the file <code>/etc/nginx/template/nginx.tmpl</code>.</p> <p>Using a Volume it is possible to use a custom template. This includes using a Configmap as source of the template</p> <pre><code>        volumeMounts:\n          - mountPath: /etc/nginx/template\n            name: nginx-template-volume\n            readOnly: true\n      volumes:\n        - name: nginx-template-volume\n          configMap:\n            name: nginx-template\n            items:\n            - key: nginx.tmpl\n              path: nginx.tmpl\n</code></pre> <p>Please note the template is tied to the Go code. Do not change names in the variable <code>$cfg</code>.</p> <p>For more information about the template syntax please check the Go template package. In addition to the built-in functions provided by the Go package the following functions are also available:</p> <ul> <li>empty: returns true if the specified parameter (string) is empty</li> <li>contains: strings.Contains</li> <li>hasPrefix: strings.HasPrefix</li> <li>hasSuffix: strings.HasSuffix</li> <li>toUpper: strings.ToUpper</li> <li>toLower: strings.ToLower</li> <li>split: strings.Split</li> <li>quote: wraps a string in double quotes</li> <li>buildLocation: helps to build the NGINX Location section in each server</li> <li>buildProxyPass: builds the reverse proxy configuration</li> <li>buildRateLimit: helps to build a limit zone inside a location if contains a rate limit annotation</li> </ul> <p>TODO:</p> <ul> <li>buildAuthLocation:</li> <li>buildAuthResponseHeaders:</li> <li>buildResolvers:</li> <li>buildDenyVariable:</li> <li>buildUpstreamName:</li> <li>buildForwardedFor:</li> <li>buildAuthSignURL:</li> <li>buildNextUpstream:</li> <li>filterRateLimits:</li> <li>formatIP:</li> <li>getenv:</li> <li>getIngressInformation:</li> <li>serverConfig:</li> <li>isLocationAllowed:</li> <li>isValidClientBodyBufferSize:</li> </ul>"},{"location":"user-guide/nginx-configuration/log-format/","title":"Log format","text":"<p>The default configuration uses a custom logging format to add additional information about upstreams, response time and status.</p> <pre><code>log_format upstreaminfo\n    '$remote_addr - $remote_user [$time_local] \"$request\" '\n    '$status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" '\n    '$request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr '\n    '$upstream_response_length $upstream_response_time $upstream_status $req_id';\n</code></pre> Placeholder Description <code>$proxy_protocol_addr</code> remote address if proxy protocol is enabled <code>$remote_addr</code> the source IP address of the client <code>$remote_user</code> user name supplied with the Basic authentication <code>$time_local</code> local time in the Common Log Format <code>$request</code> full original request line <code>$status</code> response status <code>$body_bytes_sent</code> number of bytes sent to a client, not counting the response header <code>$http_referer</code> value of the Referer header <code>$http_user_agent</code> value of User-Agent header <code>$request_length</code> request length (including request line, header, and request body) <code>$request_time</code> time elapsed since the first bytes were read from the client <code>$proxy_upstream_name</code> name of the upstream. The format is <code>upstream-&lt;namespace&gt;-&lt;service name&gt;-&lt;service port&gt;</code> <code>$proxy_alternative_upstream_name</code> name of the alternative upstream. The format is <code>upstream-&lt;namespace&gt;-&lt;service name&gt;-&lt;service port&gt;</code> <code>$upstream_addr</code> the IP address and port (or the path to the domain socket) of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas. <code>$upstream_response_length</code> the length of the response obtained from the upstream server <code>$upstream_response_time</code> time spent on receiving the response from the upstream server as seconds with millisecond resolution <code>$upstream_status</code> status code of the response obtained from the upstream server <code>$req_id</code> value of the <code>X-Request-ID</code> HTTP header. If the header is not set, a randomly generated ID. <p>Additional available variables:</p> Placeholder Description <code>$namespace</code> namespace of the ingress <code>$ingress_name</code> name of the ingress <code>$service_name</code> name of the service <code>$service_port</code> port of the service <p>Sources:</p> <ul> <li>Upstream variables</li> <li>Embedded variables</li> </ul>"},{"location":"user-guide/third-party-addons/modsecurity/","title":"ModSecurity Web Application Firewall","text":"<p>ModSecurity is an open source, cross platform web application firewall (WAF) engine for Apache, IIS and Nginx that is developed by Trustwave's SpiderLabs. It has a robust event-based programming language which provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring, logging and real-time analysis - https://www.modsecurity.org</p> <p>The ModSecurity-nginx connector is the connection point between NGINX and libmodsecurity (ModSecurity v3).</p> <p>The default ModSecurity configuration file is located in <code>/etc/nginx/modsecurity/modsecurity.conf</code>. This is the only file located in this directory and contains the default recommended configuration. Using a volume we can replace this file with the desired configuration. To enable the ModSecurity feature we need to specify <code>enable-modsecurity: \"true\"</code> in the configuration configmap.</p> <p>Note: the default configuration use detection only, because that minimizes the chances of post-installation disruption. Due to the value of the setting SecAuditLogType=Concurrent the ModSecurity log is stored in multiple files inside the directory <code>/var/log/audit</code>. The default <code>Serial</code> value in SecAuditLogType can impact performance.</p> <p>The OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. The CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts. The directory <code>/etc/nginx/owasp-modsecurity-crs</code> contains the OWASP ModSecurity Core Rule Set repository. Using <code>enable-owasp-modsecurity-crs: \"true\"</code> we enable the use of the rules.</p>"},{"location":"user-guide/third-party-addons/opentelemetry/","title":"OpenTelemetry","text":"<p>Enables requests served by NGINX for distributed telemetry via The OpenTelemetry Project.</p> <p>Using the third party module opentelemetry-cpp-contrib/nginx the Ingress-Nginx Controller can configure NGINX to enable OpenTelemetry instrumentation. By default this feature is disabled.</p> <p>Check out this demo showcasing OpenTelemetry in Ingress NGINX. The video provides an overview and practical demonstration of how OpenTelemetry can be utilized in Ingress NGINX for observability and monitoring purposes.</p> <p> </p> <p>Demo: OpenTelemetry in Ingress NGINX.</p>"},{"location":"user-guide/third-party-addons/opentelemetry/#usage","title":"Usage","text":"<p>To enable the instrumentation we must enable OpenTelemetry in the configuration ConfigMap: <pre><code>data:\n  enable-opentelemetry: \"true\"\n</code></pre></p> <p>To enable or disable instrumentation for a single Ingress, use the <code>enable-opentelemetry</code> annotation: <pre><code>kind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/enable-opentelemetry: \"true\"\n</code></pre></p> <p>We must also set the host to use when uploading traces:</p> <p><pre><code>otlp-collector-host: \"otel-coll-collector.otel.svc\"\n</code></pre> NOTE: While the option is called <code>otlp-collector-host</code>, you will need to point this to any backend that receives otlp-grpc.</p> <p>Next you will need to deploy a distributed telemetry system which uses OpenTelemetry. opentelemetry-collector, Jaeger Tempo, and zipkin have been tested.</p> <p>Other optional configuration options: <pre><code># specifies the name to use for the server span\nopentelemetry-operation-name\n\n# sets whether or not to trust incoming telemetry spans\nopentelemetry-trust-incoming-span\n\n# specifies the port to use when uploading traces, Default: 4317\notlp-collector-port\n\n# specifies the service name to use for any traces created, Default: nginx\notel-service-name\n\n# The maximum queue size. After the size is reached data are dropped.\notel-max-queuesize\n\n# The delay interval in milliseconds between two consecutive exports.\notel-schedule-delay-millis\n\n# How long the export can run before it is cancelled.\notel-schedule-delay-millis\n\n# The maximum batch size of every export. It must be smaller or equal to maxQueueSize.\notel-max-export-batch-size\n\n# specifies sample rate for any traces created, Default: 0.01\notel-sampler-ratio\n\n# specifies the sampler to be used when sampling traces.\n# The available samplers are: AlwaysOn,  AlwaysOff, TraceIdRatioBased, Default: AlwaysOff\notel-sampler\n\n# Uses sampler implementation which by default will take a sample if parent Activity is sampled, Default: false\notel-sampler-parent-based\n</code></pre></p> <p>Note that you can also set whether to trust incoming spans (global default is true) per-location using annotations like the following: <pre><code>kind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span: \"true\"\n</code></pre></p>"},{"location":"user-guide/third-party-addons/opentelemetry/#examples","title":"Examples","text":"<p>The following examples show how to deploy and test different distributed telemetry systems. These example can be performed using Docker Desktop.</p> <p>In the esigo/nginx-example GitHub repository is an example of a simple hello service:</p> <pre><code>graph TB\n    subgraph Browser\n    start[\"http://esigo.dev/hello/nginx\"]\n    end\n\n    subgraph app\n        sa[service-a]\n        sb[service-b]\n        sa --&gt; |name: nginx| sb\n        sb --&gt; |hello nginx!| sa\n    end\n\n    subgraph otel\n        otc[\"Otel Collector\"] \n    end\n\n    subgraph observability\n        tempo[\"Tempo\"]\n        grafana[\"Grafana\"]\n        backend[\"Jaeger\"]\n        zipkin[\"Zipkin\"]\n    end\n\n    subgraph ingress-nginx\n        ngx[nginx]\n    end\n\n    subgraph ngx[nginx]\n        ng[nginx]\n        om[OpenTelemetry module]\n    end\n\n    subgraph Node\n        app\n        otel\n        observability\n        ingress-nginx\n        om --&gt; |otlp-gRPC| otc --&gt; |jaeger| backend\n        otc --&gt; |zipkin| zipkin\n        otc --&gt; |otlp-gRPC| tempo --&gt; grafana\n        sa --&gt; |otlp-gRPC| otc\n        sb --&gt; |otlp-gRPC| otc\n        start --&gt; ng --&gt; sa\n    end</code></pre> <p>To install the example and collectors run:</p> <ol> <li> <p>Enable Ingress addon with:</p> <pre><code>  opentelemetry:\n    enabled: true\n    image: registry.k8s.io/ingress-nginx/opentelemetry:v20230527@sha256:fd7ec835f31b7b37187238eb4fdad4438806e69f413a203796263131f4f02ed0\n    containerSecurityContext:\n    allowPrivilegeEscalation: false\n</code></pre> </li> <li> <p>Enable OpenTelemetry and set the otlp-collector-host:</p> <pre><code>$ echo '\n  apiVersion: v1\n  kind: ConfigMap\n  data:\n    enable-opentelemetry: \"true\"\n    opentelemetry-config: \"/etc/nginx/opentelemetry.toml\"\n    opentelemetry-operation-name: \"HTTP $request_method $service_name $uri\"\n    opentelemetry-trust-incoming-span: \"true\"\n    otlp-collector-host: \"otel-coll-collector.otel.svc\"\n    otlp-collector-port: \"4317\"\n    otel-max-queuesize: \"2048\"\n    otel-schedule-delay-millis: \"5000\"\n    otel-max-export-batch-size: \"512\"\n    otel-service-name: \"nginx-proxy\" # Opentelemetry resource name\n    otel-sampler: \"AlwaysOn\" # Also: AlwaysOff, TraceIdRatioBased\n    otel-sampler-ratio: \"1.0\"\n    otel-sampler-parent-based: \"false\"\n  metadata:\n    name: ingress-nginx-controller\n    namespace: ingress-nginx\n  ' | kubectl replace -f -\n</code></pre> </li> <li> <p>Deploy otel-collector, grafana and Jaeger backend:</p> <pre><code># add helm charts needed for grafana and OpenTelemetry collector\nhelm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts\nhelm repo add grafana https://grafana.github.io/helm-charts\nhelm repo update\n# deply cert-manager needed for OpenTelemetry collector operator\nkubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.9.1/cert-manager.yaml\n# create observability namespace\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/namespace.yaml\n# install OpenTelemetry collector operator\nhelm upgrade --install otel-collector-operator -n otel --create-namespace open-telemetry/opentelemetry-operator\n# deploy OpenTelemetry collector\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/collector.yaml\n# deploy Jaeger all-in-one\nkubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.37.0/jaeger-operator.yaml -n observability\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/jaeger.yaml -n observability\n# deploy zipkin\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/zipkin.yaml -n observability\n# deploy tempo and grafana\nhelm upgrade --install tempo grafana/tempo --create-namespace -n observability\nhelm upgrade -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/grafana/grafana-values.yaml --install grafana grafana/grafana --create-namespace -n observability\n</code></pre> </li> <li> <p>Build and deploy demo app:</p> <pre><code># build images\nmake images\n\n# deploy demo app:\nmake deploy-app\n</code></pre> </li> <li> <p>Make a few requests to the Service:</p> <pre><code>kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8090:80\ncurl http://esigo.dev:8090/hello/nginx\n\n\nStatusCode        : 200\nStatusDescription : OK\nContent           : {\"v\":\"hello nginx!\"}\n\nRawContent        : HTTP/1.1 200 OK\n                    Connection: keep-alive\n                    Content-Length: 21\n                    Content-Type: text/plain; charset=utf-8\n                    Date: Mon, 10 Oct 2022 17:43:33 GMT\n\n                    {\"v\":\"hello nginx!\"}\n\nForms             : {}\nHeaders           : {[Connection, keep-alive], [Content-Length, 21], [Content-Type, text/plain; charset=utf-8], [Date,\n                    Mon, 10 Oct 2022 17:43:33 GMT]}\nImages            : {}\nInputFields       : {}\nLinks             : {}\nParsedHtml        : System.__ComObject\nRawContentLength  : 21\n</code></pre> </li> <li> <p>View the Grafana UI:</p> <p><pre><code>kubectl port-forward --namespace=observability service/grafana 3000:80\n</code></pre> In the Grafana interface we can see the details: </p> </li> <li> <p>View the Jaeger UI:</p> <p><pre><code>kubectl port-forward --namespace=observability service/jaeger-all-in-one-query 16686:16686\n</code></pre> In the Jaeger interface we can see the details: </p> </li> <li> <p>View the Zipkin UI:</p> <p><pre><code>kubectl port-forward --namespace=observability service/zipkin 9411:9411\n</code></pre> In the Zipkin interface we can see the details: </p> </li> </ol>"},{"location":"user-guide/third-party-addons/opentelemetry/#migration-from-opentracing-jaeger-zipkin-and-datadog","title":"Migration from OpenTracing, Jaeger, Zipkin and Datadog","text":"<p>If you are migrating from OpenTracing, Jaeger, Zipkin, or Datadog to OpenTelemetry, you may need to update various annotations and configurations. Here are the mappings for common annotations and configurations:</p>"},{"location":"user-guide/third-party-addons/opentelemetry/#annotations","title":"Annotations","text":"Legacy OpenTelemetry <code>nginx.ingress.kubernetes.io/enable-opentracing</code> <code>nginx.ingress.kubernetes.io/enable-opentelemetry</code> <code>nginx.ingress.kubernetes.io/opentracing-trust-incoming-span</code> <code>nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span</code>"},{"location":"user-guide/third-party-addons/opentelemetry/#configs","title":"Configs","text":"Legacy OpenTelemetry <code>opentracing-operation-name</code> <code>opentelemetry-operation-name</code> <code>opentracing-location-operation-name</code> <code>opentelemetry-operation-name</code> <code>opentracing-trust-incoming-span</code> <code>opentelemetry-trust-incoming-span</code> <code>zipkin-collector-port</code> <code>otlp-collector-port</code> <code>zipkin-service-name</code> <code>otel-service-name</code> <code>zipkin-sample-rate</code> <code>otel-sampler-ratio</code> <code>jaeger-collector-port</code> <code>otlp-collector-port</code> <code>jaeger-endpoint</code> <code>otlp-collector-port</code>, <code>otlp-collector-host</code> <code>jaeger-service-name</code> <code>otel-service-name</code> <code>jaeger-propagation-format</code> <code>N/A</code> <code>jaeger-sampler-type</code> <code>otel-sampler</code> <code>jaeger-sampler-param</code> <code>otel-sampler</code> <code>jaeger-sampler-host</code> <code>N/A</code> <code>jaeger-sampler-port</code> <code>N/A</code> <code>jaeger-trace-context-header-name</code> <code>N/A</code> <code>jaeger-debug-header</code> <code>N/A</code> <code>jaeger-baggage-header</code> <code>N/A</code> <code>jaeger-tracer-baggage-header-prefix</code> <code>N/A</code> <code>datadog-collector-port</code> <code>otlp-collector-port</code> <code>datadog-service-name</code> <code>otel-service-name</code> <code>datadog-environment</code> <code>N/A</code> <code>datadog-operation-name-override</code> <code>N/A</code> <code>datadog-priority-sampling</code> <code>otel-sampler</code> <code>datadog-sample-rate</code> <code>otel-sampler-ratio</code>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Overview","text":"<p>This is the documentation for the Ingress NGINX Controller.</p> <p>It is built around the Kubernetes Ingress resource, using a ConfigMap to store the controller configuration.</p> <p>You can learn more about using Ingress in the official Kubernetes documentation.</p>"},{"location":"#getting-started","title":"Getting Started","text":"<p>See Deployment for a whirlwind tour that will get you started.</p>"},{"location":"e2e-tests/","title":"E2e tests","text":""},{"location":"e2e-tests/#e2e-test-suite-for-ingress-nginx-controller","title":"e2e test suite for Ingress NGINX Controller","text":""},{"location":"e2e-tests/#admission-admission-controller","title":"[Admission] admission controller","text":"<ul> <li>reject ingress with global-rate-limit annotations when memcached is not configured</li> <li>should not allow overlaps of host and paths without canary annotations</li> <li>should allow overlaps of host and paths with canary annotation</li> <li>should block ingress with invalid path</li> <li>should return an error if there is an error validating the ingress definition</li> <li>should return an error if there is an invalid value in some annotation</li> <li>should return an error if there is a forbidden value in some annotation</li> <li>should return an error if there is an invalid path and wrong pathType is set</li> <li>should not return an error if the Ingress V1 definition is valid with Ingress Class</li> <li>should not return an error if the Ingress V1 definition is valid with IngressClass annotation</li> <li>should return an error if the Ingress V1 definition contains invalid annotations</li> <li>should not return an error for an invalid Ingress when it has unknown class</li> </ul>"},{"location":"e2e-tests/#affinity-session-cookie-name","title":"affinity session-cookie-name","text":"<ul> <li>should set sticky cookie SERVERID</li> <li>should change cookie name on ingress definition change</li> <li>should set the path to /something on the generated cookie</li> <li>does not set the path to / on the generated cookie if there's more than one rule referring to the same backend</li> <li>should set cookie with expires</li> <li>should set cookie with domain</li> <li>should not set cookie without domain annotation</li> <li>should work with use-regex annotation and session-cookie-path</li> <li>should warn user when use-regex is true and session-cookie-path is not set</li> <li>should not set affinity across all server locations when using separate ingresses</li> <li>should set sticky cookie without host</li> <li>should work with server-alias annotation</li> <li>should set secure in cookie with provided true annotation on http</li> <li>should not set secure in cookie with provided false annotation on http</li> <li>should set secure in cookie with provided false annotation on https</li> </ul>"},{"location":"e2e-tests/#affinitymode","title":"affinitymode","text":"<ul> <li>Balanced affinity mode should balance</li> <li>Check persistent affinity mode</li> </ul>"},{"location":"e2e-tests/#server-alias","title":"server-alias","text":"<ul> <li>should return status code 200 for host 'foo' and 404 for 'bar'</li> <li>should return status code 200 for host 'foo' and 'bar'</li> <li>should return status code 200 for hosts defined in two ingresses, different path with one alias</li> </ul>"},{"location":"e2e-tests/#app-root","title":"app-root","text":"<ul> <li>should redirect to /foo</li> </ul>"},{"location":"e2e-tests/#auth-","title":"auth-*","text":"<ul> <li>should return status code 200 when no authentication is configured</li> <li>should return status code 503 when authentication is configured with an invalid secret</li> <li>should return status code 401 when authentication is configured but Authorization header is not configured</li> <li>should return status code 401 when authentication is configured and Authorization header is sent with invalid credentials</li> <li>should return status code 401 and cors headers when authentication and cors is configured but Authorization header is not configured</li> <li>should return status code 200 when authentication is configured and Authorization header is sent</li> <li>should return status code 200 when authentication is configured with a map and Authorization header is sent</li> <li>should return status code 401 when authentication is configured with invalid content and Authorization header is sent</li> <li>proxy_set_header My-Custom-Header 42;</li> <li>proxy_set_header My-Custom-Header 42;</li> <li>proxy_set_header 'My-Custom-Header' '42';</li> <li>user retains cookie by default</li> <li>user does not retain cookie if upstream returns error status code</li> <li>user with annotated ingress retains cookie if upstream returns error status code</li> <li>should return status code 200 when signed in</li> <li>should redirect to signin url when not signed in</li> <li>keeps processing new ingresses even if one of the existing ingresses is misconfigured</li> <li>should overwrite Foo header with auth response</li> <li>should return status code 200 when signed in</li> <li>should redirect to signin url when not signed in</li> <li>keeps processing new ingresses even if one of the existing ingresses is misconfigured</li> <li>should return status code 200 when signed in after auth backend is deleted </li> <li>should deny login for different location on same server</li> <li>should deny login for different servers</li> <li>should redirect to signin url when not signed in</li> <li>should return 503 (location was denied)</li> <li>should add error to the config</li> </ul>"},{"location":"e2e-tests/#auth-tls-","title":"auth-tls-*","text":"<ul> <li>should set sslClientCertificate, sslVerifyClient and sslVerifyDepth with auth-tls-secret</li> <li>should set valid auth-tls-secret, sslVerify to off, and sslVerifyDepth to 2</li> <li>should 302 redirect to error page instead of 400 when auth-tls-error-page is set</li> <li>should pass URL-encoded certificate to upstream</li> <li>should validate auth-tls-verify-client</li> <li>should return 403 using auth-tls-match-cn with no matching CN from client</li> <li>should return 200 using auth-tls-match-cn with matching CN from client</li> <li>should return 200 using auth-tls-match-cn where atleast one of the regex options matches CN from client</li> </ul>"},{"location":"e2e-tests/#backend-protocol","title":"backend-protocol","text":"<ul> <li>should set backend protocol to https:// and use proxy_pass</li> <li>should set backend protocol to https:// and use proxy_pass with lowercase annotation</li> <li>should set backend protocol to $scheme:// and use proxy_pass</li> <li>should set backend protocol to grpc:// and use grpc_pass</li> <li>should set backend protocol to grpcs:// and use grpc_pass</li> <li>should set backend protocol to '' and use fastcgi_pass</li> </ul>"},{"location":"e2e-tests/#canary-","title":"canary-*","text":"<ul> <li>should response with a 200 status from the mainline upstream when requests are made to the mainline ingress</li> <li>should return 404 status for requests to the canary if no matching ingress is found</li> <li>should return the correct status codes when endpoints are unavailable</li> <li>should route requests to the correct upstream if mainline ingress is created before the canary ingress</li> <li>should route requests to the correct upstream if mainline ingress is created after the canary ingress</li> <li>should route requests to the correct upstream if the mainline ingress is modified</li> <li>should route requests to the correct upstream if the canary ingress is modified</li> <li>should route requests to the correct upstream</li> <li>should route requests to the correct upstream</li> <li>should route requests to the correct upstream</li> <li>should route requests to the correct upstream</li> <li>should routes to mainline upstream when the given Regex causes error</li> <li>should route requests to the correct upstream</li> <li>respects always and never values</li> <li>should route requests only to mainline if canary weight is 0</li> <li>should route requests only to canary if canary weight is 100</li> <li>should route requests only to canary if canary weight is equal to canary weight total</li> <li>should route requests split between mainline and canary if canary weight is 50</li> <li>should route requests split between mainline and canary if canary weight is 100 and weight total is 200</li> <li>should not use canary as a catch-all server</li> <li>should not use canary with domain as a server</li> <li>does not crash when canary ingress has multiple paths to the same non-matching backend</li> <li>always routes traffic to canary if first request was affinitized to canary (default behavior)</li> <li>always routes traffic to canary if first request was affinitized to canary (explicit sticky behavior)</li> <li>routes traffic to either mainline or canary backend (legacy behavior)</li> </ul>"},{"location":"e2e-tests/#client-body-buffer-size","title":"client-body-buffer-size","text":"<ul> <li>should set client_body_buffer_size to 1000</li> <li>should set client_body_buffer_size to 1K</li> <li>should set client_body_buffer_size to 1k</li> <li>should set client_body_buffer_size to 1m</li> <li>should set client_body_buffer_size to 1M</li> <li>should not set client_body_buffer_size to invalid 1b</li> </ul>"},{"location":"e2e-tests/#connection-proxy-header","title":"connection-proxy-header","text":"<ul> <li>set connection header to keep-alive</li> </ul>"},{"location":"e2e-tests/#cors-","title":"cors-*","text":"<ul> <li>should enable cors</li> <li>should set cors methods to only allow POST, GET</li> <li>should set cors max-age</li> <li>should disable cors allow credentials</li> <li>should allow origin for cors</li> <li>should allow headers for cors</li> <li>should expose headers for cors</li> <li>should allow - single origin for multiple cors values</li> <li>should not allow - single origin for multiple cors values</li> <li>should allow correct origins - single origin for multiple cors values</li> <li>should not break functionality</li> <li>should not break functionality - without <code>*</code></li> <li>should not break functionality with extra domain</li> <li>should not match</li> <li>should allow - single origin with required port</li> <li>should not allow - single origin with port and origin without port</li> <li>should not allow - single origin without port and origin with required port</li> <li>should allow - matching origin with wildcard origin (2 subdomains)</li> <li>should not allow - unmatching origin with wildcard origin (2 subdomains)</li> <li>should allow - matching origin+port with wildcard origin</li> <li>should not allow - portless origin with wildcard origin</li> <li>should allow correct origins - missing subdomain + origin with wildcard origin and correct origin</li> <li>should allow - missing origins (should allow all origins)</li> <li>should allow correct origin but not others - cors allow origin annotations contain trailing comma</li> </ul>"},{"location":"e2e-tests/#custom-http-errors","title":"custom-http-errors","text":"<ul> <li>configures Nginx correctly</li> </ul>"},{"location":"e2e-tests/#default-backend","title":"default-backend","text":"<ul> <li>should use a custom default backend as upstream</li> </ul>"},{"location":"e2e-tests/#disable-access-log-disable-http-access-log-disable-stream-access-log","title":"disable-access-log disable-http-access-log disable-stream-access-log","text":"<ul> <li>disable-access-log set access_log off</li> <li>disable-http-access-log set access_log off</li> <li>disable-stream-access-log set access_log off</li> </ul>"},{"location":"e2e-tests/#disable-proxy-intercept-errors","title":"disable-proxy-intercept-errors","text":"<ul> <li>configures Nginx correctly</li> </ul>"},{"location":"e2e-tests/#backend-protocol-fastcgi","title":"backend-protocol - FastCGI","text":"<ul> <li>should use fastcgi_pass in the configuration file</li> <li>should add fastcgi_index in the configuration file</li> <li>should add fastcgi_param in the configuration file</li> <li>should return OK for service with backend protocol FastCGI</li> </ul>"},{"location":"e2e-tests/#force-ssl-redirect","title":"force-ssl-redirect","text":"<ul> <li>should redirect to https</li> </ul>"},{"location":"e2e-tests/#from-to-www-redirect","title":"from-to-www-redirect","text":"<ul> <li>should redirect from www HTTP to HTTP</li> <li>should redirect from www HTTPS to HTTPS</li> </ul>"},{"location":"e2e-tests/#annotation-global-rate-limit","title":"annotation-global-rate-limit","text":"<ul> <li>generates correct configuration</li> </ul>"},{"location":"e2e-tests/#backend-protocol-grpc","title":"backend-protocol - GRPC","text":"<ul> <li>should use grpc_pass in the configuration file</li> <li>should return OK for service with backend protocol GRPC</li> <li>authorization metadata should be overwritten by external auth response headers</li> <li>should return OK for service with backend protocol GRPCS</li> </ul>"},{"location":"e2e-tests/#http2-push-preload","title":"http2-push-preload","text":"<ul> <li>enable the http2-push-preload directive</li> </ul>"},{"location":"e2e-tests/#allowlist-source-range","title":"allowlist-source-range","text":"<ul> <li>should set valid ip allowlist range</li> </ul>"},{"location":"e2e-tests/#denylist-source-range","title":"denylist-source-range","text":"<ul> <li>only deny explicitly denied IPs, allow all others</li> <li>only allow explicitly allowed IPs, deny all others</li> </ul>"},{"location":"e2e-tests/#annotation-limit-connections","title":"Annotation - limit-connections","text":"<ul> <li>should limit-connections</li> </ul>"},{"location":"e2e-tests/#limit-rate","title":"limit-rate","text":"<ul> <li>Check limit-rate annotation</li> </ul>"},{"location":"e2e-tests/#enable-access-log-enable-rewrite-log","title":"enable-access-log enable-rewrite-log","text":"<ul> <li>set access_log off</li> <li>set rewrite_log on</li> </ul>"},{"location":"e2e-tests/#mirror-","title":"mirror-*","text":"<ul> <li>should set mirror-target to http://localhost/mirror</li> <li>should set mirror-target to https://test.env.com/$request_uri</li> <li>should disable mirror-request-body</li> </ul>"},{"location":"e2e-tests/#modsecurity-owasp","title":"modsecurity owasp","text":"<ul> <li>should enable modsecurity</li> <li>should enable modsecurity with transaction ID and OWASP rules</li> <li>should disable modsecurity</li> <li>should enable modsecurity with snippet</li> <li>should enable modsecurity without using 'modsecurity on;'</li> <li>should disable modsecurity using 'modsecurity off;'</li> <li>should enable modsecurity with snippet and block requests</li> <li>should enable modsecurity globally and with modsecurity-snippet block requests</li> <li>should enable modsecurity when enable-owasp-modsecurity-crs is set to true</li> <li>should enable modsecurity through the config map</li> <li>should enable modsecurity through the config map but ignore snippet as disabled by admin</li> <li>should disable default modsecurity conf setting when modsecurity-snippet is specified</li> </ul>"},{"location":"e2e-tests/#preserve-trailing-slash","title":"preserve-trailing-slash","text":"<ul> <li>should allow preservation of trailing slashes</li> </ul>"},{"location":"e2e-tests/#proxy-","title":"proxy-*","text":"<ul> <li>should set proxy_redirect to off</li> <li>should set proxy_redirect to default</li> <li>should set proxy_redirect to hello.com goodbye.com</li> <li>should set proxy client-max-body-size to 8m</li> <li>should not set proxy client-max-body-size to incorrect value</li> <li>should set valid proxy timeouts</li> <li>should not set invalid proxy timeouts</li> <li>should turn on proxy-buffering</li> <li>should turn off proxy-request-buffering</li> <li>should build proxy next upstream</li> <li>should setup proxy cookies</li> <li>should change the default proxy HTTP version</li> </ul>"},{"location":"e2e-tests/#proxy-ssl-","title":"proxy-ssl-*","text":"<ul> <li>should set valid proxy-ssl-secret</li> <li>should set valid proxy-ssl-secret, proxy-ssl-verify to on, proxy-ssl-verify-depth to 2, and proxy-ssl-server-name to on</li> <li>should set valid proxy-ssl-secret, proxy-ssl-ciphers to HIGH:!AES</li> <li>should set valid proxy-ssl-secret, proxy-ssl-protocols</li> <li>proxy-ssl-location-only flag should change the nginx config server part</li> </ul>"},{"location":"e2e-tests/#permanent-redirect-permanent-redirect-code","title":"permanent-redirect permanent-redirect-code","text":"<ul> <li>should respond with a standard redirect code</li> <li>should respond with a custom redirect code</li> </ul>"},{"location":"e2e-tests/#rewrite-target-use-regex-enable-rewrite-log","title":"rewrite-target use-regex enable-rewrite-log","text":"<ul> <li>should write rewrite logs</li> <li>should use correct longest path match</li> <li>should use ~* location modifier if regex annotation is present</li> <li>should fail to use longest match for documented warning</li> <li>should allow for custom rewrite parameters</li> </ul>"},{"location":"e2e-tests/#satisfy","title":"satisfy","text":"<ul> <li>should configure satisfy directive correctly</li> <li>should allow multiple auth with satisfy any</li> </ul>"},{"location":"e2e-tests/#server-snippet","title":"server-snippet","text":""},{"location":"e2e-tests/#service-upstream","title":"service-upstream","text":"<ul> <li>should use the Service Cluster IP and Port </li> <li>should use the Service Cluster IP and Port </li> <li>should not use the Service Cluster IP and Port</li> </ul>"},{"location":"e2e-tests/#configuration-snippet","title":"configuration-snippet","text":"<ul> <li>set snippet more_set_headers in all locations</li> <li>drops snippet more_set_header in all locations if disabled by admin</li> </ul>"},{"location":"e2e-tests/#ssl-ciphers","title":"ssl-ciphers","text":"<ul> <li>should change ssl ciphers</li> <li>should keep ssl ciphers</li> </ul>"},{"location":"e2e-tests/#stream-snippet","title":"stream-snippet","text":"<ul> <li>should add value of stream-snippet to nginx config</li> <li>should add stream-snippet and drop annotations per admin config</li> </ul>"},{"location":"e2e-tests/#upstream-hash-by-","title":"upstream-hash-by-*","text":"<ul> <li>should connect to the same pod</li> <li>should connect to the same subset of pods</li> </ul>"},{"location":"e2e-tests/#upstream-vhost","title":"upstream-vhost","text":"<ul> <li>set host to upstreamvhost.bar.com</li> </ul>"},{"location":"e2e-tests/#x-forwarded-prefix","title":"x-forwarded-prefix","text":"<ul> <li>should set the X-Forwarded-Prefix to the annotation value</li> <li>should not add X-Forwarded-Prefix if the annotation value is empty</li> </ul>"},{"location":"e2e-tests/#debug-cli","title":"Debug CLI","text":"<ul> <li>should list the backend servers</li> <li>should get information for a specific backend server</li> <li>should produce valid JSON for /dbg general</li> </ul>"},{"location":"e2e-tests/#default-backend-custom-service","title":"[Default Backend] custom service","text":"<ul> <li>uses custom default backend that returns 200 as status code</li> </ul>"},{"location":"e2e-tests/#default-backend_1","title":"[Default Backend]","text":"<ul> <li>should return 404 sending requests when only a default backend is running</li> <li>enables access logging for default backend</li> <li>disables access logging for default backend</li> </ul>"},{"location":"e2e-tests/#default-backend-ssl","title":"[Default Backend] SSL","text":"<ul> <li>should return a self generated SSL certificate</li> </ul>"},{"location":"e2e-tests/#default-backend-change-default-settings","title":"[Default Backend] change default settings","text":"<ul> <li>should apply the annotation to the default backend</li> </ul>"},{"location":"e2e-tests/#endpointslices-long-service-name","title":"[Endpointslices] long service name","text":"<ul> <li>should return 200 when service name has max allowed number of characters 63</li> </ul>"},{"location":"e2e-tests/#topologyhints-topology-aware-routing","title":"[TopologyHints] topology aware routing","text":"<ul> <li>should return 200 when service has topology hints</li> </ul>"},{"location":"e2e-tests/#shutdown-grace-period-shutdown","title":"[Shutdown] Grace period shutdown","text":"<ul> <li>/healthz should return status code 500 during shutdown grace period</li> </ul>"},{"location":"e2e-tests/#shutdown-ingress-controller","title":"[Shutdown] ingress controller","text":"<ul> <li>should shutdown in less than 60 secons without pending connections</li> </ul>"},{"location":"e2e-tests/#shutdown-graceful-shutdown-with-pending-request","title":"[Shutdown] Graceful shutdown with pending request","text":"<ul> <li>should let slow requests finish before shutting down</li> </ul>"},{"location":"e2e-tests/#ingress-deepinspection","title":"[Ingress] DeepInspection","text":"<ul> <li>should drop whole ingress if one path matches invalid regex</li> </ul>"},{"location":"e2e-tests/#single-ingress-multiple-hosts","title":"single ingress - multiple hosts","text":"<ul> <li>should set the correct $service_name NGINX variable</li> </ul>"},{"location":"e2e-tests/#ingress-pathtype-exact","title":"[Ingress] [PathType] exact","text":"<ul> <li>should choose exact location for /exact</li> </ul>"},{"location":"e2e-tests/#ingress-pathtype-mix-exact-and-prefix-paths","title":"[Ingress] [PathType] mix Exact and Prefix paths","text":"<ul> <li>should choose the correct location</li> </ul>"},{"location":"e2e-tests/#ingress-pathtype-prefix-checks","title":"[Ingress] [PathType] prefix checks","text":"<ul> <li>should return 404 when prefix /aaa does not match request /aaaccc</li> <li>should test prefix path using simple regex pattern for /id/{int}</li> <li>should test prefix path using regex pattern for /id/{int} ignoring non-digits characters at end of string</li> <li>should test prefix path using fixed path size regex pattern /id/{int}{3}</li> <li>should correctly route multi-segment path patterns</li> </ul>"},{"location":"e2e-tests/#ingress-definition-without-host","title":"[Ingress] definition without host","text":"<ul> <li>should set ingress details variables for ingresses without a host</li> <li>should set ingress details variables for ingresses with host without IngressRuleValue, only Backend</li> </ul>"},{"location":"e2e-tests/#memory-leak-dynamic-certificates","title":"[Memory Leak] Dynamic Certificates","text":"<ul> <li>should not leak memory from ingress SSL certificates or configuration updates</li> </ul>"},{"location":"e2e-tests/#load-balancer-load-balance","title":"[Load Balancer] load-balance","text":"<ul> <li>should apply the configmap load-balance setting</li> </ul>"},{"location":"e2e-tests/#load-balancer-ewma","title":"[Load Balancer] EWMA","text":"<ul> <li>does not fail requests</li> </ul>"},{"location":"e2e-tests/#load-balancer-round-robin","title":"[Load Balancer] round-robin","text":"<ul> <li>should evenly distribute requests with round-robin (default algorithm)</li> </ul>"},{"location":"e2e-tests/#lua-dynamic-certificates","title":"[Lua] dynamic certificates","text":"<ul> <li>picks up the certificate when we add TLS spec to existing ingress</li> <li>picks up the previously missing secret for a given ingress without reloading</li> <li>supports requests with domain with trailing dot</li> <li>picks up the updated certificate without reloading</li> <li>falls back to using default certificate when secret gets deleted without reloading</li> <li>picks up a non-certificate only change</li> <li>removes HTTPS configuration when we delete TLS spec</li> </ul>"},{"location":"e2e-tests/#lua-dynamic-configuration","title":"[Lua] dynamic configuration","text":"<ul> <li>configures balancer Lua middleware correctly</li> <li>handles endpoints only changes</li> <li>handles endpoints only changes (down scaling of replicas)</li> <li>handles endpoints only changes consistently (down scaling of replicas vs. empty service)</li> <li>handles an annotation change</li> </ul>"},{"location":"e2e-tests/#metrics-exported-prometheus-metrics","title":"[metrics] exported prometheus metrics","text":"<ul> <li>exclude socket request metrics are absent</li> <li>exclude socket request metrics are present</li> </ul>"},{"location":"e2e-tests/#nginx-configuration","title":"nginx-configuration","text":"<ul> <li>start nginx with default configuration</li> <li>fails when using alias directive</li> <li>fails when using root directive</li> </ul>"},{"location":"e2e-tests/#security-request-smuggling","title":"[Security] request smuggling","text":"<ul> <li>should not return body content from error_page</li> </ul>"},{"location":"e2e-tests/#service-backend-status-code-503","title":"[Service] backend status code 503","text":"<ul> <li>should return 503 when backend service does not exist</li> <li>should return 503 when all backend service endpoints are unavailable</li> </ul>"},{"location":"e2e-tests/#service-type-externalname","title":"[Service] Type ExternalName","text":"<ul> <li>works with external name set to incomplete fqdn</li> <li>should return 200 for service type=ExternalName without a port defined</li> <li>should return 200 for service type=ExternalName with a port defined</li> <li>should return status 502 for service type=ExternalName with an invalid host</li> <li>should return 200 for service type=ExternalName using a port name</li> <li>should return 200 for service type=ExternalName using FQDN with trailing dot</li> <li>should update the external name after a service update</li> <li>should sync ingress on external name service addition/deletion</li> </ul>"},{"location":"e2e-tests/#service-nil-service-backend","title":"[Service] Nil Service Backend","text":"<ul> <li>should return 404 when backend service is nil</li> </ul>"},{"location":"e2e-tests/#access-log","title":"access-log","text":"<ul> <li>use the default configuration</li> <li>use the specified configuration</li> <li>use the specified configuration</li> <li>use the specified configuration</li> <li>use the specified configuration</li> </ul>"},{"location":"e2e-tests/#aio-write","title":"aio-write","text":"<ul> <li>should be enabled by default</li> <li>should be enabled when setting is true</li> <li>should be disabled when setting is false</li> </ul>"},{"location":"e2e-tests/#bad-annotation-values","title":"Bad annotation values","text":"<ul> <li>[BAD_ANNOTATIONS] should drop an ingress if there is an invalid character in some annotation</li> <li>[BAD_ANNOTATIONS] should drop an ingress if there is a forbidden word in some annotation</li> <li>[BAD_ANNOTATIONS] should allow an ingress if there is a default blocklist config in place</li> <li>[BAD_ANNOTATIONS] should drop an ingress if there is a custom blocklist config in place and allow others to pass</li> </ul>"},{"location":"e2e-tests/#brotli","title":"brotli","text":"<ul> <li>should only compress responses that meet the <code>brotli-min-length</code> condition</li> </ul>"},{"location":"e2e-tests/#configmap-change","title":"Configmap change","text":"<ul> <li>should reload after an update in the configuration</li> </ul>"},{"location":"e2e-tests/#add-headers","title":"add-headers","text":"<ul> <li>Add a custom header</li> <li>Add multiple custom headers</li> </ul>"},{"location":"e2e-tests/#ssl-flag-default-ssl-certificate","title":"[SSL] [Flag] default-ssl-certificate","text":"<ul> <li>uses default ssl certificate for catch-all ingress</li> <li>uses default ssl certificate for host based ingress when configured certificate does not match host</li> </ul>"},{"location":"e2e-tests/#flag-disable-catch-all","title":"[Flag] disable-catch-all","text":"<ul> <li>should ignore catch all Ingress with backend</li> <li>should ignore catch all Ingress with backend and rules</li> <li>should delete Ingress updated to catch-all</li> <li>should allow Ingress with rules</li> </ul>"},{"location":"e2e-tests/#flag-disable-service-external-name","title":"[Flag] disable-service-external-name","text":"<ul> <li>should ignore services of external-name type</li> </ul>"},{"location":"e2e-tests/#flag-disable-sync-events","title":"[Flag] disable-sync-events","text":"<ul> <li>should create sync events (default)</li> <li>should create sync events</li> <li>should not create sync events</li> </ul>"},{"location":"e2e-tests/#enable-real-ip","title":"enable-real-ip","text":"<ul> <li>trusts X-Forwarded-For header only when setting is true</li> <li>should not trust X-Forwarded-For header when setting is false</li> </ul>"},{"location":"e2e-tests/#use-forwarded-headers","title":"use-forwarded-headers","text":"<ul> <li>should trust X-Forwarded headers when setting is true</li> <li>should not trust X-Forwarded headers when setting is false</li> </ul>"},{"location":"e2e-tests/#geoip2","title":"Geoip2","text":"<ul> <li>should include geoip2 line in config when enabled and db file exists</li> <li>should only allow requests from specific countries</li> </ul>"},{"location":"e2e-tests/#security-block-","title":"[Security] block-*","text":"<ul> <li>should block CIDRs defined in the ConfigMap</li> <li>should block User-Agents defined in the ConfigMap</li> <li>should block Referers defined in the ConfigMap</li> </ul>"},{"location":"e2e-tests/#security-global-auth-url","title":"[Security] global-auth-url","text":"<ul> <li>should return status code 401 when request any protected service</li> <li>should return status code 200 when request whitelisted (via no-auth-locations) service and 401 when request protected service</li> <li>should return status code 200 when request whitelisted (via ingress annotation) service and 401 when request protected service</li> <li>should still return status code 200 after auth backend is deleted using cache</li> <li>user retains cookie by default</li> <li>user does not retain cookie if upstream returns error status code</li> <li>user with global-auth-always-set-cookie key in configmap retains cookie if upstream returns error status code</li> </ul>"},{"location":"e2e-tests/#global-options","title":"global-options","text":"<ul> <li>should have worker_rlimit_nofile option</li> <li>should have worker_rlimit_nofile option and be independent on amount of worker processes</li> </ul>"},{"location":"e2e-tests/#settings-global-rate-limit","title":"settings-global-rate-limit","text":"<ul> <li>generates correct NGINX configuration</li> </ul>"},{"location":"e2e-tests/#gzip","title":"gzip","text":"<ul> <li>should be disabled by default</li> <li>should be enabled with default settings</li> <li>should set gzip_comp_level to 4</li> <li>should set gzip_disable to msie6</li> <li>should set gzip_min_length to 100</li> <li>should set gzip_types to text/html</li> </ul>"},{"location":"e2e-tests/#hash-size","title":"hash size","text":"<ul> <li>should set server_names_hash_bucket_size</li> <li>should set server_names_hash_max_size</li> <li>should set proxy-headers-hash-bucket-size</li> <li>should set proxy-headers-hash-max-size</li> <li>should set variables-hash-bucket-size</li> <li>should set variables-hash-max-size</li> <li>should set vmap-hash-bucket-size</li> </ul>"},{"location":"e2e-tests/#flag-ingress-class","title":"[Flag] ingress-class","text":"<ul> <li>should ignore Ingress with a different class annotation</li> <li>should ignore Ingress with different controller class</li> <li>should accept both Ingresses with default IngressClassName and IngressClass annotation</li> <li>should ignore Ingress without IngressClass configuration</li> <li>should delete Ingress when class is removed</li> <li>should serve Ingress when class is added</li> <li>should serve Ingress when class is updated between annotation and ingressClassName</li> <li>should ignore Ingress with no class and accept the correctly configured Ingresses</li> <li>should watch Ingress with no class and ignore ingress with a different class</li> <li>should watch Ingress that uses the class name even if spec is different</li> <li>should watch Ingress with correct annotation</li> <li>should ignore Ingress with only IngressClassName</li> </ul>"},{"location":"e2e-tests/#keep-alive-keep-alive-requests","title":"keep-alive keep-alive-requests","text":"<ul> <li>should set keepalive_timeout</li> <li>should set keepalive_requests</li> <li>should set keepalive connection to upstream server</li> <li>should set keep alive connection timeout to upstream server</li> <li>should set keepalive time to upstream server</li> <li>should set the request count to upstream server through one keep alive connection</li> </ul>"},{"location":"e2e-tests/#configmap-limit-rate","title":"Configmap - limit-rate","text":"<ul> <li>Check limit-rate config</li> </ul>"},{"location":"e2e-tests/#flag-custom-http-and-https-ports","title":"[Flag] custom HTTP and HTTPS ports","text":"<ul> <li>should set X-Forwarded-Port headers accordingly when listening on a non-default HTTP port</li> <li>should set X-Forwarded-Port header to 443</li> <li>should set the X-Forwarded-Port header to 443</li> </ul>"},{"location":"e2e-tests/#log-format-","title":"log-format-*","text":"<ul> <li>should not configure log-format escape by default</li> <li>should enable the log-format-escape-json</li> <li>should disable the log-format-escape-json</li> <li>should enable the log-format-escape-none</li> <li>should disable the log-format-escape-none</li> <li>log-format-escape-json enabled</li> <li>log-format default escape</li> <li>log-format-escape-none enabled</li> </ul>"},{"location":"e2e-tests/#lua-lua-shared-dicts","title":"[Lua] lua-shared-dicts","text":"<ul> <li>configures lua shared dicts</li> </ul>"},{"location":"e2e-tests/#main-snippet","title":"main-snippet","text":"<ul> <li>should add value of main-snippet setting to nginx config</li> </ul>"},{"location":"e2e-tests/#security-modsecurity-snippet","title":"[Security] modsecurity-snippet","text":"<ul> <li>should add value of modsecurity-snippet setting to nginx config</li> </ul>"},{"location":"e2e-tests/#enable-multi-accept","title":"enable-multi-accept","text":"<ul> <li>should be enabled by default</li> <li>should be enabled when set to true</li> <li>should be disabled when set to false</li> </ul>"},{"location":"e2e-tests/#flag-watch-namespace-selector","title":"[Flag] watch namespace selector","text":"<ul> <li>should ignore Ingress of namespace without label foo=bar and accept those of namespace with label foo=bar</li> </ul>"},{"location":"e2e-tests/#security-no-auth-locations","title":"[Security] no-auth-locations","text":"<ul> <li>should return status code 401 when accessing '/' unauthentication</li> <li>should return status code 200 when accessing '/'  authentication</li> <li>should return status code 200 when accessing '/noauth' unauthenticated</li> </ul>"},{"location":"e2e-tests/#add-no-tls-redirect-locations","title":"Add no tls redirect locations","text":"<ul> <li>Check no tls redirect locations config</li> </ul>"},{"location":"e2e-tests/#ocsp","title":"OCSP","text":"<ul> <li>should enable OCSP and contain stapling information in the connection</li> </ul>"},{"location":"e2e-tests/#configure-opentelemetry","title":"Configure Opentelemetry","text":"<ul> <li>should not exists opentelemetry directive</li> <li>should exists opentelemetry directive when is enabled</li> <li>should include opentelemetry_trust_incoming_spans on directive when enabled</li> <li>should not exists opentelemetry_operation_name directive when is empty</li> <li>should exists opentelemetry_operation_name directive when is configured</li> </ul>"},{"location":"e2e-tests/#plugins","title":"plugins","text":"<ul> <li>should exist a x-hello-world header</li> </ul>"},{"location":"e2e-tests/#proxy-connect-timeout","title":"proxy-connect-timeout","text":"<ul> <li>should set valid proxy timeouts using configmap values</li> <li>should not set invalid proxy timeouts using configmap values</li> </ul>"},{"location":"e2e-tests/#dynamic-proxy_host","title":"Dynamic $proxy_host","text":"<ul> <li>should exist a proxy_host</li> <li>should exist a proxy_host using the upstream-vhost annotation value</li> </ul>"},{"location":"e2e-tests/#proxy-next-upstream","title":"proxy-next-upstream","text":"<ul> <li>should build proxy next upstream using configmap values</li> </ul>"},{"location":"e2e-tests/#use-proxy-protocol","title":"use-proxy-protocol","text":"<ul> <li>should respect port passed by the PROXY Protocol</li> <li>should respect proto passed by the PROXY Protocol server port</li> <li>should enable PROXY Protocol for HTTPS</li> <li>should enable PROXY Protocol for TCP</li> </ul>"},{"location":"e2e-tests/#proxy-read-timeout","title":"proxy-read-timeout","text":"<ul> <li>should set valid proxy read timeouts using configmap values</li> <li>should not set invalid proxy read timeouts using configmap values</li> </ul>"},{"location":"e2e-tests/#proxy-send-timeout","title":"proxy-send-timeout","text":"<ul> <li>should set valid proxy send timeouts using configmap values</li> <li>should not set invalid proxy send timeouts using configmap values</li> </ul>"},{"location":"e2e-tests/#reuse-port","title":"reuse-port","text":"<ul> <li>reuse port should be enabled by default</li> <li>reuse port should be disabled</li> <li>reuse port should be enabled</li> </ul>"},{"location":"e2e-tests/#configmap-server-snippet","title":"configmap server-snippet","text":"<ul> <li>should add value of server-snippet setting to all ingress config</li> <li>should add global server-snippet and drop annotations per admin config</li> </ul>"},{"location":"e2e-tests/#server-tokens","title":"server-tokens","text":"<ul> <li>should not exists Server header in the response</li> <li>should exists Server header in the response when is enabled</li> </ul>"},{"location":"e2e-tests/#ssl-ciphers_1","title":"ssl-ciphers","text":"<ul> <li>Add ssl ciphers</li> </ul>"},{"location":"e2e-tests/#flag-enable-ssl-passthrough","title":"[Flag] enable-ssl-passthrough","text":""},{"location":"e2e-tests/#with-enable-ssl-passthrough-enabled","title":"With enable-ssl-passthrough enabled","text":"<ul> <li>should enable ssl-passthrough-proxy-port on a different port</li> <li>should pass unknown traffic to default backend and handle known traffic</li> </ul>"},{"location":"e2e-tests/#configmap-stream-snippet","title":"configmap stream-snippet","text":"<ul> <li>should add value of stream-snippet via config map to nginx config</li> </ul>"},{"location":"e2e-tests/#ssl-tls-protocols-ciphers-and-headers","title":"[SSL] TLS protocols, ciphers and headers)","text":"<ul> <li>setting cipher suite</li> <li>setting max-age parameter</li> <li>setting includeSubDomains parameter</li> <li>setting preload parameter</li> <li>overriding what's set from the upstream</li> <li>should not use ports during the HTTP to HTTPS redirection</li> <li>should not use ports or X-Forwarded-Host during the HTTP to HTTPS redirection</li> </ul>"},{"location":"e2e-tests/#annotation-validations","title":"annotation validations","text":"<ul> <li>should allow ingress based on their risk on webhooks</li> <li>should allow ingress based on their risk on webhooks</li> </ul>"},{"location":"e2e-tests/#ssl-redirect-to-https","title":"[SSL] redirect to HTTPS","text":"<ul> <li>should redirect from HTTP to HTTPS when secret is missing</li> </ul>"},{"location":"e2e-tests/#ssl-secret-update","title":"[SSL] secret update","text":"<ul> <li>should not appear references to secret updates not used in ingress rules</li> <li>should return the fake SSL certificate if the secret is invalid</li> </ul>"},{"location":"e2e-tests/#status-status-update","title":"[Status] status update","text":"<ul> <li>should update status field after client-go reconnection</li> </ul>"},{"location":"e2e-tests/#tcp-tcp-services","title":"[TCP] tcp-services","text":"<ul> <li>should expose a TCP service</li> <li>should expose an ExternalName TCP service</li> <li>should reload after an update in the configuration</li> </ul>"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#retaining-client-ipaddress","title":"Retaining Client IPAddress","text":"<p>Please read Retain Client IPAddress Guide here.</p>"},{"location":"faq/#kubernetes-v122-migration","title":"Kubernetes v1.22 Migration","text":"<p>If you are using Ingress objects in your cluster (running Kubernetes older than version 1.22), and you plan to upgrade your Kubernetes version to K8S 1.22 or above, then please read the migration guide here.</p>"},{"location":"faq/#validation-of-path","title":"Validation Of <code>path</code>","text":"<ul> <li> <p>For improving security and also following desired standards on Kubernetes API spec, the next release, scheduled for v1.8.0, will include a new &amp; optional feature of validating the value for the key <code>ingress.spec.rules.http.paths.path</code>.</p> </li> <li> <p>This behavior will be disabled by default on the 1.8.0 release and enabled by default on the next breaking change release, set for 2.0.0.</p> </li> <li> <p>When \"<code>ingress.spec.rules.http.pathType=Exact</code>\" or \"<code>pathType=Prefix</code>\", this validation will limit the characters accepted on the field \"<code>ingress.spec.rules.http.paths.path</code>\", to \"<code>alphanumeric characters</code>\", and  <code>\"/,\" \"_,\" \"-.\"</code> Also, in this case, the path should start with <code>\"/.\"</code></p> </li> <li> <p>When the ingress resource path contains other characters (like on rewrite configurations), the pathType value should be \"<code>ImplementationSpecific</code>\".</p> </li> <li> <p>API Spec on pathType is documented here</p> </li> <li> <p>When this option is enabled, the validation will happen on the Admission Webhook. So if any new ingress object contains characters other than alphanumeric characters, and, <code>\"/,\",\"_\",\"-\"</code>, in the <code>path</code> field, but is not using <code>pathType</code> value as <code>ImplementationSpecific</code>, then the ingress object will be denied admission.</p> </li> <li> <p>The cluster admin should establish validation rules using mechanisms like \"<code>Open Policy Agent</code>\", to validate that only authorized users can use ImplementationSpecific pathType and that only the authorized characters can be used. The configmap value is here</p> </li> <li> <p>A complete example of an Openpolicyagent gatekeeper rule is available here</p> </li> <li> <p>If you have any issues or concerns, please do one of the following:</p> </li> <li>Open a GitHub issue</li> <li>Comment in our Dev Slack Channel</li> <li>Open a thread in our Google Group ingress-nginx-dev@kubernetes.io</li> </ul>"},{"location":"faq/#why-is-chunking-not-working-since-controller-v110","title":"Why is chunking not working since controller v1.10 ?","text":"<ul> <li> <p>If your code is setting the HTTP header <code>\"Transfer-Encoding: chunked\"</code> and the controller log messages show an error about duplicate header, it is because of this change http://hg.nginx.org/nginx/rev/2bf7792c262e</p> </li> <li> <p>More details are available in this issue https://github.com/kubernetes/ingress-nginx/issues/11162</p> </li> </ul>"},{"location":"how-it-works/","title":"How it works","text":"<p>The objective of this document is to explain how the Ingress-NGINX controller works, in particular how the NGINX model is built and why we need one.</p>"},{"location":"how-it-works/#nginx-configuration","title":"NGINX configuration","text":"<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. Though it is important to note that we don't reload Nginx on changes that impact only an <code>upstream</code> configuration (i.e Endpoints change when you deploy your app). We use lua-nginx-module to achieve this. Check below to learn more about how it's done.</p>"},{"location":"how-it-works/#nginx-model","title":"NGINX model","text":"<p>Usually, a Kubernetes Controller utilizes the synchronization loop pattern 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 Kubernetes Informers, in particular, <code>FilteredSharedInformer</code>. These informers allow reacting to change in using callbacks 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 Go template using the new model as input for the variables required by the template.</p>"},{"location":"how-it-works/#building-the-nginx-model","title":"Building the NGINX model","text":"<p>Building a model is an expensive operation, for this reason, the use of the synchronization loop is a must. By using a work queue it is possible to not lose changes and remove the use of sync.Mutex 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 work queue.</p> <p>Operations to build the model:</p> <ul> <li> <p>Order Ingress rules by <code>CreationTimestamp</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> </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>"},{"location":"how-it-works/#when-a-reload-is-required","title":"When a reload is required","text":"<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>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>"},{"location":"how-it-works/#avoiding-reloads","title":"Avoiding reloads","text":"<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>"},{"location":"how-it-works/#avoiding-reloads-on-endpoints-changes","title":"Avoiding reloads on Endpoints changes","text":"<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 <code>balancer_by_lua</code> 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. Note that this includes annotation changes that affects only <code>upstream</code> configuration in Nginx as well.</p> <p>In a relatively big cluster 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>"},{"location":"how-it-works/#avoiding-outage-from-wrong-configuration","title":"Avoiding outage from wrong configuration","text":"<p>Because the ingress controller works using the synchronization loop pattern, 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>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>To prevent this situation to happen, the Ingress-Nginx Controller optionally exposes a validating admission webhook server 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>"},{"location":"kubectl-plugin/","title":"kubectl plugin","text":""},{"location":"kubectl-plugin/#the-ingress-nginx-kubectl-plugin","title":"The ingress-nginx kubectl plugin","text":""},{"location":"kubectl-plugin/#installation","title":"Installation","text":"<p>Install krew, then run</p> <pre><code>kubectl krew install ingress-nginx\n</code></pre> <p>to install the plugin. Then run</p> <pre><code>kubectl ingress-nginx --help\n</code></pre> <p>to make sure the plugin is properly installed and to get a list of commands:</p> <pre><code>kubectl ingress-nginx --help\nA kubectl plugin for inspecting your ingress-nginx deployments\n\nUsage:\n  ingress-nginx [command]\n\nAvailable Commands:\n  backends    Inspect the dynamic backend information of an ingress-nginx instance\n  certs       Output the certificate data stored in an ingress-nginx pod\n  conf        Inspect the generated nginx.conf\n  exec        Execute a command inside an ingress-nginx pod\n  general     Inspect the other dynamic ingress-nginx information\n  help        Help about any command\n  info        Show information about the ingress-nginx service\n  ingresses   Provide a short summary of all of the ingress definitions\n  lint        Inspect kubernetes resources for possible issues\n  logs        Get the kubernetes logs for an ingress-nginx pod\n  ssh         ssh into a running ingress-nginx pod\n\nFlags:\n      --as string                      Username to impersonate for the operation\n      --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.\n      --cache-dir string               Default HTTP cache directory (default \"/Users/alexkursell/.kube/http-cache\")\n      --certificate-authority string   Path to a cert file for the certificate authority\n      --client-certificate string      Path to a client certificate file for TLS\n      --client-key string              Path to a client key file for TLS\n      --cluster string                 The name of the kubeconfig cluster to use\n      --context string                 The name of the kubeconfig context to use\n  -h, --help                           help for ingress-nginx\n      --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.\n  -n, --namespace string               If present, the namespace scope for this CLI request\n      --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default \"0\")\n  -s, --server string                  The address and port of the Kubernetes API server\n      --token string                   Bearer token for authentication to the API server\n      --user string                    The name of the kubeconfig user to use\n\nUse \"ingress-nginx [command] --help\" for more information about a command.\n</code></pre>"},{"location":"kubectl-plugin/#common-flags","title":"Common Flags","text":"<ul> <li>Every subcommand supports the basic <code>kubectl</code> configuration flags like <code>--namespace</code>, <code>--context</code>, <code>--client-key</code> and so on.</li> <li>Subcommands that act on a particular <code>ingress-nginx</code> pod (<code>backends</code>, <code>certs</code>, <code>conf</code>, <code>exec</code>, <code>general</code>, <code>logs</code>, <code>ssh</code>), support the <code>--deployment &lt;deployment&gt;</code>, <code>--pod &lt;pod&gt;</code>, and <code>--container &lt;container&gt;</code> flags to select either a pod from a deployment with the given name, or a pod with the given name (and the given container name). The <code>--deployment</code> flag defaults to <code>ingress-nginx-controller</code>, and the <code>--container</code> flag defaults to <code>controller</code>.</li> <li>Subcommands that inspect resources (<code>ingresses</code>, <code>lint</code>) support the <code>--all-namespaces</code> flag, which causes them to inspect resources in every namespace.</li> </ul>"},{"location":"kubectl-plugin/#subcommands","title":"Subcommands","text":"<p>Note that <code>backends</code>, <code>general</code>, <code>certs</code>, and <code>conf</code> require <code>ingress-nginx</code> version <code>0.23.0</code> or higher.</p>"},{"location":"kubectl-plugin/#backends","title":"backends","text":"<p>Run <code>kubectl ingress-nginx backends</code> to get a JSON array of the backends that an ingress-nginx controller currently knows about:</p> <pre><code>$ kubectl ingress-nginx backends -n ingress-nginx\n[\n  {\n    \"name\": \"default-apple-service-5678\",\n    \"service\": {\n      \"metadata\": {\n        \"creationTimestamp\": null\n      },\n      \"spec\": {\n        \"ports\": [\n          {\n            \"protocol\": \"TCP\",\n            \"port\": 5678,\n            \"targetPort\": 5678\n          }\n        ],\n        \"selector\": {\n          \"app\": \"apple\"\n        },\n        \"clusterIP\": \"10.97.230.121\",\n        \"type\": \"ClusterIP\",\n        \"sessionAffinity\": \"None\"\n      },\n      \"status\": {\n        \"loadBalancer\": {}\n      }\n    },\n    \"port\": 0,\n    \"sslPassthrough\": false,\n    \"endpoints\": [\n      {\n        \"address\": \"10.1.3.86\",\n        \"port\": \"5678\"\n      }\n    ],\n    \"sessionAffinityConfig\": {\n      \"name\": \"\",\n      \"cookieSessionAffinity\": {\n        \"name\": \"\"\n      }\n    },\n    \"upstreamHashByConfig\": {\n      \"upstream-hash-by-subset-size\": 3\n    },\n    \"noServer\": false,\n    \"trafficShapingPolicy\": {\n      \"weight\": 0,\n      \"header\": \"\",\n      \"headerValue\": \"\",\n      \"cookie\": \"\"\n    }\n  },\n  {\n    \"name\": \"default-echo-service-8080\",\n    ...\n  },\n  {\n    \"name\": \"upstream-default-backend\",\n    ...\n  }\n]\n</code></pre> <p>Add the <code>--list</code> option to show only the backend names. Add the <code>--backend &lt;backend&gt;</code> option to show only the backend with the given name.</p>"},{"location":"kubectl-plugin/#certs","title":"certs","text":"<p>Use <code>kubectl ingress-nginx certs --host &lt;hostname&gt;</code> to dump the SSL cert/key information for a given host.</p> <p>WARNING: This command will dump sensitive private key information. Don't blindly share the output, and certainly don't log it anywhere.</p> <pre><code>$ kubectl ingress-nginx certs -n ingress-nginx --host testaddr.local\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n\n-----BEGIN RSA PRIVATE KEY-----\n&lt;REDACTED! DO NOT SHARE THIS!&gt;\n-----END RSA PRIVATE KEY-----\n</code></pre>"},{"location":"kubectl-plugin/#conf","title":"conf","text":"<p>Use <code>kubectl ingress-nginx conf</code> to dump the generated <code>nginx.conf</code> file. Add the <code>--host &lt;hostname&gt;</code> option to view only the server block for that host:</p> <pre><code>kubectl ingress-nginx conf -n ingress-nginx --host testaddr.local\n\n    server {\n        server_name testaddr.local ;\n\n        listen 80;\n\n        set $proxy_upstream_name \"-\";\n        set $pass_access_scheme $scheme;\n        set $pass_server_port $server_port;\n        set $best_http_host $http_host;\n        set $pass_port $pass_server_port;\n\n        location / {\n\n            set $namespace      \"\";\n            set $ingress_name   \"\";\n            set $service_name   \"\";\n            set $service_port   \"0\";\n            set $location_path  \"/\";\n\n...\n</code></pre>"},{"location":"kubectl-plugin/#exec","title":"exec","text":"<p><code>kubectl ingress-nginx exec</code> is exactly the same as <code>kubectl exec</code>, with the same command flags. It will automatically choose an <code>ingress-nginx</code> pod to run the command in.</p> <pre><code>$ kubectl ingress-nginx exec -i -n ingress-nginx -- ls /etc/nginx\nfastcgi_params\ngeoip\nlua\nmime.types\nmodsecurity\nmodules\nnginx.conf\nopentracing.json\nopentelemetry.toml\nowasp-modsecurity-crs\ntemplate\n</code></pre>"},{"location":"kubectl-plugin/#info","title":"info","text":"<p>Shows the internal and external IP/CNAMES for an <code>ingress-nginx</code> service.</p> <pre><code>$ kubectl ingress-nginx info -n ingress-nginx\nService cluster IP address: 10.187.253.31\nLoadBalancer IP|CNAME: 35.123.123.123\n</code></pre> <p>Use the <code>--service &lt;service&gt;</code> flag if your <code>ingress-nginx</code> <code>LoadBalancer</code> service is not named <code>ingress-nginx</code>.</p>"},{"location":"kubectl-plugin/#ingresses","title":"ingresses","text":"<p><code>kubectl ingress-nginx ingresses</code>, alternately <code>kubectl ingress-nginx ing</code>, shows a more detailed view of the ingress definitions in a namespace.</p> <p>Compare:</p> <pre><code>$ kubectl get ingresses --all-namespaces\nNAMESPACE   NAME               HOSTS                            ADDRESS     PORTS   AGE\ndefault     example-ingress1   testaddr.local,testaddr2.local   localhost   80      5d\ndefault     test-ingress-2     *                                localhost   80      5d\n</code></pre> <p>vs.</p> <pre><code>$ kubectl ingress-nginx ingresses --all-namespaces\nNAMESPACE   INGRESS NAME       HOST+PATH                        ADDRESSES   TLS   SERVICE         SERVICE PORT   ENDPOINTS\ndefault     example-ingress1   testaddr.local/etameta           localhost   NO    pear-service    5678           5\ndefault     example-ingress1   testaddr2.local/otherpath        localhost   NO    apple-service   5678           1\ndefault     example-ingress1   testaddr2.local/otherotherpath   localhost   NO    pear-service    5678           5\ndefault     test-ingress-2     *                                localhost   NO    echo-service    8080           2\n</code></pre>"},{"location":"kubectl-plugin/#lint","title":"lint","text":"<p><code>kubectl ingress-nginx lint</code> can check a namespace or entire cluster for potential configuration issues. This command is especially useful when upgrading between <code>ingress-nginx</code> versions.</p> <pre><code>$ kubectl ingress-nginx lint --all-namespaces --verbose\nChecking ingresses...\n\u2717 anamespace/this-nginx\n  - Contains the removed session-cookie-hash annotation.\n       Lint added for version 0.24.0\n       https://github.com/kubernetes/ingress-nginx/issues/3743\n\u2717 othernamespace/ingress-definition-blah\n  - The rewrite-target annotation value does not reference a capture group\n      Lint added for version 0.22.0\n      https://github.com/kubernetes/ingress-nginx/issues/3174\n\nChecking deployments...\n\u2717 namespace2/ingress-nginx-controller\n  - Uses removed config flag --sort-backends\n      Lint added for version 0.22.0\n      https://github.com/kubernetes/ingress-nginx/issues/3655\n  - Uses removed config flag --enable-dynamic-certificates\n      Lint added for version 0.24.0\n      https://github.com/kubernetes/ingress-nginx/issues/3808\n</code></pre> <p>To show the lints added only for a particular <code>ingress-nginx</code> release, use the <code>--from-version</code> and <code>--to-version</code> flags:</p> <pre><code>$ kubectl ingress-nginx lint --all-namespaces --verbose --from-version 0.24.0 --to-version 0.24.0\nChecking ingresses...\n\u2717 anamespace/this-nginx\n  - Contains the removed session-cookie-hash annotation.\n       Lint added for version 0.24.0\n       https://github.com/kubernetes/ingress-nginx/issues/3743\n\nChecking deployments...\n\u2717 namespace2/ingress-nginx-controller\n  - Uses removed config flag --enable-dynamic-certificates\n      Lint added for version 0.24.0\n      https://github.com/kubernetes/ingress-nginx/issues/3808\n</code></pre>"},{"location":"kubectl-plugin/#logs","title":"logs","text":"<p><code>kubectl ingress-nginx logs</code> is almost the same as <code>kubectl logs</code>, with fewer flags. It will automatically choose an <code>ingress-nginx</code> pod to read logs from.</p> <pre><code>$ kubectl ingress-nginx logs -n ingress-nginx\n-------------------------------------------------------------------------------\nNGINX Ingress controller\n  Release:    dev\n  Build:      git-48dc3a867\n  Repository: git@github.com:kubernetes/ingress-nginx.git\n-------------------------------------------------------------------------------\n\nW0405 16:53:46.061589       7 flags.go:214] SSL certificate chain completion is disabled (--enable-ssl-chain-completion=false)\nnginx version: nginx/1.15.9\nW0405 16:53:46.070093       7 client_config.go:549] Neither --kubeconfig nor --master was specified.  Using the inClusterConfig.  This might not work.\nI0405 16:53:46.070499       7 main.go:205] Creating API client for https://10.96.0.1:443\nI0405 16:53:46.077784       7 main.go:249] Running in Kubernetes cluster version v1.10 (v1.10.11) - git (clean) commit 637c7e288581ee40ab4ca210618a89a555b6e7e9 - platform linux/amd64\nI0405 16:53:46.183359       7 nginx.go:265] Starting NGINX Ingress controller\nI0405 16:53:46.193913       7 event.go:209] Event(v1.ObjectReference{Kind:\"ConfigMap\", Namespace:\"ingress-nginx\", Name:\"udp-services\", UID:\"82258915-563e-11e9-9c52-025000000001\", APIVersion:\"v1\", ResourceVersion:\"494\", FieldPath:\"\"}): type: 'Normal' reason: 'CREATE' ConfigMap ingress-nginx/udp-services\n...\n</code></pre>"},{"location":"kubectl-plugin/#ssh","title":"ssh","text":"<p><code>kubectl ingress-nginx ssh</code> is exactly the same as <code>kubectl ingress-nginx exec -it -- /bin/bash</code>. Use it when you want to quickly be dropped into a shell inside a running <code>ingress-nginx</code> container.</p> <pre><code>$ kubectl ingress-nginx ssh -n ingress-nginx\nwww-data@ingress-nginx-controller-7cbf77c976-wx5pn:/etc/nginx$\n</code></pre>"},{"location":"lua_tests/","title":"Lua Tests","text":""},{"location":"lua_tests/#running-the-lua-tests","title":"Running the Lua Tests","text":"<p>To run the Lua tests you can run the following from the root directory:</p> <pre><code>make lua-test\n</code></pre> <p>This command makes use of docker hence does not need any dependency installations besides docker</p>"},{"location":"lua_tests/#where-are-the-lua-tests","title":"Where are the Lua Tests?","text":"<p>Lua Tests can be found in the rootfs/etc/nginx/lua/test directory</p>"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#troubleshooting","title":"Troubleshooting","text":""},{"location":"troubleshooting/#ingress-controller-logs-and-events","title":"Ingress-Controller Logs and Events","text":"<p>There are many ways to troubleshoot the ingress-controller. The following are basic troubleshooting methods to obtain more information.</p>"},{"location":"troubleshooting/#check-the-ingress-resource-events","title":"Check the Ingress Resource Events","text":"<pre><code>$ kubectl get ing -n &lt;namespace-of-ingress-resource&gt;\nNAME           HOSTS      ADDRESS     PORTS     AGE\ncafe-ingress   cafe.com   10.0.2.15   80        25s\n\n$ kubectl describe ing &lt;ingress-resource-name&gt; -n &lt;namespace-of-ingress-resource&gt;\nName:             cafe-ingress\nNamespace:        default\nAddress:          10.0.2.15\nDefault backend:  default-http-backend:80 (172.17.0.5:8080)\nRules:\n  Host      Path  Backends\n  ----      ----  --------\n  cafe.com\n            /tea      tea-svc:80 (&lt;none&gt;)\n            /coffee   coffee-svc:80 (&lt;none&gt;)\nAnnotations:\n  kubectl.kubernetes.io/last-applied-configuration:  {\"apiVersion\":\"networking.k8s.io/v1\",\"kind\":\"Ingress\",\"metadata\":{\"annotations\":{},\"name\":\"cafe-ingress\",\"namespace\":\"default\",\"selfLink\":\"/apis/networking/v1/namespaces/default/ingresses/cafe-ingress\"},\"spec\":{\"rules\":[{\"host\":\"cafe.com\",\"http\":{\"paths\":[{\"backend\":{\"serviceName\":\"tea-svc\",\"servicePort\":80},\"path\":\"/tea\"},{\"backend\":{\"serviceName\":\"coffee-svc\",\"servicePort\":80},\"path\":\"/coffee\"}]}}]},\"status\":{\"loadBalancer\":{\"ingress\":[{\"ip\":\"169.48.142.110\"}]}}}\n\nEvents:\n  Type    Reason  Age   From                      Message\n  ----    ------  ----  ----                      -------\n  Normal  CREATE  1m    ingress-nginx-controller  Ingress default/cafe-ingress\n  Normal  UPDATE  58s   ingress-nginx-controller  Ingress default/cafe-ingress\n</code></pre>"},{"location":"troubleshooting/#check-the-ingress-controller-logs","title":"Check the Ingress Controller Logs","text":"<pre><code>$ kubectl get pods -n &lt;namespace-of-ingress-controller&gt;\nNAME                                        READY     STATUS    RESTARTS   AGE\ningress-nginx-controller-67956bf89d-fv58j   1/1       Running   0          1m\n\n$ kubectl logs -n &lt;namespace&gt; ingress-nginx-controller-67956bf89d-fv58j\n-------------------------------------------------------------------------------\nNGINX Ingress controller\n  Release:    0.14.0\n  Build:      git-734361d\n  Repository: https://github.com/kubernetes/ingress-nginx\n-------------------------------------------------------------------------------\n....\n</code></pre>"},{"location":"troubleshooting/#check-the-nginx-configuration","title":"Check the Nginx Configuration","text":"<pre><code>$ kubectl get pods -n &lt;namespace-of-ingress-controller&gt;\nNAME                                        READY     STATUS    RESTARTS   AGE\ningress-nginx-controller-67956bf89d-fv58j   1/1       Running   0          1m\n\n$ kubectl exec -it -n &lt;namespace-of-ingress-controller&gt; ingress-nginx-controller-67956bf89d-fv58j -- cat /etc/nginx/nginx.conf\ndaemon off;\nworker_processes 2;\npid /run/nginx.pid;\nworker_rlimit_nofile 523264;\nworker_shutdown_timeout 240s;\nevents {\n    multi_accept        on;\n    worker_connections  16384;\n    use                 epoll;\n}\nhttp {\n....\n</code></pre>"},{"location":"troubleshooting/#check-if-used-services-exist","title":"Check if used Services Exist","text":"<pre><code>$ kubectl get svc --all-namespaces\nNAMESPACE     NAME                   TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)         AGE\ndefault       coffee-svc             ClusterIP   10.106.154.35    &lt;none&gt;        80/TCP          18m\ndefault       kubernetes             ClusterIP   10.96.0.1        &lt;none&gt;        443/TCP         30m\ndefault       tea-svc                ClusterIP   10.104.172.12    &lt;none&gt;        80/TCP          18m\nkube-system   default-http-backend   NodePort    10.108.189.236   &lt;none&gt;        80:30001/TCP    30m\nkube-system   kube-dns               ClusterIP   10.96.0.10       &lt;none&gt;        53/UDP,53/TCP   30m\nkube-system   kubernetes-dashboard   NodePort    10.103.128.17    &lt;none&gt;        80:30000/TCP    30m\n</code></pre>"},{"location":"troubleshooting/#debug-logging","title":"Debug Logging","text":"<p>Using the flag <code>--v=XX</code> it is possible to increase the level of logging. This is performed by editing the deployment.</p> <pre><code>$ kubectl get deploy -n &lt;namespace-of-ingress-controller&gt;\nNAME                       DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE\ndefault-http-backend       1         1         1            1           35m\ningress-nginx-controller   1         1         1            1           35m\n\n$ kubectl edit deploy -n &lt;namespace-of-ingress-controller&gt; ingress-nginx-controller\n# Add --v=X to \"- args\", where X is an integer\n</code></pre> <ul> <li><code>--v=2</code> shows details using <code>diff</code> about the changes in the configuration in nginx</li> <li><code>--v=3</code> shows details about the service, Ingress rule, endpoint changes and it dumps the nginx configuration in JSON format</li> <li><code>--v=5</code> configures NGINX in debug mode</li> </ul>"},{"location":"troubleshooting/#authentication-to-the-kubernetes-api-server","title":"Authentication to the Kubernetes API Server","text":"<p>A number of components are involved in the authentication process and the first step is to narrow down the source of the problem, namely whether it is a problem with service authentication or with the kubeconfig file.</p> <p>Both authentications must work:</p> <pre><code>+-------------+   service          +------------+\n|             |   authentication   |            |\n+  apiserver  +&lt;-------------------+  ingress   |\n|             |                    | controller |\n+-------------+                    +------------+\n</code></pre> <p>Service authentication</p> <p>The Ingress controller needs information from apiserver. Therefore, authentication is required, which can be achieved in a couple of ways:</p> <ul> <li> <p>Service Account: This is recommended, because nothing has to be configured. The Ingress controller will use information provided by the system to communicate with the API server. See 'Service Account' section for details.</p> </li> <li> <p>Kubeconfig file: In some Kubernetes environments service accounts are not available. In this case a manual configuration is required. The Ingress controller binary can be started with the <code>--kubeconfig</code> flag. The value of the flag is a path to a file specifying how to connect to the API server. Using the <code>--kubeconfig</code> does not requires the flag <code>--apiserver-host</code>.    The format of the file is identical to <code>~/.kube/config</code> which is used by kubectl to connect to the API server. See 'kubeconfig' section for details.</p> </li> <li> <p>Using the flag <code>--apiserver-host</code>: Using this flag <code>--apiserver-host=http://localhost:8080</code> it is possible to specify an unsecured API server or reach a remote kubernetes cluster using kubectl proxy.    Please do not use this approach in production.</p> </li> </ul> <p>In the diagram below you can see the full authentication flow with all options, starting with the browser on the lower left hand side.</p> <pre><code>Kubernetes                                                  Workstation\n+---------------------------------------------------+     +------------------+\n|                                                   |     |                  |\n|  +-----------+   apiserver        +------------+  |     |  +------------+  |\n|  |           |   proxy            |            |  |     |  |            |  |\n|  | apiserver |                    |  ingress   |  |     |  |  ingress   |  |\n|  |           |                    | controller |  |     |  | controller |  |\n|  |           |                    |            |  |     |  |            |  |\n|  |           |                    |            |  |     |  |            |  |\n|  |           |  service account/  |            |  |     |  |            |  |\n|  |           |  kubeconfig        |            |  |     |  |            |  |\n|  |           +&lt;-------------------+            |  |     |  |            |  |\n|  |           |                    |            |  |     |  |            |  |\n|  +------+----+      kubeconfig    +------+-----+  |     |  +------+-----+  |\n|         |&lt;--------------------------------------------------------|        |\n|                                                   |     |                  |\n+---------------------------------------------------+     +------------------+\n</code></pre>"},{"location":"troubleshooting/#service-account","title":"Service Account","text":"<p>If using a service account to connect to the API server, the ingress-controller expects the file <code>/var/run/secrets/kubernetes.io/serviceaccount/token</code> to be present. It provides a secret token that is required to authenticate with the API server.</p> <p>Verify with the following commands:</p> <pre><code># start a container that contains curl\n$ kubectl run -it --rm test --image=curlimages/curl --restart=Never -- /bin/sh\n\n# check if secret exists\n/ $ ls /var/run/secrets/kubernetes.io/serviceaccount/\nca.crt     namespace  token\n/ $\n\n# check base connectivity from cluster inside\n/ $ curl -k https://kubernetes.default.svc.cluster.local\n{\n  \"kind\": \"Status\",\n  \"apiVersion\": \"v1\",\n  \"metadata\": {\n\n  },\n  \"status\": \"Failure\",\n  \"message\": \"forbidden: User \\\"system:anonymous\\\" cannot get path \\\"/\\\"\",\n  \"reason\": \"Forbidden\",\n  \"details\": {\n\n  },\n  \"code\": 403\n}/ $\n\n# connect using tokens\n}/ $ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt -H  \"Authorization: Bearer $(cat /var/run/secrets/kubernetes.io/serviceaccount/token)\" https://kubernetes.default.svc.cluster.local\n&amp;&amp; echo\n{\n  \"paths\": [\n    \"/api\",\n    \"/api/v1\",\n    \"/apis\",\n    \"/apis/\",\n    ... TRUNCATED\n    \"/readyz/shutdown\",\n    \"/version\"\n  ]\n}\n/ $\n\n# when you type `exit` or `^D` the test pod will be deleted.\n</code></pre> <p>If it is not working, there are two possible reasons:</p> <ol> <li> <p>The contents of the tokens are invalid. Find the secret name with <code>kubectl get secrets | grep service-account</code> and    delete it with <code>kubectl delete secret &lt;name&gt;</code>. It will automatically be recreated.</p> </li> <li> <p>You have a non-standard Kubernetes installation and the file containing the token may not be present.    The API server will mount a volume containing this file, but only if the API server is configured to use    the ServiceAccount admission controller.    If you experience this error, verify that your API server is using the ServiceAccount admission controller.    If you are configuring the API server by hand, you can set this with the <code>--admission-control</code> parameter.</p> <p>Note that you should use other admission controllers as well. Before configuring this option, you should read about admission controllers.</p> </li> </ol> <p>More information:</p> <ul> <li>User Guide: Service Accounts</li> <li>Cluster Administrator Guide: Managing Service Accounts</li> </ul>"},{"location":"troubleshooting/#kube-config","title":"Kube-Config","text":"<p>If you want to use a kubeconfig file for authentication, follow the deploy procedure and add the flag <code>--kubeconfig=/etc/kubernetes/kubeconfig.yaml</code> to the args section of the deployment.</p>"},{"location":"troubleshooting/#using-gdb-with-nginx","title":"Using GDB with Nginx","text":"<p>Gdb can be used to with nginx to perform a configuration dump. This allows us to see which configuration is being used, as well as older configurations.</p> <p>Note: The below is based on the nginx documentation.</p> <ol> <li> <p>SSH into the worker</p> <pre><code>$ ssh user@workerIP\n</code></pre> </li> <li> <p>Obtain the Docker Container Running nginx</p> <pre><code>$ docker ps | grep ingress-nginx-controller\nCONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES\nd9e1d243156a        registry.k8s.io/ingress-nginx/controller   \"/usr/bin/dumb-init \u2026\"   19 minutes ago      Up 19 minutes                                                                            k8s_ingress-nginx-controller_ingress-nginx-controller-67956bf89d-mqxzt_kube-system_079f31ec-aa37-11e8-ad39-080027a227db_0\n</code></pre> </li> <li> <p>Exec into the container</p> <pre><code>$ docker exec -it --user=0 --privileged d9e1d243156a bash\n</code></pre> </li> <li> <p>Make sure nginx is running in <code>--with-debug</code></p> <pre><code>$ nginx -V 2&gt;&amp;1 | grep -- '--with-debug'\n</code></pre> </li> <li> <p>Get list of processes running on container</p> <pre><code>$ ps -ef\nUID        PID  PPID  C STIME TTY          TIME CMD\nroot         1     0  0 20:23 ?        00:00:00 /usr/bin/dumb-init /nginx-ingres\nroot         5     1  0 20:23 ?        00:00:05 /ingress-nginx-controller --defa\nroot        21     5  0 20:23 ?        00:00:00 nginx: master process /usr/sbin/\nnobody     106    21  0 20:23 ?        00:00:00 nginx: worker process\nnobody     107    21  0 20:23 ?        00:00:00 nginx: worker process\nroot       172     0  0 20:43 pts/0    00:00:00 bash\n</code></pre> </li> <li> <p>Attach gdb to the nginx master process</p> <pre><code>$ gdb -p 21\n....\nAttaching to process 21\nReading symbols from /usr/sbin/nginx...done.\n....\n(gdb)\n</code></pre> </li> <li> <p>Copy and paste the following:</p> <pre><code>set $cd = ngx_cycle-&gt;config_dump\nset $nelts = $cd.nelts\nset $elts = (ngx_conf_dump_t*)($cd.elts)\nwhile ($nelts-- &gt; 0)\nset $name = $elts[$nelts]-&gt;name.data\nprintf \"Dumping %s to nginx_conf.txt\\n\", $name\nappend memory nginx_conf.txt \\\n        $elts[$nelts]-&gt;buffer.start $elts[$nelts]-&gt;buffer.end\nend\n</code></pre> </li> <li> <p>Quit GDB by pressing CTRL+D</p> </li> <li> <p>Open nginx_conf.txt</p> <pre><code>cat nginx_conf.txt\n</code></pre> </li> </ol>"},{"location":"troubleshooting/#image-related-issues-faced-on-nginx-425-or-other-versions-helm-chart-versions","title":"Image related issues faced on Nginx 4.2.5 or other versions (Helm chart versions)","text":"<ol> <li> <p>Incase you face below error while installing Nginx using helm chart (either by helm commands or helm_release terraform provider )  <pre><code>Warning  Failed     5m5s (x4 over 6m34s)   kubelet            Failed to pull image \"registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.3.0@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": rpc error: code = Unknown desc = failed to pull and unpack image \"registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": failed to resolve reference \"registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": failed to do request: Head \"https://eu.gcr.io/v2/k8s-artifacts-prod/ingress-nginx/kube-webhook-certgen/manifests/sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\": EOF\n</code></pre>    Then please follow the below steps.</p> </li> <li> <p>During troubleshooting you can also execute the below commands to test the connectivities from you local machines and repositories  details</p> <p>a. curl registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47 &gt; /dev/null   <pre><code>(\u2388 |myprompt)\u279c  ~ curl registry.k8s.io/ingress-nginx/kube-webhook-certgen@sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47 &gt; /dev/null\n                    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n                                                    Dload  Upload   Total   Spent    Left  Speed\n                    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\n (\u2388 |myprompt)\u279c  ~\n</code></pre>   b. curl -I https://eu.gcr.io/v2/k8s-artifacts-prod/ingress-nginx/kube-webhook-certgen/manifests/sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47   <pre><code>(\u2388 |myprompt)\u279c  ~ curl -I https://eu.gcr.io/v2/k8s-artifacts-prod/ingress-nginx/kube-webhook-certgen/manifests/sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\n                                    HTTP/2 200\n                                    docker-distribution-api-version: registry/2.0\n                                    content-type: application/vnd.docker.distribution.manifest.list.v2+json\n                                    docker-content-digest: sha256:549e71a6ca248c5abd51cdb73dbc3083df62cf92ed5e6147c780e30f7e007a47\n                                    content-length: 1384\n                                    date: Wed, 28 Sep 2022 16:46:28 GMT\n                                    server: Docker Registry\n                                    x-xss-protection: 0\n                                    x-frame-options: SAMEORIGIN\n                                    alt-svc: h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"\n\n  (\u2388 |myprompt)\u279c  ~\n</code></pre>    Redirection in the proxy is implemented to ensure the pulling of the images.</p> </li> <li> <p>This is the solution recommended to whitelist the below image repositories :       <pre><code>*.appspot.com    \n*.k8s.io        \n*.pkg.dev\n*.gcr.io\n</code></pre>      More details about the above repos :       a. *.k8s.io -&gt; To ensure you can pull any images from registry.k8s.io      b. *.gcr.io -&gt; GCP services are used for image hosting. This is part of the domains suggested by GCP to allow and ensure users can pull images from their container registry services.      c. *.appspot.com -&gt; This a Google domain. part of the domain used for GCR.</p> </li> </ol>"},{"location":"troubleshooting/#unable-to-listen-on-port-80443","title":"Unable to listen on port (80/443)","text":"<p>One possible reason for this error is lack of permission to bind to the port.  Ports 80, 443, and any other port &lt; 1024 are Linux privileged ports which historically could only be bound by root.  The ingress-nginx-controller uses the CAP_NET_BIND_SERVICE linux capability to allow binding these ports as a normal user (www-data / 101).  This involves two components: 1. In the image, the /nginx-ingress-controller file has the cap_net_bind_service capability added (e.g. via setcap)  2. The NET_BIND_SERVICE capability is added to the container in the containerSecurityContext of the deployment.</p> <p>If encountering this on one/some node(s) and not on others, try to purge and pull a fresh copy of the image to the affected node(s), in case there has been corruption of the underlying layers to lose the capability on the executable.</p>"},{"location":"troubleshooting/#create-a-test-pod","title":"Create a test pod","text":"<p>The /nginx-ingress-controller process exits/crashes when encountering this error, making it difficult to troubleshoot what is happening inside the container.  To get around this, start an equivalent container running \"sleep 3600\", and exec into it for further troubleshooting.  For example: <pre><code>apiVersion: v1\nkind: Pod\nmetadata:\n  name: ingress-nginx-sleep\n  namespace: default\n  labels:\n    app: nginx\nspec:\n  containers:\n    - name: nginx\n      image: ##_CONTROLLER_IMAGE_##\n      resources:\n        requests:\n          memory: \"512Mi\"\n          cpu: \"500m\"\n        limits:\n          memory: \"1Gi\"\n          cpu: \"1\"\n      command: [\"sleep\"]\n      args: [\"3600\"]\n      ports:\n      - containerPort: 80\n        name: http\n        protocol: TCP\n      - containerPort: 443\n        name: https\n        protocol: TCP\n      securityContext:\n        allowPrivilegeEscalation: true\n        capabilities:\n          add:\n          - NET_BIND_SERVICE\n          drop:\n          - ALL\n        runAsUser: 101\n  restartPolicy: Never\n  nodeSelector:\n    kubernetes.io/hostname: ##_NODE_NAME_##\n  tolerations:\n  - key: \"node.kubernetes.io/unschedulable\"\n    operator: \"Exists\"\n    effect: NoSchedule\n</code></pre> * update the namespace if applicable/desired * replace <code>##_NODE_NAME_##</code> with the problematic node (or remove nodeSelector section if problem is not confined to one node) * replace <code>##_CONTROLLER_IMAGE_##</code> with the same image as in use by your ingress-nginx deployment * confirm the securityContext section matches what is in place for ingress-nginx-controller pods in your cluster</p> <p>Apply the YAML and open a shell into the pod. Try to manually run the controller process: <pre><code>$ /nginx-ingress-controller\n</code></pre> You should get the same error as from the ingress controller pod logs.</p> <p>Confirm the capabilities are properly surfacing into the pod: <pre><code>$ grep CapBnd /proc/1/status\nCapBnd: 0000000000000400\n</code></pre> The above value has only net_bind_service enabled (per security context in YAML which adds that and drops all). If you get a different value, then you can decode it on another linux box (capsh not available in this container) like below, and then figure out why specified capabilities are not propagating into the pod/container. <pre><code>$ capsh --decode=0000000000000400\n0x0000000000000400=cap_net_bind_service\n</code></pre></p>"},{"location":"troubleshooting/#create-a-test-pod-as-root","title":"Create a test pod as root","text":"<p>(Note, this may be restricted by PodSecurityPolicy, PodSecurityAdmission/Standards, OPA Gatekeeper, etc. in which case you will need to do the appropriate workaround for testing, e.g. deploy in a new namespace without the restrictions.) To test further you may want to install additional utilities, etc.  Modify the pod yaml by: * changing runAsUser from 101 to 0 * removing the \"drop..ALL\" section from the capabilities.</p> <p>Some things to try after shelling into this container:</p> <p>Try running the controller as the www-data (101) user: <pre><code>$ chmod 4755 /nginx-ingress-controller\n$ /nginx-ingress-controller\n</code></pre> Examine the errors to see if there is still an issue listening on the port or if it passed that and moved on to other expected errors due to running out of context.</p> <p>Install the libcap package and check capabilities on the file: <pre><code>$ apk add libcap\n(1/1) Installing libcap (2.50-r0)\nExecuting busybox-1.33.1-r7.trigger\nOK: 26 MiB in 41 packages\n$ getcap /nginx-ingress-controller\n/nginx-ingress-controller cap_net_bind_service=ep\n</code></pre> (if missing, see above about purging image on the server and re-pulling)</p> <p>Strace the executable to see what system calls are being executed when it fails: <pre><code>$ apk add strace\n(1/1) Installing strace (5.12-r0)\nExecuting busybox-1.33.1-r7.trigger\nOK: 28 MiB in 42 packages\n$ strace /nginx-ingress-controller\nexecve(\"/nginx-ingress-controller\", [\"/nginx-ingress-controller\"], 0x7ffeb9eb3240 /* 131 vars */) = 0\narch_prctl(ARCH_SET_FS, 0x29ea690)      = 0\n...\n</code></pre></p>"},{"location":"deploy/","title":"Installation Guide","text":"<p>There are multiple ways to install the Ingress-Nginx Controller:</p> <ul> <li>with Helm, using the project repository chart;</li> <li>with <code>kubectl apply</code>, using YAML manifests;</li> <li>with specific addons (e.g. for minikube or MicroK8s).</li> </ul> <p>On most Kubernetes clusters, the ingress controller will work without requiring any extra configuration. If you want to  get started as fast as possible, you can check the quick start instructions. However, in many  environments, you can improve the performance or get better logs by enabling extra features. We recommend that you  check the environment-specific instructions for details about optimizing the  ingress controller for your particular environment or cloud provider.</p>"},{"location":"deploy/#contents","title":"Contents","text":"<ul> <li> <p>Quick start</p> </li> <li> <p>Environment-specific instructions</p> </li> <li>... Docker Desktop</li> <li>... Rancher Desktop</li> <li>... minikube</li> <li>... MicroK8s</li> <li>... AWS</li> <li>... GCE - GKE</li> <li>... Azure</li> <li>... Digital Ocean</li> <li>... Scaleway</li> <li>... Exoscale</li> <li>... Oracle Cloud Infrastructure</li> <li>... OVHcloud</li> <li>... Bare-metal</li> <li>Miscellaneous</li> </ul>"},{"location":"deploy/#quick-start","title":"Quick start","text":"<p>If you have Helm, you can deploy the ingress controller with the following command:</p> <pre><code>helm upgrade --install ingress-nginx ingress-nginx \\\n  --repo https://kubernetes.github.io/ingress-nginx \\\n  --namespace ingress-nginx --create-namespace\n</code></pre> <p>It will install the controller in the <code>ingress-nginx</code> namespace, creating that namespace if it doesn't already exist.</p> <p>Info</p> <p>This command is idempotent:</p> <ul> <li>if the ingress controller is not installed, it will install it,</li> <li>if the ingress controller is already installed, it will upgrade it.</li> </ul> <p>If you want a full list of values that you can set, while installing with Helm, then run:</p> <pre><code>helm show values ingress-nginx --repo https://kubernetes.github.io/ingress-nginx\n</code></pre> <p>If you don't have Helm or if you prefer to use a YAML manifest, you can run the following command instead:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>Info</p> <p>The YAML manifest in the command above was generated with <code>helm template</code>, so you will end up with almost the same  resources as if you had used Helm to install the controller.</p> <p>Attention</p> <p>If you are running an old version of Kubernetes (1.18 or earlier), please read this paragraph for specific instructions. Because of api deprecations, the default manifest may not work on your cluster. Specific manifests for supported Kubernetes versions are available within a sub-folder of each provider.</p>"},{"location":"deploy/#firewall-configuration","title":"Firewall configuration","text":"<p>To check which ports are used by your installation of ingress-nginx, look at the output of <code>kubectl -n ingress-nginx get pod -o yaml</code>. In general, you need: - Port 8443 open between all hosts on which the kubernetes nodes are running. This is used for the ingress-nginx admission controller. - Port 80 (for HTTP) and/or 443 (for HTTPS) open to the public on the kubernetes nodes to which the DNS of your apps are pointing.</p>"},{"location":"deploy/#pre-flight-check","title":"Pre-flight check","text":"<p>A few pods should start in the <code>ingress-nginx</code> namespace:</p> <pre><code>kubectl get pods --namespace=ingress-nginx\n</code></pre> <p>After a while, they should all be running. The following command will wait for the ingress controller pod to be up,  running, and ready:</p> <pre><code>kubectl wait --namespace ingress-nginx \\\n  --for=condition=ready pod \\\n  --selector=app.kubernetes.io/component=controller \\\n  --timeout=120s\n</code></pre>"},{"location":"deploy/#local-testing","title":"Local testing","text":"<p>Let's create a simple web server and the associated service:</p> <pre><code>kubectl create deployment demo --image=httpd --port=80\nkubectl expose deployment demo\n</code></pre> <p>Then create an ingress resource. The following example uses a host that maps to <code>localhost</code>:</p> <pre><code>kubectl create ingress demo-localhost --class=nginx \\\n  --rule=\"demo.localdev.me/*=demo:80\"\n</code></pre> <p>Now, forward a local port to the ingress controller:</p> <pre><code>kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8080:80\n</code></pre> <p>Info</p> <p>A note on DNS &amp; network-connection. This documentation assumes that a user has awareness of the DNS and the network routing aspects involved in using ingress. The port-forwarding mentioned above, is the easiest way to demo the working of ingress. The \"kubectl port-forward...\" command above has forwarded the port number 8080, on the localhost's tcp/ip stack, where the command was typed, to the port  number 80, of the service created by the installation of ingress-nginx controller. So now, the traffic sent to port number 8080 on localhost will reach the port number 80, of the ingress-controller's service. Port-forwarding is not for a production environment use-case. But here we use port-forwarding, to simulate a HTTP request, originating from outside the cluster, to reach the service of the ingress-nginx controller, that is exposed to receive traffic from outside the cluster.</p> <p>This issue shows a typical DNS problem and its solution.</p> <p>At this point, you can access your deployment using curl ; <pre><code>curl --resolve demo.localdev.me:8080:127.0.0.1 http://demo.localdev.me:8080\n</code></pre></p> <p>You should see a HTML response containing text like \"It works!\".</p>"},{"location":"deploy/#online-testing","title":"Online testing","text":"<p>If your Kubernetes cluster is a \"real\" cluster that supports services of type <code>LoadBalancer</code>, it will have allocated an  external IP address or FQDN to the ingress controller.</p> <p>You can see that IP address or FQDN with the following command:</p> <pre><code>kubectl get service ingress-nginx-controller --namespace=ingress-nginx\n</code></pre> <p>It will be the <code>EXTERNAL-IP</code> field. If that field shows <code>&lt;pending&gt;</code>, this means that your Kubernetes cluster wasn't  able to provision the load balancer (generally, this is because it doesn't support services of type <code>LoadBalancer</code>).</p> <p>Once you have the external IP address (or FQDN), set up a DNS record pointing to it. Then you can create an ingress  resource. The following example assumes that you have set up a DNS record for <code>www.demo.io</code>:</p> <pre><code>kubectl create ingress demo --class=nginx \\\n  --rule=\"www.demo.io/*=demo:80\"\n</code></pre> <p>Alternatively, the above command can be rewritten as follows for the <code>--rule</code> command and below. <pre><code>kubectl create ingress demo --class=nginx \\\n  --rule www.demo.io/=demo:80\n</code></pre></p> <p>You should then be able to see the \"It works!\" page when you connect to http://www.demo.io/. Congratulations,  you are serving a public website hosted on a Kubernetes cluster! \ud83c\udf89</p>"},{"location":"deploy/#environment-specific-instructions","title":"Environment-specific instructions","text":""},{"location":"deploy/#local-development-clusters","title":"Local development clusters","text":""},{"location":"deploy/#minikube","title":"minikube","text":"<p>The ingress controller can be installed through minikube's addons system:</p> <pre><code>minikube addons enable ingress\n</code></pre>"},{"location":"deploy/#microk8s","title":"MicroK8s","text":"<p>The ingress controller can be installed through MicroK8s's addons system:</p> <pre><code>microk8s enable ingress\n</code></pre> <p>Please check the MicroK8s documentation page for details.</p>"},{"location":"deploy/#docker-desktop","title":"Docker Desktop","text":"<p>Kubernetes is available in Docker Desktop:</p> <ul> <li>Mac, from version 18.06.0-ce</li> <li>Windows, from version 18.06.0-ce</li> </ul> <p>First, make sure that Kubernetes is enabled in the Docker settings. The command <code>kubectl get nodes</code> should show a  single node called <code>docker-desktop</code>.</p> <p>The ingress controller can be installed on Docker Desktop using the default quick start instructions.</p> <p>On most systems, if you don't have any other service of type <code>LoadBalancer</code> bound to port 80, the ingress controller  will be assigned the <code>EXTERNAL-IP</code> of <code>localhost</code>, which means that it will be reachable on localhost:80. If that  doesn't work, you might have to fall back to the <code>kubectl port-forward</code> method described in the  local testing section.</p>"},{"location":"deploy/#rancher-desktop","title":"Rancher Desktop","text":"<p>Rancher Desktop provides Kubernetes and Container Management on the desktop. Kubernetes is enabled by default in Rancher Desktop. </p> <p>Rancher Desktop uses K3s under the hood, which in turn uses Traefik as the default ingress controller for the Kubernetes cluster. To use Ingress-Nginx Controller in place of the default Traefik, disable Traefik from Preference &gt; Kubernetes menu.</p> <p>Once traefik is disabled, the Ingress-Nginx Controller can be installed on Rancher Desktop using the default quick start instructions. Follow the instructions described in the local testing section to try a sample.</p>"},{"location":"deploy/#cloud-deployments","title":"Cloud deployments","text":"<p>If the load balancers of your cloud provider do active healthchecks on their backends (most do), you can change the  <code>externalTrafficPolicy</code> of the ingress controller Service to <code>Local</code> (instead of the default <code>Cluster</code>) to save an  extra hop in some cases. If you're installing with Helm, this can be done by adding  <code>--set controller.service.externalTrafficPolicy=Local</code> to the <code>helm install</code> or <code>helm upgrade</code> command.</p> <p>Furthermore, if the load balancers of your cloud provider support the PROXY protocol, you can enable it, and it will  let the ingress controller see the real IP address of the clients. Otherwise, it will generally see the IP address of  the upstream load balancer. This must be done both in the ingress controller  (with e.g. <code>--set controller.config.use-proxy-protocol=true</code>) and in the cloud provider's load balancer configuration  to function correctly.</p> <p>In the following sections, we provide YAML manifests that enable these options when possible, using the specific  options of various cloud providers.</p>"},{"location":"deploy/#aws","title":"AWS","text":"<p>In AWS, we use a Network load balancer (NLB) to expose the Ingress-Nginx Controller behind a Service of <code>Type=LoadBalancer</code>.</p> <p>Info</p> <p>The provided templates illustrate the setup for legacy in-tree service load balancer for AWS NLB. AWS provides the documentation on how to use  Network load balancing on Amazon EKS  with AWS Load Balancer Controller.</p>"},{"location":"deploy/#network-load-balancer-nlb","title":"Network Load Balancer (NLB)","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/aws/deploy.yaml\n</code></pre>"},{"location":"deploy/#tls-termination-in-aws-load-balancer-nlb","title":"TLS termination in AWS Load Balancer (NLB)","text":"<p>By default, TLS is terminated in the ingress controller. But it is also possible to terminate TLS in the Load Balancer.  This section explains how to do that on AWS using an NLB.</p> <ol> <li>Download the deploy.yaml template</li> </ol> <pre><code>wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/aws/nlb-with-tls-termination/deploy.yaml\n</code></pre> <ol> <li> <p>Edit the file and change the VPC CIDR in use for the Kubernetes cluster:    <pre><code>proxy-real-ip-cidr: XXX.XXX.XXX/XX\n</code></pre></p> </li> <li> <p>Change the AWS Certificate Manager (ACM) ID as well:    <pre><code>arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX\n</code></pre></p> </li> <li> <p>Deploy the manifest:    <pre><code>kubectl apply -f deploy.yaml\n</code></pre></p> </li> </ol>"},{"location":"deploy/#nlb-idle-timeouts","title":"NLB Idle Timeouts","text":"<p>Idle timeout value for TCP flows is 350 seconds and  cannot be modified.</p> <p>For this reason, you need to ensure the  keepalive_timeout  value is configured less than 350 seconds to work as expected.</p> <p>By default, NGINX <code>keepalive_timeout</code> is set to <code>75s</code>.</p> <p>More information with regard to timeouts can be found in the  official AWS documentation</p>"},{"location":"deploy/#gce-gke","title":"GCE-GKE","text":"<p>First, your user needs to have <code>cluster-admin</code> permissions on the cluster. This can be done with the following command:</p> <pre><code>kubectl create clusterrolebinding cluster-admin-binding \\\n  --clusterrole cluster-admin \\\n  --user $(gcloud config get-value account)\n</code></pre> <p>Then, the ingress controller can be installed like this:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>Warning</p> <p>For private clusters, you will need to either add a firewall rule that allows master nodes access to  port <code>8443/tcp</code> on worker nodes, or change the existing rule that allows access to port <code>80/tcp</code>, <code>443/tcp</code> and  <code>10254/tcp</code> to also allow access to port <code>8443/tcp</code>. More information can be found in the  Official GCP Documentation.</p> <p>See the GKE documentation  on adding rules and the Kubernetes issue for more detail.</p> <p>Proxy-protocol is supported in GCE check the Official Documentations on how to enable.</p>"},{"location":"deploy/#azure","title":"Azure","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>More information with regard to Azure annotations for ingress controller can be found in the official AKS documentation.</p>"},{"location":"deploy/#digital-ocean","title":"Digital Ocean","text":"<p><pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/do/deploy.yaml\n</code></pre> - By default the service object of the ingress-nginx-controller for Digital-Ocean, only configures one annotation. Its this one <code>service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol: \"true\"</code>. While this makes the service functional, it was reported that the Digital-Ocean LoadBalancer graphs shows <code>no data</code>, unless a few other annotations are also configured. Some of these other annotations require values that can not be generic and hence not forced in a out-of-the-box installation. These annotations and a discussion on them is well documented in this issue. Please refer to the issue to add annotations, with values specific to user, to get graphs of the DO-LB populated with data.</p>"},{"location":"deploy/#scaleway","title":"Scaleway","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/scw/deploy.yaml\n</code></pre>"},{"location":"deploy/#exoscale","title":"Exoscale","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/exoscale/deploy.yaml\n</code></pre> <p>The full list of annotations supported by Exoscale is available in the Exoscale Cloud Controller Manager  documentation.</p>"},{"location":"deploy/#oracle-cloud-infrastructure","title":"Oracle Cloud Infrastructure","text":"<pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/cloud/deploy.yaml\n</code></pre> <p>A  complete list of available annotations for Oracle Cloud Infrastructure  can be found in the OCI Cloud Controller Manager documentation.</p>"},{"location":"deploy/#ovhcloud","title":"OVHcloud","text":"<pre><code>helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx\nhelm repo update\nhelm -n ingress-nginx install ingress-nginx ingress-nginx/ingress-nginx --create-namespace\n</code></pre> <p>You can find the complete tutorial.</p>"},{"location":"deploy/#bare-metal-clusters","title":"Bare metal clusters","text":"<p>This section is applicable to Kubernetes clusters deployed on bare metal servers, as well as \"raw\" VMs where Kubernetes  was installed manually, using generic Linux distros (like CentOS, Ubuntu...)</p> <p>For quick testing, you can use a  NodePort.  This should work on almost every cluster, but it will typically use a port in the range 30000-32767.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/baremetal/deploy.yaml\n</code></pre> <p>For more information about bare metal deployments (and how to use port 80 instead of a random port in the 30000-32767 range), see bare-metal considerations.</p>"},{"location":"deploy/#miscellaneous","title":"Miscellaneous","text":""},{"location":"deploy/#checking-ingress-controller-version","title":"Checking ingress controller version","text":"<p>Run <code>/nginx-ingress-controller --version</code> within the pod, for instance with <code>kubectl exec</code>:</p> <pre><code>POD_NAMESPACE=ingress-nginx\nPOD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/name=ingress-nginx --field-selector=status.phase=Running -o name)\nkubectl exec $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version\n</code></pre>"},{"location":"deploy/#scope","title":"Scope","text":"<p>By default, the controller watches Ingress objects from all namespaces. If you want to change this behavior,  use the flag <code>--watch-namespace</code> or check the Helm chart value <code>controller.scope</code> to limit the controller to a single  namespace.</p> <p>See also  \u201cHow to easily install multiple instances of the Ingress NGINX controller in the same cluster\u201d  for more details.</p>"},{"location":"deploy/#webhook-network-access","title":"Webhook network access","text":"<p>Warning</p> <p>The controller uses an admission webhook to validate Ingress definitions. Make sure that you don't have  Network policies  or additional firewalls preventing connections from the API server to the <code>ingress-nginx-controller-admission</code> service.</p>"},{"location":"deploy/#certificate-generation","title":"Certificate generation","text":"<p>Attention</p> <p>The first time the ingress controller starts, two Jobs create the SSL Certificate used by the admission webhook.</p> <p>This can cause an initial delay of up to two minutes until it is possible to create and validate Ingress definitions.</p> <p>You can wait until it is ready to run the next command:</p> <pre><code> kubectl wait --namespace ingress-nginx \\\n  --for=condition=ready pod \\\n  --selector=app.kubernetes.io/component=controller \\\n  --timeout=120s\n</code></pre>"},{"location":"deploy/#running-on-kubernetes-versions-older-than-119","title":"Running on Kubernetes versions older than 1.19","text":"<p>Ingress resources evolved over time. They started with <code>apiVersion: extensions/v1beta1</code>,  then moved to <code>apiVersion: networking.k8s.io/v1beta1</code> and more recently to <code>apiVersion: networking.k8s.io/v1</code>.</p> <p>Here is how these Ingress versions are supported in Kubernetes: - before Kubernetes 1.19, only <code>v1beta1</code> Ingress resources are supported - from Kubernetes 1.19 to 1.21, both <code>v1beta1</code> and <code>v1</code> Ingress resources are supported - in Kubernetes 1.22 and above, only <code>v1</code> Ingress resources are supported</p> <p>And here is how these Ingress versions are supported in Ingress-Nginx Controller: - before version 1.0, only <code>v1beta1</code> Ingress resources are supported - in version 1.0 and above, only <code>v1</code> Ingress resources are</p> <p>As a result, if you're running Kubernetes 1.19 or later, you should be able to use the latest version of the NGINX  Ingress Controller; but if you're using an old version of Kubernetes (1.18 or earlier) you will have to use version 0.X  of the Ingress-Nginx Controller (e.g. version 0.49).</p> <p>The Helm chart of the Ingress-Nginx Controller switched to version 1 in version 4 of the chart. In other words, if  you're running Kubernetes 1.19 or earlier, you should use version 3.X of the chart (this can be done by adding  <code>--version='&lt;4'</code> to the <code>helm install</code> command ).</p>"},{"location":"deploy/baremetal/","title":"Bare-metal considerations","text":"<p>In traditional cloud environments, where network load balancers are available on-demand, a single Kubernetes manifest suffices to provide a single point of contact to the Ingress-Nginx Controller to external clients and, indirectly, to any application running inside the cluster. Bare-metal environments lack this commodity, requiring a slightly different setup to offer the same kind of access to external consumers.</p> <p> </p> <p>The rest of this document describes a few recommended approaches to deploying the Ingress-Nginx Controller inside a Kubernetes cluster running on bare-metal.</p>"},{"location":"deploy/baremetal/#a-pure-software-solution-metallb","title":"A pure software solution: MetalLB","text":"<p>MetalLB provides a network load-balancer implementation for Kubernetes clusters that do not run on a supported cloud provider, effectively allowing the usage of LoadBalancer Services within any cluster.</p> <p>This section demonstrates how to use the Layer 2 configuration mode of MetalLB together with the NGINX Ingress controller in a Kubernetes cluster that has publicly accessible nodes. In this mode, one node attracts all the traffic for the <code>ingress-nginx</code> Service IP. See Traffic policies for more details.</p> <p></p> <p>Note</p> <p>The description of other supported configuration modes is off-scope for this document.</p> <p>Warning</p> <p>MetalLB is currently in beta. Read about the Project maturity and make sure you inform yourself by reading the official documentation thoroughly.</p> <p>MetalLB can be deployed either with a simple Kubernetes manifest or with Helm. The rest of this example assumes MetalLB was deployed following the Installation instructions, and that the Ingress-Nginx Controller was installed  using the steps described in the quickstart section of the installation guide.</p> <p>MetalLB requires a pool of IP addresses in order to be able to take ownership of the <code>ingress-nginx</code> Service. This pool can be defined through <code>IPAddressPool</code> objects in the same namespace as the MetalLB controller. This pool of IPs must be dedicated to MetalLB's use, you can't reuse the Kubernetes node IPs or IPs handed out by a DHCP server.</p> <p>Example</p> <p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>After creating the following objects, MetalLB takes ownership of one of the IP addresses in the pool and updates the loadBalancer IP field of the <code>ingress-nginx</code> Service accordingly.</p> <pre><code>---\napiVersion: metallb.io/v1beta1\nkind: IPAddressPool\nmetadata:\n  name: default\n  namespace: metallb-system\nspec:\n  addresses:\n  - 203.0.113.10-203.0.113.15\n  autoAssign: true\n---\napiVersion: metallb.io/v1beta1\nkind: L2Advertisement\nmetadata:\n  name: default\n  namespace: metallb-system\nspec:\n  ipAddressPools:\n  - default\n</code></pre> <pre><code>$ kubectl -n ingress-nginx get svc\nNAME                   TYPE          CLUSTER-IP     EXTERNAL-IP  PORT(S)\ndefault-http-backend   ClusterIP     10.0.64.249    &lt;none&gt;       80/TCP\ningress-nginx          LoadBalancer  10.0.220.217   203.0.113.10  80:30100/TCP,443:30101/TCP\n</code></pre> <p>As soon as MetalLB sets the external IP address of the <code>ingress-nginx</code> LoadBalancer Service, the corresponding entries are created in the iptables NAT table and the node with the selected IP address starts responding to HTTP requests on the ports configured in the LoadBalancer Service:</p> <pre><code>$ curl -D- http://203.0.113.10 -H 'Host: myapp.example.com'\nHTTP/1.1 200 OK\nServer: nginx/1.15.2\n</code></pre> <p>Tip</p> <p>In order to preserve the source IP address in HTTP requests sent to NGINX, it is necessary to use the <code>Local</code> traffic policy. Traffic policies are described in more details in Traffic policies as well as in the next section.</p>"},{"location":"deploy/baremetal/#over-a-nodeport-service","title":"Over a NodePort Service","text":"<p>Due to its simplicity, this is the setup a user will deploy by default when following the steps described in the installation guide.</p> <p>Info</p> <p>A Service of type <code>NodePort</code> exposes, via the <code>kube-proxy</code> component, the same unprivileged port (default: 30000-32767) on every Kubernetes node, masters included. For more information, see Services.</p> <p>In this configuration, the NGINX container remains isolated from the host network. As a result, it can safely bind to any port, including the standard HTTP ports 80 and 443. However, due to the container namespace isolation, a client located outside the cluster network (e.g. on the public internet) is not able to access Ingress hosts directly on ports 80 and 443. Instead, the external client must append the NodePort allocated to the <code>ingress-nginx</code> Service to HTTP requests.</p> <p></p> <p>Example</p> <p>Given the NodePort <code>30100</code> allocated to the <code>ingress-nginx</code> Service</p> <pre><code>$ kubectl -n ingress-nginx get svc\nNAME                   TYPE        CLUSTER-IP     PORT(S)\ndefault-http-backend   ClusterIP   10.0.64.249    80/TCP\ningress-nginx          NodePort    10.0.220.217   80:30100/TCP,443:30101/TCP\n</code></pre> <p>and a Kubernetes node with the public IP address <code>203.0.113.2</code> (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>a client would reach an Ingress with <code>host: myapp.example.com</code> at <code>http://myapp.example.com:30100</code>, where the myapp.example.com subdomain resolves to the 203.0.113.2 IP address.</p> <p>Impact on the host system</p> <p>While it may sound tempting to reconfigure the NodePort range using the <code>--service-node-port-range</code> API server flag to include unprivileged ports and be able to expose ports 80 and 443, doing so may result in unexpected issues including (but not limited to) the use of ports otherwise reserved to system daemons and the necessity to grant <code>kube-proxy</code> privileges it may otherwise not require.</p> <p>This practice is therefore discouraged. See the other approaches proposed in this page for alternatives.</p> <p>This approach has a few other limitations one ought to be aware of:</p> <ul> <li>Source IP address</li> </ul> <p>Services of type NodePort perform source address translation by default. This means the source IP of a HTTP request is always the IP address of the Kubernetes node that received the request from the perspective of NGINX.</p> <p>The recommended way to preserve the source IP in a NodePort setup is to set the value of the <code>externalTrafficPolicy</code> field of the <code>ingress-nginx</code> Service spec to <code>Local</code> (example).</p> <p>Warning</p> <p>This setting effectively drops packets sent to Kubernetes nodes which are not running any instance of the NGINX Ingress controller. Consider assigning NGINX Pods to specific nodes in order to control on what nodes the Ingress-Nginx Controller should be scheduled or not scheduled.</p> <p>Example</p> <p>In a Kubernetes cluster composed of 3 nodes (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>with a <code>ingress-nginx-controller</code> Deployment composed of 2 replicas</p> <pre><code>$ kubectl -n ingress-nginx get pod -o wide\nNAME                                       READY   STATUS    IP           NODE\ndefault-http-backend-7c5bc89cc9-p86md      1/1     Running   172.17.1.1   host-2\ningress-nginx-controller-cf9ff8c96-8vvf8   1/1     Running   172.17.0.3   host-3\ningress-nginx-controller-cf9ff8c96-pxsds   1/1     Running   172.17.1.4   host-2\n</code></pre> <p>Requests sent to <code>host-2</code> and <code>host-3</code> would be forwarded to NGINX and original client's IP would be preserved, while requests to <code>host-1</code> would get dropped because there is no NGINX replica running on that node.</p> <ul> <li>Ingress status</li> </ul> <p>Because NodePort Services do not get a LoadBalancerIP assigned by definition, the Ingress-Nginx Controller does not update the status of Ingress objects it manages.</p> <pre><code>$ kubectl get ingress\nNAME           HOSTS               ADDRESS   PORTS\ntest-ingress   myapp.example.com             80\n</code></pre> <p>Despite the fact there is no load balancer providing a public IP address to the Ingress-Nginx Controller, it is possible to force the status update of all managed Ingress objects by setting the <code>externalIPs</code> field of the <code>ingress-nginx</code> Service.</p> <p>Warning</p> <p>There is more to setting <code>externalIPs</code> than just enabling the Ingress-Nginx Controller to update the status of Ingress objects. Please read about this option in the Services page of official Kubernetes documentation as well as the section about External IPs in this document for more information.</p> <p>Example</p> <p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>one could edit the <code>ingress-nginx</code> Service and add the following field to the object spec</p> <pre><code>spec:\n  externalIPs:\n  - 203.0.113.1\n  - 203.0.113.2\n  - 203.0.113.3\n</code></pre> <p>which would in turn be reflected on Ingress objects as follows:</p> <pre><code>$ kubectl get ingress -o wide\nNAME           HOSTS               ADDRESS                               PORTS\ntest-ingress   myapp.example.com   203.0.113.1,203.0.113.2,203.0.113.3   80\n</code></pre> <ul> <li>Redirects</li> </ul> <p>As NGINX is not aware of the port translation operated by the NodePort Service, backend applications are responsible for generating redirect URLs that take into account the URL used by external clients, including the NodePort.</p> <p>Example</p> <p>Redirects generated by NGINX, for instance HTTP to HTTPS or <code>domain</code> to <code>www.domain</code>, are generated without NodePort:</p> <pre><code>$ curl -D- http://myapp.example.com:30100`\nHTTP/1.1 308 Permanent Redirect\nServer: nginx/1.15.2\nLocation: https://myapp.example.com/  #-&gt; missing NodePort in HTTPS redirect\n</code></pre>"},{"location":"deploy/baremetal/#via-the-host-network","title":"Via the host network","text":"<p>In a setup where there is no external load balancer available but using NodePorts is not an option, one can configure <code>ingress-nginx</code> Pods to use the network of the host they run on instead of a dedicated network namespace. The benefit of this approach is that the Ingress-Nginx Controller can bind ports 80 and 443 directly to Kubernetes nodes' network interfaces, without the extra network translation imposed by NodePort Services.</p> <p>Note</p> <p>This approach does not leverage any Service object to expose the Ingress-Nginx Controller. If the <code>ingress-nginx</code> Service exists in the target cluster, it is recommended to delete it.</p> <p>This can be achieved by enabling the <code>hostNetwork</code> option in the Pods' spec.</p> <pre><code>template:\n  spec:\n    hostNetwork: true\n</code></pre> <p>Security considerations</p> <p>Enabling this option exposes every system daemon to the Ingress-Nginx Controller on any network interface, including the host's loopback. Please evaluate the impact this may have on the security of your system carefully.</p> <p>Example</p> <p>Consider this <code>ingress-nginx-controller</code> Deployment composed of 2 replicas, NGINX Pods inherit from the IP address of their host instead of an internal Pod IP.</p> <pre><code>$ kubectl -n ingress-nginx get pod -o wide\nNAME                                       READY   STATUS    IP            NODE\ndefault-http-backend-7c5bc89cc9-p86md      1/1     Running   172.17.1.1    host-2\ningress-nginx-controller-5b4cf5fc6-7lg6c   1/1     Running   203.0.113.3   host-3\ningress-nginx-controller-5b4cf5fc6-lzrls   1/1     Running   203.0.113.2   host-2\n</code></pre> <p>One major limitation of this deployment approach is that only a single Ingress-Nginx Controller Pod may be scheduled on each cluster node, because binding the same port multiple times on the same network interface is technically impossible. Pods that are unschedulable due to such situation fail with the following event:</p> <pre><code>$ kubectl -n ingress-nginx describe pod &lt;unschedulable-ingress-nginx-controller-pod&gt;\n...\nEvents:\n  Type     Reason            From               Message\n  ----     ------            ----               -------\n  Warning  FailedScheduling  default-scheduler  0/3 nodes are available: 3 node(s) didn't have free ports for the requested pod ports.\n</code></pre> <p>One way to ensure only schedulable Pods are created is to deploy the Ingress-Nginx Controller as a DaemonSet instead of a traditional Deployment.</p> <p>Info</p> <p>A DaemonSet schedules exactly one type of Pod per cluster node, masters included, unless a node is configured to repel those Pods. For more information, see DaemonSet.</p> <p>Because most properties of DaemonSet objects are identical to Deployment objects, this documentation page leaves the configuration of the corresponding manifest at the user's discretion.</p> <p></p> <p>Like with NodePorts, this approach has a few quirks it is important to be aware of.</p> <ul> <li>DNS resolution</li> </ul> <p>Pods configured with <code>hostNetwork: true</code> do not use the internal DNS resolver (i.e. kube-dns or CoreDNS), unless their <code>dnsPolicy</code> spec field is set to <code>ClusterFirstWithHostNet</code>. Consider using this setting if NGINX is expected to resolve internal names for any reason.</p> <ul> <li>Ingress status</li> </ul> <p>Because there is no Service exposing the Ingress-Nginx Controller in a configuration using the host network, the default <code>--publish-service</code> flag used in standard cloud setups does not apply and the status of all Ingress objects remains blank.</p> <pre><code>$ kubectl get ingress\nNAME           HOSTS               ADDRESS   PORTS\ntest-ingress   myapp.example.com             80\n</code></pre> <p>Instead, and because bare-metal nodes usually don't have an ExternalIP, one has to enable the <code>--report-node-internal-ip-address</code> flag, which sets the status of all Ingress objects to the internal IP address of all nodes running the Ingress-Nginx Controller.</p> <p>Example</p> <p>Given a <code>ingress-nginx-controller</code> DaemonSet composed of 2 replicas</p> <pre><code>$ kubectl -n ingress-nginx get pod -o wide\nNAME                                       READY   STATUS    IP            NODE\ndefault-http-backend-7c5bc89cc9-p86md      1/1     Running   172.17.1.1    host-2\ningress-nginx-controller-5b4cf5fc6-7lg6c   1/1     Running   203.0.113.3   host-3\ningress-nginx-controller-5b4cf5fc6-lzrls   1/1     Running   203.0.113.2   host-2\n</code></pre> <p>the controller sets the status of all Ingress objects it manages to the following value:</p> <pre><code>$ kubectl get ingress -o wide\nNAME           HOSTS               ADDRESS                   PORTS\ntest-ingress   myapp.example.com   203.0.113.2,203.0.113.3   80\n</code></pre> <p>Note</p> <p>Alternatively, it is possible to override the address written to Ingress objects using the <code>--publish-status-address</code> flag. See Command line arguments.</p>"},{"location":"deploy/baremetal/#using-a-self-provisioned-edge","title":"Using a self-provisioned edge","text":"<p>Similarly to cloud environments, this deployment approach requires an edge network component providing a public entrypoint to the Kubernetes cluster. This edge component can be either hardware (e.g. vendor appliance) or software (e.g. HAproxy) and is usually managed outside of the Kubernetes landscape by operations teams.</p> <p>Such deployment builds upon the NodePort Service described above in Over a NodePort Service, with one significant difference: external clients do not access cluster nodes directly, only the edge component does. This is particularly suitable for private Kubernetes clusters where none of the nodes has a public IP address.</p> <p>On the edge side, the only prerequisite is to dedicate a public IP address that forwards all HTTP traffic to Kubernetes nodes and/or masters. Incoming traffic on TCP ports 80 and 443 is forwarded to the corresponding HTTP and HTTPS NodePort on the target nodes as shown in the diagram below:</p> <p></p>"},{"location":"deploy/baremetal/#external-ips","title":"External IPs","text":"<p>Source IP address</p> <p>This method does not allow preserving the source IP of HTTP requests in any manner, it is therefore not recommended to use it despite its apparent simplicity.</p> <p>The <code>externalIPs</code> Service option was previously mentioned in the NodePort section.</p> <p>As per the Services page of the official Kubernetes documentation, the <code>externalIPs</code> option causes <code>kube-proxy</code> to route traffic sent to arbitrary IP addresses and on the Service ports to the endpoints of that Service. These IP addresses must belong to the target node.</p> <p>Example</p> <p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is &lt;None&gt;)</p> <pre><code>$ kubectl get node\nNAME     STATUS   ROLES    EXTERNAL-IP\nhost-1   Ready    master   203.0.113.1\nhost-2   Ready    node     203.0.113.2\nhost-3   Ready    node     203.0.113.3\n</code></pre> <p>and the following <code>ingress-nginx</code> NodePort Service</p> <pre><code>$ kubectl -n ingress-nginx get svc\nNAME                   TYPE        CLUSTER-IP     PORT(S)\ningress-nginx          NodePort    10.0.220.217   80:30100/TCP,443:30101/TCP\n</code></pre> <p>One could set the following external IPs in the Service spec, and NGINX would become available on both the NodePort and the Service port:</p> <pre><code>spec:\n  externalIPs:\n  - 203.0.113.2\n  - 203.0.113.3\n</code></pre> <pre><code>$ curl -D- http://myapp.example.com:30100\nHTTP/1.1 200 OK\nServer: nginx/1.15.2\n\n$ curl -D- http://myapp.example.com\nHTTP/1.1 200 OK\nServer: nginx/1.15.2\n</code></pre> <p>We assume the myapp.example.com subdomain above resolves to both 203.0.113.2 and 203.0.113.3 IP addresses.</p>"},{"location":"deploy/hardening-guide/","title":"Hardening Guide","text":""},{"location":"deploy/hardening-guide/#overview","title":"Overview","text":"<p>There are several ways to do hardening and securing of nginx. In this documentation two guides are used, the guides are overlapping in some points:</p> <ul> <li>nginx CIS Benchmark</li> <li>cipherlist.eu (one of many forks of the now dead project cipherli.st)</li> </ul> <p>This guide describes, what of the different configurations described in those guides is already implemented as default in the nginx implementation of kubernetes ingress, what needs to be configured, what is obsolete due to the fact that the nginx is running as container (the CIS benchmark relates to a non-containerized installation) and what is difficult or not possible.</p> <p>Be aware that this is only a guide and you are responsible for your own implementation. Some of the configurations may lead to have specific clients unable to reach your site or similar consequences.</p> <p>This guide refers to chapters in the CIS Benchmark. For full explanation you should refer to the benchmark document itself</p>"},{"location":"deploy/hardening-guide/#configuration-guide","title":"Configuration Guide","text":"Chapter in CIS benchmark Status Default Action to do if not default 1 Initial Setup 1.1 Installation 1.1.1 Ensure NGINX is installed (Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.1.2 Ensure NGINX is installed from source (Not Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.2 Configure Software Updates 1.2.1 Ensure package manager repositories are properly configured (Not Scored) OK done via helm, nginx version could be overwritten, however compatibility is not ensured then 1.2.2 Ensure the latest software package is installed (Not Scored) ACTION NEEDED done via helm, nginx version could be overwritten, however compatibility is not ensured then Plan for periodic updates 2 Basic Configuration 2.1 Minimize NGINX Modules 2.1.1 Ensure only required modules are installed (Not Scored) OK Already only needed modules are installed, however proposals for further reduction are welcome 2.1.2 Ensure HTTP WebDAV module is not installed (Scored) OK 2.1.3 Ensure modules with gzip functionality are disabled (Scored) OK 2.1.4 Ensure the autoindex module is disabled (Scored) OK No autoindex configs so far in ingress defaults 2.2 Account Security 2.2.1 Ensure that NGINX is run using a non-privileged, dedicated service account (Not Scored) OK Pod configured as user www-data: See this line in helm chart values. Compiled with user www-data: See this line in build script 2.2.2 Ensure the NGINX service account is locked (Scored) OK Docker design ensures this 2.2.3 Ensure the NGINX service account has an invalid shell (Scored) OK Shell is nologin: see this line in build script 2.3 Permissions and Ownership 2.3.1 Ensure NGINX directories and files are owned by root (Scored) OK Obsolete through docker-design and ingress controller needs to update the configs dynamically 2.3.2 Ensure access to NGINX directories and files is restricted (Scored) OK See previous answer 2.3.3 Ensure the NGINX process ID (PID) file is secured (Scored) OK No PID-File due to docker design 2.3.4 Ensure the core dump directory is secured (Not Scored) OK No working_directory configured by default 2.4 Network Configuration 2.4.1 Ensure NGINX only listens for network connections on authorized ports (Not Scored) OK Ensured by automatic nginx.conf configuration 2.4.2 Ensure requests for unknown host names are rejected (Not Scored) OK They are not rejected but send to the \"default backend\" delivering appropriate errors (mostly 404) 2.4.3 Ensure keepalive_timeout is 10 seconds or less, but not 0 (Scored) ACTION NEEDED Default is 75s configure keep-alive to 10 seconds according to this documentation 2.4.4 Ensure send_timeout is set to 10 seconds or less, but not 0 (Scored) RISK TO BE ACCEPTED Not configured, however the nginx default is 60s Not configurable 2.5 Information Disclosure 2.5.1 Ensure server_tokens directive is set to <code>off</code> (Scored) OK server_tokens is configured to off by default 2.5.2 Ensure default error and index.html pages do not reference NGINX (Scored) ACTION NEEDED 404 shows no version at all, 503 and 403 show \"nginx\", which is hardcoded see this line in nginx source code configure custom error pages at least for 403, 404 and 503 and 500 2.5.3 Ensure hidden file serving is disabled (Not Scored) ACTION NEEDED config not set configure a config.server-snippet Snippet, but beware of .well-known challenges or similar. Refer to the benchmark here please 2.5.4 Ensure the NGINX reverse proxy does not enable information disclosure (Scored) ACTION NEEDED hide not configured configure hide-headers with array of \"X-Powered-By\" and \"Server\": according to this documentation 3 Logging 3.1 Ensure detailed logging is enabled (Not Scored) OK nginx ingress has a very detailed log format by default 3.2 Ensure access logging is enabled (Scored) OK Access log is enabled by default 3.3 Ensure error logging is enabled and set to the info logging level (Scored) OK Error log is configured by default. The log level does not matter, because it is all sent to STDOUT anyway 3.4 Ensure log files are rotated (Scored) OBSOLETE Log file handling is not part of the nginx ingress and should be handled separately 3.5 Ensure error logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.6 Ensure access logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.7 Ensure proxies pass source IP information (Scored) OK Headers are set by default 4 Encryption 4.1 TLS / SSL Configuration 4.1.1 Ensure HTTP is redirected to HTTPS (Scored) OK Redirect to TLS is default 4.1.2 Ensure a trusted certificate and trust chain is installed (Not Scored) ACTION NEEDED For installing certs there are enough manuals in the web. A good way is to use lets encrypt through cert-manager Install proper certificates or use lets encrypt with cert-manager 4.1.3 Ensure private key permissions are restricted (Scored) ACTION NEEDED See previous answer 4.1.4 Ensure only modern TLS protocols are used (Scored) OK/ACTION NEEDED Default is TLS 1.2 + 1.3, while this is okay for CIS Benchmark, cipherlist.eu only recommends 1.3. This may cut off old OS's Set controller.config.ssl-protocols to \"TLSv1.3\" 4.1.5 Disable weak ciphers (Scored) ACTION NEEDED Default ciphers are already good, but cipherlist.eu recommends even stronger ciphers Set controller.config.ssl-ciphers to \"EECDH+AESGCM:EDH+AESGCM\" 4.1.6 Ensure custom Diffie-Hellman parameters are used (Scored) ACTION NEEDED No custom DH parameters are generated Generate dh parameters for each ingress deployment you use - see here for a how to 4.1.7 Ensure Online Certificate Status Protocol (OCSP) stapling is enabled (Scored) ACTION NEEDED Not enabled set via this configuration parameter 4.1.8 Ensure HTTP Strict Transport Security (HSTS) is enabled (Scored) OK HSTS is enabled by default 4.1.9 Ensure HTTP Public Key Pinning is enabled (Not Scored) ACTION NEEDED / RISK TO BE ACCEPTED HKPK not enabled by default If lets encrypt is not used, set correct HPKP header. There are several ways to implement this - with the helm charts it works via controller.add-headers. If lets encrypt is used, this is complicated, a solution here is yet unknown 4.1.10 Ensure upstream server traffic is authenticated with a client certificate (Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, manual is here 4.1.11 Ensure the upstream traffic server certificate is trusted (Not Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, see configuration here 4.1.12 Ensure your domain is preloaded (Not Scored) ACTION NEEDED Preload is not active by default Set controller.config.hsts-preload to true 4.1.13 Ensure session resumption is disabled to enable perfect forward security (Scored) OK Session tickets are disabled by default 4.1.14 Ensure HTTP/2.0 is used (Not Scored) OK http2 is set by default 5 Request Filtering and Restrictions 5.1 Access Control 5.1.1 Ensure allow and deny filters limit access to specific IP addresses (Not Scored) OK/ACTION NEEDED Depends on use case, geo ip module is compiled into Ingress-Nginx Controller, there are several ways to use it If needed set IP restrictions via annotations or work with config snippets (be careful with lets-encrypt-http-challenge!) 5.1.2 Ensure only whitelisted HTTP methods are allowed (Not Scored) OK/ACTION NEEDED Depends on use case If required it can be set via config snippet 5.2 Request Limits 5.2.1 Ensure timeout values for reading the client header and body are set correctly (Scored) ACTION NEEDED Default timeout is 60s Set via this configuration parameter and respective body equivalent 5.2.2 Ensure the maximum request body size is set correctly (Scored) ACTION NEEDED Default is 1m set via this configuration parameter 5.2.3 Ensure the maximum buffer size for URIs is defined (Scored) ACTION NEEDED Default is 4 8k Set via this configuration parameter 5.2.4 Ensure the number of connections per IP address is limited (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.2.5 Ensure rate limits by IP address are set (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.3 Browser Security 5.3.1 Ensure X-Frame-Options header is configured and enabled (Scored) ACTION NEEDED Header not set by default Several ways to implement this - with the helm charts it works via controller.add-headers 5.3.2 Ensure X-Content-Type-Options header is configured and enabled (Scored) ACTION NEEDED See previous answer See previous answer 5.3.3 Ensure the X-XSS-Protection Header is enabled and configured properly (Scored) ACTION NEEDED See previous answer See previous answer 5.3.4 Ensure that Content Security Policy (CSP) is enabled and configured properly (Not Scored) ACTION NEEDED See previous answer See previous answer 5.3.5 Ensure the Referrer Policy is enabled and configured properly (Not Scored) ACTION NEEDED Depends on application. It should be handled in the applications webserver itself, not in the load balancing ingress check backend webserver 6 Mandatory Access Control n/a too high level, depends on backends"},{"location":"deploy/rbac/","title":"Role Based Access Control (RBAC)","text":""},{"location":"deploy/rbac/#overview","title":"Overview","text":"<p>This example applies to ingress-nginx-controllers being deployed in an environment with RBAC enabled.</p> <p>Role Based Access Control is comprised of four layers:</p> <ol> <li><code>ClusterRole</code> - permissions assigned to a role that apply to an entire cluster</li> <li><code>ClusterRoleBinding</code> - binding a ClusterRole to a specific account</li> <li><code>Role</code> - permissions assigned to a role that apply to a specific namespace</li> <li><code>RoleBinding</code> - binding a Role to a specific account</li> </ol> <p>In order for RBAC to be applied to an ingress-nginx-controller, that controller should be assigned to a <code>ServiceAccount</code>.  That <code>ServiceAccount</code> should be bound to the <code>Role</code>s and <code>ClusterRole</code>s defined for the ingress-nginx-controller.</p>"},{"location":"deploy/rbac/#service-accounts-created-in-this-example","title":"Service Accounts created in this example","text":"<p>One ServiceAccount is created in this example, <code>ingress-nginx</code>.</p>"},{"location":"deploy/rbac/#permissions-granted-in-this-example","title":"Permissions Granted in this example","text":"<p>There are two sets of permissions defined in this example.  Cluster-wide permissions defined by the <code>ClusterRole</code> named <code>ingress-nginx</code>, and namespace specific permissions defined by the <code>Role</code> named <code>ingress-nginx</code>.</p>"},{"location":"deploy/rbac/#cluster-permissions","title":"Cluster Permissions","text":"<p>These permissions are granted in order for the ingress-nginx-controller to be able to function as an ingress across the cluster.  These permissions are granted to the <code>ClusterRole</code> named <code>ingress-nginx</code></p> <ul> <li><code>configmaps</code>, <code>endpoints</code>, <code>nodes</code>, <code>pods</code>, <code>secrets</code>: list, watch</li> <li><code>nodes</code>: get</li> <li><code>services</code>, <code>ingresses</code>, <code>ingressclasses</code>, <code>endpointslices</code>: get, list, watch</li> <li><code>events</code>: create, patch</li> <li><code>ingresses/status</code>: update</li> <li><code>leases</code>: list, watch</li> </ul>"},{"location":"deploy/rbac/#namespace-permissions","title":"Namespace Permissions","text":"<p>These permissions are granted specific to the ingress-nginx namespace.  These permissions are granted to the <code>Role</code> named <code>ingress-nginx</code></p> <ul> <li><code>configmaps</code>, <code>pods</code>, <code>secrets</code>: get</li> <li><code>endpoints</code>: get</li> </ul> <p>Furthermore to support leader-election, the ingress-nginx-controller needs to have access to a <code>leases</code> using the resourceName <code>ingress-nginx-leader</code></p> <p>Note that resourceNames can NOT be used to limit requests using the \u201ccreate\u201d verb because authorizers only have access to information that can be obtained from the request URL, method, and headers (resource names in a \u201ccreate\u201d request are part of the request body).</p> <ul> <li><code>leases</code>: get, update (for resourceName <code>ingress-controller-leader</code>)</li> <li><code>leases</code>: create</li> </ul> <p>This resourceName is the <code>election-id</code> defined by the ingress-controller, which defaults to:</p> <ul> <li><code>election-id</code>: <code>ingress-controller-leader</code></li> <li><code>resourceName</code> : <code>&lt;election-id&gt;</code></li> </ul> <p>Please adapt accordingly if you overwrite either parameter when launching the ingress-nginx-controller.</p>"},{"location":"deploy/rbac/#bindings","title":"Bindings","text":"<p>The ServiceAccount <code>ingress-nginx</code> is bound to the Role <code>ingress-nginx</code> and the ClusterRole <code>ingress-nginx</code>.</p> <p>The serviceAccountName associated with the containers in the deployment must match the serviceAccount. The namespace references in the Deployment metadata,  container arguments, and POD_NAMESPACE should be in the ingress-nginx namespace.</p>"},{"location":"deploy/upgrade/","title":"Upgrading","text":"<p>Important</p> <p>No matter the method you use for upgrading, if you use template overrides, make sure your templates are compatible with the new version of ingress-nginx.</p>"},{"location":"deploy/upgrade/#without-helm","title":"Without Helm","text":"<p>To upgrade your ingress-nginx installation, it should be enough to change the version of the image in the controller Deployment.</p> <p>I.e. if your deployment resource looks like (partial example):</p> <pre><code>kind: Deployment\nmetadata:\n  name: ingress-nginx-controller\n  namespace: ingress-nginx\nspec:\n  replicas: 1\n  selector: ...\n  template:\n    metadata: ...\n    spec:\n      containers:\n        - name: ingress-nginx-controller\n          image: registry.k8s.io/ingress-nginx/controller:v1.0.4@sha256:545cff00370f28363dad31e3b59a94ba377854d3a11f18988f5f9e56841ef9ef\n          args: ...\n</code></pre> <p>simply change the <code>v1.0.4</code> tag to the version you wish to upgrade to. The easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):</p> <pre><code>kubectl set image deployment/ingress-nginx-controller \\\n  controller=registry.k8s.io/ingress-nginx/controller:v1.0.5@sha256:55a1fcda5b7657c372515fe402c3e39ad93aa59f6e4378e82acd99912fe6028d \\\n  -n ingress-nginx\n</code></pre> <p>For interactive editing, use <code>kubectl edit deployment ingress-nginx-controller -n ingress-nginx</code>.</p>"},{"location":"deploy/upgrade/#with-helm","title":"With Helm","text":"<p>If you installed ingress-nginx using the Helm command in the deployment docs so its name is <code>ingress-nginx</code>, you should be able to upgrade using</p> <pre><code>helm upgrade --reuse-values ingress-nginx ingress-nginx/ingress-nginx\n</code></pre>"},{"location":"deploy/upgrade/#migrating-from-stablenginx-ingress","title":"Migrating from stable/nginx-ingress","text":"<p>See detailed steps in the upgrading section of the <code>ingress-nginx</code> chart README.</p>"},{"location":"developer-guide/code-overview/","title":"Ingress NGINX - Code Overview","text":"<p>This document provides an overview of Ingress NGINX code.</p>"},{"location":"developer-guide/code-overview/#core-golang-code","title":"Core Golang code","text":"<p>This part of the code is responsible for the main logic of Ingress NGINX. It contains all the logics that parses Ingress Objects,  annotations, watches Endpoints and turn them into usable nginx.conf configuration.</p>"},{"location":"developer-guide/code-overview/#core-sync-logics","title":"Core Sync Logics:","text":"<p>Ingress-nginx has an internal model of the ingresses, secrets and endpoints in a given cluster. It maintains two copies of that:</p> <ol> <li>One copy is the currently running configuration model</li> <li>Second copy is the one generated in response to some changes in the cluster</li> </ol> <p>The sync logic diffs the two models and if there's a change it tries to converge the running configuration to the new one. </p> <p>There are static and dynamic configuration changes. </p> <p>All endpoints and certificate changes are handled dynamically by posting the payload to an internal NGINX endpoint that is handled by Lua.</p> <p>The following parts of the code can be found:</p>"},{"location":"developer-guide/code-overview/#entrypoint","title":"Entrypoint","text":"<p>The <code>main</code> package is responsible for starting ingress-nginx program, which can be found in cmd/nginx directory.</p>"},{"location":"developer-guide/code-overview/#version","title":"Version","text":"<p>Is the package of the code responsible for adding <code>version</code> subcommand, and can be found in version directory.</p>"},{"location":"developer-guide/code-overview/#internal-code","title":"Internal code","text":"<p>This part of the code contains the internal logics that compose Ingress NGINX Controller, and it's split into:</p>"},{"location":"developer-guide/code-overview/#admission-controller","title":"Admission Controller","text":"<p>Contains the code of Kubernetes Admission Controller which validates the syntax of ingress objects before accepting it.</p> <p>This code can be found in internal/admission/controller directory.</p>"},{"location":"developer-guide/code-overview/#file-functions","title":"File functions","text":"<p>Contains auxiliary codes that deal with files, such as generating the SHA1 checksum of a file, or creating required directories.</p> <p>This code can be found in internal/file directory.</p>"},{"location":"developer-guide/code-overview/#ingress-functions","title":"Ingress functions","text":"<p>Contains all the logics from Ingress-Nginx Controller, with some examples being:</p> <ul> <li>Expected Golang structures that will be used in templates and other parts of the code - internal/ingress/types.go.</li> <li>supported annotations and its parsing logics - internal/ingress/annotations.</li> <li>reconciliation loops and logics - internal/ingress/controller</li> <li>defaults - define the default struct - internal/ingress/defaults.</li> <li>Error interface and types implementation - internal/ingress/errors</li> <li>Metrics collectors for Prometheus exporting - internal/ingress/metric.</li> <li>Resolver - Extracts information from a controller - internal/ingress/resolver.</li> <li>Ingress Object status publisher - internal/ingress/status.</li> </ul> <p>And other parts of the code that will be written in this document in a future.</p>"},{"location":"developer-guide/code-overview/#k8s-functions","title":"K8s functions","text":"<p>Contains helper functions for parsing Kubernetes objects.</p> <p>This part of the code can be found in internal/k8s directory.</p>"},{"location":"developer-guide/code-overview/#networking-functions","title":"Networking functions","text":"<p>Contains helper functions for networking, such as IPv4 and IPv6 parsing, SSL certificate parsing, etc.</p> <p>This part of the code can be found in internal/net directory.</p>"},{"location":"developer-guide/code-overview/#nginx-functions","title":"NGINX functions","text":"<p>Contains helper function to deal with NGINX, such as verify if it's running and reading it's configuration file parts.</p> <p>This part of the code can be found in internal/nginx directory.</p>"},{"location":"developer-guide/code-overview/#tasks-queue","title":"Tasks / Queue","text":"<p>Contains the functions responsible for the sync queue part of the controller.</p> <p>This part of the code can be found in internal/task directory.</p>"},{"location":"developer-guide/code-overview/#other-parts-of-internal","title":"Other parts of internal","text":"<p>Other parts of internal code might not be covered here, like runtime and watch but they can be added in a future.</p>"},{"location":"developer-guide/code-overview/#e2e-test","title":"E2E Test","text":"<p>The e2e tests code is in test directory.</p>"},{"location":"developer-guide/code-overview/#other-programs","title":"Other programs","text":"<p>Describe here <code>kubectl plugin</code>, <code>dbg</code>, <code>waitshutdown</code> and cover the hack scripts.</p>"},{"location":"developer-guide/code-overview/#kubectl-plugin","title":"kubectl plugin","text":"<p>It contains kubectl plugin for inspecting your ingress-nginx deployments. This part of code can be found in cmd/plugin directory Detail functions flow and available flow can be found in kubectl-plugin</p>"},{"location":"developer-guide/code-overview/#deploy-files","title":"Deploy files","text":"<p>This directory contains the <code>yaml</code> deploy files used as examples or references in the docs to deploy Ingress NGINX and other components.</p> <p>Those files are in deploy directory.</p>"},{"location":"developer-guide/code-overview/#helm-chart","title":"Helm Chart","text":"<p>Used to generate the Helm chart published.</p> <p>Code is in charts/ingress-nginx.</p>"},{"location":"developer-guide/code-overview/#documentationwebsite","title":"Documentation/Website","text":"<p>The documentation used to generate the website https://kubernetes.github.io/ingress-nginx/</p> <p>This code is available in docs and it's main \"language\" is <code>Markdown</code>, used by mkdocs file to generate static pages.</p>"},{"location":"developer-guide/code-overview/#container-images","title":"Container Images","text":"<p>Container images used to run ingress-nginx, or to build the final image.</p>"},{"location":"developer-guide/code-overview/#base-images","title":"Base Images","text":"<p>Contains the <code>Dockerfiles</code> and scripts used to build base images that are used in other parts of the repo. They are present in images repo. Some examples: * nginx - The base NGINX image ingress-nginx uses is not a vanilla NGINX. It bundles many libraries together and it is a job in itself to maintain that and keep things up-to-date. * custom-error-pages - Used on the custom error page examples.</p> <p>There are other images inside this directory.</p>"},{"location":"developer-guide/code-overview/#ingress-controller-image","title":"Ingress Controller Image","text":"<p>The image used to build the final ingress controller, used in deploy scripts and Helm charts. </p> <p>This is NGINX with some Lua enhancement. We do dynamic certificate, endpoints handling, canary traffic split, custom load balancing etc at this component. One can also add new functionalities using Lua plugin system.</p> <p>The files are in rootfs directory and contains:</p> <ul> <li>The Dockerfile</li> <li>nginx config</li> </ul>"},{"location":"developer-guide/code-overview/#ingress-nginx-lua-scripts","title":"Ingress NGINX Lua Scripts","text":"<p>Ingress NGINX uses Lua Scripts to enable features like hot reloading, rate limiting and monitoring. Some are written using the OpenResty helper.</p> <p>The directory containing Lua scripts is rootfs/etc/nginx/lua.</p>"},{"location":"developer-guide/code-overview/#nginx-go-template-file","title":"Nginx Go template file","text":"<p>One of the functions of Ingress NGINX is to turn Ingress objects into nginx.conf file. </p> <p>To do so, the final step is to apply those configurations in nginx.tmpl turning it into a final nginx.conf file.</p>"},{"location":"developer-guide/getting-started/","title":"Getting Started","text":"<p>Developing for Ingress-Nginx Controller</p> <p>This document explains how to get started with developing for Ingress-Nginx Controller.</p> <p>For the really new contributors, who want to contribute to the INGRESS-NGINX project, but need help with understanding some basic concepts, that are needed to work with the Kubernetes ingress resource, here is a link to the New Contributors Guide. This guide contains tips on how a http/https request travels, from a browser or a curl command, to the webserver process running inside a container, in a pod, in a Kubernetes cluster, but enters the cluster via a ingress resource. For those who are familiar with those basic networking concepts like routing of a packet with regards to a http request, termination of connection, reverseproxy etc. etc., you can skip this and move on to the sections below. (or read it anyways just for context and also provide feedbacks if any)</p>"},{"location":"developer-guide/getting-started/#prerequisites","title":"Prerequisites","text":"<p>Install Go 1.14 or later.</p> <p>Note</p> <p>The project uses Go Modules</p> <p>Install Docker (v19.03.0 or later with experimental feature on)</p> <p>Important</p> <p>The majority of make tasks run as docker containers</p>"},{"location":"developer-guide/getting-started/#quick-start","title":"Quick Start","text":"<ol> <li>Fork the repository</li> <li>Clone the repository to any location in your work station</li> <li>Add a <code>GO111MODULE</code> environment variable with <code>export GO111MODULE=on</code></li> <li>Run <code>go mod download</code> to install dependencies</li> </ol>"},{"location":"developer-guide/getting-started/#local-build","title":"Local build","text":"<p>Start a local Kubernetes cluster using kind, build and deploy the ingress controller</p> <p><pre><code>make dev-env\n</code></pre> - If you are working on the v1.x.x version of this controller, and you want to create a cluster with kubernetes version 1.22, then please visit the documentation for kind, and look for how to set a custom image for the kind node (image: kindest/node...), in the kind config file.</p>"},{"location":"developer-guide/getting-started/#testing","title":"Testing","text":"<p>Run go unit tests</p> <pre><code>make test\n</code></pre> <p>Run unit-tests for lua code</p> <pre><code>make lua-test\n</code></pre> <p>Lua tests are located in the directory <code>rootfs/etc/nginx/lua/test</code></p> <p>Important</p> <p>Test files must follow the naming convention <code>&lt;mytest&gt;_test.lua</code> or it will be ignored</p> <p>Run e2e test suite</p> <pre><code>make kind-e2e-test\n</code></pre> <p>To limit the scope of the tests to execute, we can use the environment variable <code>FOCUS</code></p> <pre><code>FOCUS=\"no-auth-locations\" make kind-e2e-test\n</code></pre> <p>Note</p> <p>The variable <code>FOCUS</code> defines Ginkgo Focused Specs</p> <p>Valid values are defined in the describe definition of the e2e tests like Default Backend</p> <p>The complete list of tests can be found here</p>"},{"location":"developer-guide/getting-started/#custom-docker-image","title":"Custom docker image","text":"<p>In some cases, it can be useful to build a docker image and publish such an image to a private or custom registry location.</p> <p>This can be done setting two environment variables, <code>REGISTRY</code> and <code>TAG</code></p> <pre><code>export TAG=\"dev\"\nexport REGISTRY=\"$USER\"\n\nmake build image\n</code></pre> <p>and then publish such version with</p> <pre><code>docker push $REGISTRY/controller:$TAG\n</code></pre>"},{"location":"enhancements/","title":"Kubernetes Enhancement Proposals (KEPs)","text":"<p>A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the <code>ingress-nginx</code> project is adopting it.</p>"},{"location":"enhancements/#quick-start-for-the-kep-process","title":"Quick start for the KEP process","text":"<p>Follow the process outlined in the KEP template</p>"},{"location":"enhancements/#do-i-have-to-use-the-kep-process","title":"Do I have to use the KEP process?","text":"<p>No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record.</p> <p>KEPs are only required when the changes are wide ranging and impact most of the project.</p>"},{"location":"enhancements/#why-would-i-want-to-use-the-kep-process","title":"Why would I want to use the KEP process?","text":"<p>Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata.</p> <p>Benefits to KEP users (in the limit):</p> <ul> <li>Exposure on a kubernetes blessed web site that is findable via web search engines.</li> <li>Cross indexing of KEPs so that users can find connections and the current status of any KEP.</li> <li>A clear process with approvers and reviewers for making decisions.   This will lead to more structured decisions that stick as there is a discoverable record around the decisions.</li> </ul> <p>We are inspired by IETF RFCs, Python PEPs, and Rust RFCs.</p>"},{"location":"enhancements/20190724-only-dynamic-ssl/","title":"Remove static SSL configuration mode","text":""},{"location":"enhancements/20190724-only-dynamic-ssl/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Summary</li> <li>Motivation</li> <li>Goals</li> <li>Non-Goals</li> <li>Proposal</li> <li>Implementation Details/Notes/Constraints</li> <li>Drawbacks</li> <li>Alternatives</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#summary","title":"Summary","text":"<p>Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic.</p>"},{"location":"enhancements/20190724-only-dynamic-ssl/#motivation","title":"Motivation","text":"<p>The static configuration implies reloads, something that affects the majority of the users.</p>"},{"location":"enhancements/20190724-only-dynamic-ssl/#goals","title":"Goals","text":"<ul> <li>Deprecation of the flag <code>--enable-dynamic-certificates</code>.</li> <li>Cleanup of the codebase.</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#non-goals","title":"Non-Goals","text":"<ul> <li>Features related to certificate authentication are not changed in any way.</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#proposal","title":"Proposal","text":"<ul> <li>Remove static SSL configuration</li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#implementation-detailsnotesconstraints","title":"Implementation Details/Notes/Constraints","text":"<ul> <li>Deprecate the flag Move the directives <code>ssl_certificate</code> and <code>ssl_certificate_key</code> from each server block to the <code>http</code> section. These settings are required to avoid NGINX errors in the logs.</li> <li>Remove any action of the flag <code>--enable-dynamic-certificates</code></li> </ul>"},{"location":"enhancements/20190724-only-dynamic-ssl/#drawbacks","title":"Drawbacks","text":""},{"location":"enhancements/20190724-only-dynamic-ssl/#alternatives","title":"Alternatives","text":"<p>Keep both implementations</p>"},{"location":"enhancements/20190815-zone-aware-routing/","title":"Availability zone aware routing","text":""},{"location":"enhancements/20190815-zone-aware-routing/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Availability zone aware routing</li> <li>Table of Contents</li> <li>Summary</li> <li>Motivation<ul> <li>Goals</li> <li>Non-Goals</li> </ul> </li> <li>Proposal</li> <li>Implementation History</li> <li>Drawbacks [optional]</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#summary","title":"Summary","text":"<p>Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint.</p>"},{"location":"enhancements/20190815-zone-aware-routing/#motivation","title":"Motivation","text":"<p>When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money.</p> <p>At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic.</p> <p>This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost.</p> <p>Arguably inter-zone network latency should also be better than cross-zone.</p>"},{"location":"enhancements/20190815-zone-aware-routing/#goals","title":"Goals","text":"<ul> <li>Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying</li> <li>This should not impact canary feature</li> <li>ingress-nginx should be able to operate successfully if there are no zonal endpoints</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#non-goals","title":"Non-Goals","text":"<ul> <li>This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone</li> <li>This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#proposal","title":"Proposal","text":"<p>The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior.</p> <p>Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that.</p> <p>How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the <code>failure-domain.beta.kubernetes.io/zone</code> annotation. Then we can pass that value to Lua land through Nginx configuration when loading <code>lua_ingress.lua</code> module in <code>init_by_lua</code> phase.</p> <p>How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using <code>.subsets.addresses[i].nodeName</code> and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes <code>failure-domain.beta.kubernetes.io/zone</code> annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead.</p> <p>Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on,  it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded.</p> <p>How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer.</p> <p>We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem.</p>"},{"location":"enhancements/20190815-zone-aware-routing/#implementation-history","title":"Implementation History","text":"<ul> <li>initial version of KEP is shipped</li> <li>proposal and implementation details are done</li> </ul>"},{"location":"enhancements/20190815-zone-aware-routing/#drawbacks-optional","title":"Drawbacks [optional]","text":"<p>More load on the Kubernetes API server.</p>"},{"location":"enhancements/20231001-split-containers/","title":"Proposal to split containers","text":"<ul> <li>All the NGINX files should live on one container</li> <li>No file other than NGINX files should exist on this container</li> <li>This includes not mounting the service account</li> <li>All the controller files should live on a different container</li> <li>Controller container should have bare minimum to work (just go program)</li> <li> <p>ServiceAccount should be mounted just on controller</p> </li> <li> <p>Inside nginx container, there should be a really small http listener just able  to start, stop and reload NGINX</p> </li> </ul>"},{"location":"enhancements/20231001-split-containers/#roadmap-what-needs-to-be-done","title":"Roadmap (what needs to be done)","text":"<ul> <li>Map what needs to be done to mount the SA just on controller container</li> <li>Map all the required files for NGINX to work</li> <li>Map all the required network calls between controller and NGINX</li> <li>eg.: Dynamic lua reconfiguration</li> <li>Map problematic features that will need attention</li> <li>SSLPassthrough today happens on controller process and needs to happen on NGINX</li> </ul>"},{"location":"enhancements/20231001-split-containers/#ports-and-endpoints-on-nginx-container","title":"Ports and endpoints on NGINX container","text":"<ul> <li>Public HTTP/HTTPs port - 80 and 443</li> <li>Lua configuration port - 10246 (HTTP) and 10247 (Stream)</li> <li>3333 (temp) - Dataplane controller http server</li> <li>/reload - (POST) Reloads the configuration.<ul> <li>\"config\" argument is the location of temporary file that should be used / moved to nginx.conf</li> </ul> </li> <li>/test - (POST) Test the configuration of a given file location<ul> <li>\"config\" argument is the location of temporary file that should be tested</li> </ul> </li> </ul>"},{"location":"enhancements/20231001-split-containers/#mounting-empty-sa-on-controller-container","title":"Mounting empty SA on controller container","text":"<pre><code>kind: Pod\napiVersion: v1\nmetadata:\n  name: test\nspec:\n  containers:\n  - name: nginx\n    image: nginx:latest\n    ports:\n    - containerPort: 80\n  - name: othernginx\n    image: alpine:latest\n    command: [\"/bin/sh\"]\n    args: [\"-c\", \"while true; do date; sleep 3; done\"]\n    volumeMounts:\n    - mountPath: /var/run/secrets/kubernetes.io/serviceaccount\n      name: emptysecret\n  volumes:\n  - name: emptysecret\n    emptyDir:\n      sizeLimit: 1Mi\n</code></pre>"},{"location":"enhancements/20231001-split-containers/#mapped-folders-on-nginx-configuration","title":"Mapped folders on NGINX configuration","text":"<p>WARNING We need to be aware of inter mount containers and inode problems. If we  mount a file instead of a directory, it may take time to reflect the file value on  the target container</p> <ul> <li>\"/etc/nginx/lua/?.lua;/etc/nginx/lua/vendor/?.lua;;\"; - Lua scripts</li> <li>\"/var/log/nginx\" - NGINX logs</li> <li>\"/tmp/nginx (nginx.pid)\" - NGINX pid directory / file, fcgi socket, etc</li> <li>\" /etc/nginx/geoip\" - GeoIP database directory - OK - /etc/ingress-controller/geoip</li> <li>/etc/nginx/mime.types - Mime types</li> <li>/etc/ingress-controller/ssl - SSL directory (fake cert, auth cert)</li> <li>/etc/ingress-controller/auth - Authentication files</li> <li>/etc/nginx/modsecurity - Modsecurity configuration</li> <li>/etc/nginx/owasp-modsecurity-crs - Modsecurity rules</li> <li>/etc/nginx/tickets.key - SSL tickets - OK - /etc/ingress-controller/tickets.key</li> <li>/etc/nginx/opentelemetry.toml - OTEL config - OK - /etc/ingress-controller/telemetry</li> <li>/etc/nginx/opentracing.json - Opentracing config - OK - /etc/ingress-controller/telemetry</li> <li>/etc/nginx/modules - NGINX modules</li> <li>/etc/nginx/fastcgi_params (maybe) - fcgi params</li> <li>/etc/nginx/template - Template, may be used by controller only</li> </ul>"},{"location":"enhancements/20231001-split-containers/#list-of-modules","title":"List of modules","text":"<pre><code>ngx_http_auth_digest_module.so    ngx_http_modsecurity_module.so\nngx_http_brotli_filter_module.so  ngx_http_opentracing_module.so\nngx_http_brotli_static_module.so  ngx_stream_geoip2_module.so\nngx_http_geoip2_module.so\n</code></pre>"},{"location":"enhancements/20231001-split-containers/#list-of-files-that-may-be-removed","title":"List of files that may be removed","text":"<pre><code>-rw-r--r--    1 www-data www-data      1077 Jun 23 19:44 fastcgi.conf\n-rw-r--r--    1 www-data www-data      1077 Jun 23 19:44 fastcgi.conf.default\n-rw-r--r--    1 www-data www-data      1007 Jun 23 19:44 fastcgi_params\n-rw-r--r--    1 www-data www-data      1007 Jun 23 19:44 fastcgi_params.default\ndrwxr-xr-x    2 www-data www-data      4096 Jun 23 19:34 geoip\n-rw-r--r--    1 www-data www-data      2837 Jun 23 19:44 koi-utf\n-rw-r--r--    1 www-data www-data      2223 Jun 23 19:44 koi-win\ndrwxr-xr-x    6 www-data www-data      4096 Sep 19 14:13 lua\n-rw-r--r--    1 www-data www-data      5349 Jun 23 19:44 mime.types\n-rw-r--r--    1 www-data www-data      5349 Jun 23 19:44 mime.types.default\ndrwxr-xr-x    2 www-data www-data      4096 Jun 23 19:44 modsecurity\ndrwxr-xr-x    2 www-data www-data      4096 Jun 23 19:44 modules\n-rw-r--r--    1 www-data www-data     18275 Oct  1 21:28 nginx.conf\n-rw-r--r--    1 www-data www-data      2656 Jun 23 19:44 nginx.conf.default\n-rwx------    1 www-data www-data       420 Oct  1 21:28 opentelemetry.toml\n-rw-r--r--    1 www-data www-data         2 Oct  1 21:28 opentracing.json\ndrwxr-xr-x    7 www-data www-data      4096 Jun 23 19:44 owasp-modsecurity-crs\n-rw-r--r--    1 www-data www-data       636 Jun 23 19:44 scgi_params\n-rw-r--r--    1 www-data www-data       636 Jun 23 19:44 scgi_params.default\ndrwxr-xr-x    2 www-data www-data      4096 Sep 19 14:13 template\n-rw-r--r--    1 www-data www-data       664 Jun 23 19:44 uwsgi_params\n-rw-r--r--    1 www-data www-data       664 Jun 23 19:44 uwsgi_params.default\n-rw-r--r--    1 www-data www-data      3610 Jun 23 19:44 win-utf\n</code></pre>"},{"location":"enhancements/YYYYMMDD-kep-template/","title":"Title","text":"<p>This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review.</p> <p>The title should be lowercased and spaces/punctuation should be replaced with <code>-</code>.</p> <p>To get started with this template:</p> <ol> <li>Make a copy of this template.   Create a copy of this template and name it <code>YYYYMMDD-my-title.md</code>, where <code>YYYYMMDD</code> is the date the KEP was first drafted.</li> <li>Fill out the \"overview\" sections.   This includes the Summary and Motivation sections.   These should be easy if you've preflighted the idea of the KEP in an issue.</li> <li>Create a PR.   Assign it to folks that are sponsoring this process.</li> <li>Create an issue   When filing an enhancement tracking issue, please ensure to complete all fields in the template.</li> <li>Merge early.   Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly.   The best way to do this is to just start with the \"Overview\" sections and fill out details incrementally in follow on PRs.   View anything marked as a <code>provisional</code> as a working document and subject to change.   Aim for single topic PRs to keep discussions focused.   If you disagree with what is already in a document, open a new PR with suggested changes.</li> </ol> <p>The canonical place for the latest set of instructions (and the likely source of this file) is here.</p> <p>The <code>Metadata</code> section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#table-of-contents","title":"Table of Contents","text":"<p>A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template.</p> <p>Ensure the TOC is wrapped with <code>&lt;!-- toc --&amp;rt;&lt;!-- /toc --&amp;rt;</code> tags, and then generate with <code>hack/update-toc.sh</code>.</p> <ul> <li>Summary</li> <li>Motivation</li> <li>Goals</li> <li>Non-Goals</li> <li>Proposal</li> <li>User Stories [optional]<ul> <li>Story 1</li> <li>Story 2</li> </ul> </li> <li>Implementation Details/Notes/Constraints [optional]</li> <li>Risks and Mitigations</li> <li>Design Details</li> <li>Test Plan<ul> <li>Removing a deprecated flag</li> </ul> </li> <li>Implementation History</li> <li>Drawbacks [optional]</li> <li>Alternatives [optional]</li> </ul>"},{"location":"enhancements/YYYYMMDD-kep-template/#summary","title":"Summary","text":"<p>The <code>Summary</code> section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself.</p> <p>A good summary is probably at least a paragraph in length.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#motivation","title":"Motivation","text":"<p>This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#goals","title":"Goals","text":"<p>List the specific goals of the KEP. How will we know that this has succeeded?</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#non-goals","title":"Non-Goals","text":"<p>What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#proposal","title":"Proposal","text":"<p>This is where we get down to the nitty gritty of what the proposal actually is.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#user-stories-optional","title":"User Stories [optional]","text":"<p>Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the \"how\" of the system. The goal here is to make this feel real for users without getting bogged down.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#story-1","title":"Story 1","text":""},{"location":"enhancements/YYYYMMDD-kep-template/#story-2","title":"Story 2","text":""},{"location":"enhancements/YYYYMMDD-kep-template/#implementation-detailsnotesconstraints-optional","title":"Implementation Details/Notes/Constraints [optional]","text":"<p>What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#risks-and-mitigations","title":"Risks and Mitigations","text":"<p>What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem.</p> <p>How will security be reviewed and by whom? How will UX be reviewed and by whom?</p> <p>Consider including folks that also work outside project.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#design-details","title":"Design Details","text":""},{"location":"enhancements/YYYYMMDD-kep-template/#test-plan","title":"Test Plan","text":"<p>Note: Section not required until targeted at a release.</p> <p>Consider the following in developing a test plan for this enhancement:</p> <ul> <li>Will there be e2e and integration tests, in addition to unit tests?</li> <li>How will it be tested in isolation vs with other components?</li> </ul> <p>No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out.</p> <p>All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#removing-a-deprecated-flag","title":"Removing a deprecated flag","text":"<ul> <li>Announce deprecation and support policy of the existing flag</li> <li>Two versions passed since introducing the functionality which deprecates the flag (to address version skew)</li> <li>Address feedback on usage/changed behavior, provided on GitHub issues</li> <li>Deprecate the flag</li> </ul>"},{"location":"enhancements/YYYYMMDD-kep-template/#implementation-history","title":"Implementation History","text":"<p>Major milestones in the life cycle of a KEP should be tracked in <code>Implementation History</code>. Major milestones might include</p> <ul> <li>the <code>Summary</code> and <code>Motivation</code> sections being merged signaling acceptance</li> <li>the <code>Proposal</code> section being merged signaling agreement on a proposed design</li> <li>the date implementation started</li> <li>the first Kubernetes release where an initial version of the KEP was available</li> <li>the version of Kubernetes where the KEP graduated to general availability</li> <li>when the KEP was retired or superseded</li> </ul>"},{"location":"enhancements/YYYYMMDD-kep-template/#drawbacks-optional","title":"Drawbacks [optional]","text":"<p>Why should this KEP not be implemented.</p>"},{"location":"enhancements/YYYYMMDD-kep-template/#alternatives-optional","title":"Alternatives [optional]","text":"<p>Similar to the <code>Drawbacks</code> section the <code>Alternatives</code> section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.</p>"},{"location":"examples/","title":"Ingress examples","text":"<p>This directory contains a catalog of examples on how to run, configure and scale Ingress. Please review the prerequisites before trying them.</p> <p>The examples on these pages include the <code>spec.ingressClassName</code> field which replaces the deprecated <code>kubernetes.io/ingress.class: nginx</code> annotation. Users of ingress-nginx &lt; 1.0.0 (Helm chart &lt; 4.0.0) should use the legacy documentation.</p> <p>For more information, check out the Migration to apiVersion networking.k8s.io/v1 guide.</p> Category Name Description Complexity Level Apps Docker Registry TODO TODO Auth Basic authentication password protect your website Intermediate Auth Client certificate authentication secure your website with client certificate authentication Intermediate Auth External authentication plugin defer to an external authentication service Intermediate Auth OAuth external auth TODO TODO Customization Configuration snippets customize nginx location configuration using annotations Advanced Customization Custom configuration TODO TODO Customization Custom DH parameters for perfect forward secrecy TODO TODO Customization Custom errors serve custom error pages from the default backend Intermediate Customization Custom headers set custom headers before sending traffic to backends Advanced Customization External authentication with response header propagation TODO TODO Customization Sysctl tuning TODO TODO Features Rewrite TODO TODO Features Session stickiness route requests consistently to the same endpoint Advanced Features Canary Deployments weighted canary routing to a seperate deployment Intermediate Scaling Static IP a single ingress gets a single static IP Intermediate TLS Multi TLS certificate termination TODO TODO TLS TLS termination TODO TODO"},{"location":"examples/PREREQUISITES/","title":"Prerequisites","text":"<p>Many of the examples in this directory have common prerequisites.</p>"},{"location":"examples/PREREQUISITES/#tls-certificates","title":"TLS certificates","text":"<p>Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows</p> <pre><code>$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj \"/CN=nginxsvc/O=nginxsvc\"\nGenerating a 2048 bit RSA private key\n................+++\n................+++\nwriting new private key to 'tls.key'\n-----\n\n$ kubectl create secret tls tls-secret --key tls.key --cert tls.crt\nsecret \"tls-secret\" created\n</code></pre> <p>Note: If using CA Authentication, described below, you will need to sign the server certificate with the CA.</p>"},{"location":"examples/PREREQUISITES/#client-certificate-authentication","title":"Client Certificate Authentication","text":"<p>CA Authentication also known as Mutual Authentication allows both the server and client to verify each others identity via a common CA.</p> <p>We have a CA Certificate which we usually obtain from a Certificate Authority and use that to sign both our server certificate and client certificate. Then every time we want to access our backend, we must pass the client certificate.</p> <p>These instructions are based on the following blog</p> <p>Generate the CA Key and Certificate:</p> <pre><code>openssl req -x509 -sha256 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 356 -nodes -subj '/CN=My Cert Authority'\n</code></pre> <p>Generate the Server Key, and Certificate and Sign with the CA Certificate:</p> <pre><code>openssl req -new -newkey rsa:4096 -keyout server.key -out server.csr -nodes -subj '/CN=mydomain.com'\nopenssl x509 -req -sha256 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt\n</code></pre> <p>Generate the Client Key, and Certificate and Sign with the CA Certificate:</p> <pre><code>openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=My Client'\nopenssl x509 -req -sha256 -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 02 -out client.crt\n</code></pre> <p>Once this is complete you can continue to follow the instructions here</p>"},{"location":"examples/PREREQUISITES/#test-http-service","title":"Test HTTP Service","text":"<p>All examples that require a test HTTP Service use the standard http-svc pod, which you can deploy as follows</p> <pre><code>$ kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/http-svc.yaml\nservice \"http-svc\" created\nreplicationcontroller \"http-svc\" created\n\n$ kubectl get po\nNAME             READY     STATUS    RESTARTS   AGE\nhttp-svc-p1t3t   1/1       Running   0          1d\n\n$ kubectl get svc\nNAME             CLUSTER-IP     EXTERNAL-IP   PORT(S)            AGE\nhttp-svc         10.0.122.116   &lt;pending&gt;     80:30301/TCP       1d\n</code></pre> <p>You can test that the HTTP Service works by exposing it temporarily</p> <pre><code>$ kubectl patch svc http-svc -p '{\"spec\":{\"type\": \"LoadBalancer\"}}'\n\"http-svc\" patched\n\n$ kubectl get svc http-svc\nNAME             CLUSTER-IP     EXTERNAL-IP   PORT(S)            AGE\nhttp-svc         10.0.122.116   &lt;pending&gt;     80:30301/TCP       1d\n\n$ kubectl describe svc http-svc\nName:                   http-svc\nNamespace:              default\nLabels:                 app=http-svc\nSelector:               app=http-svc\nType:                   LoadBalancer\nIP:                     10.0.122.116\nLoadBalancer Ingress:   108.59.87.136\nPort:                   http    80/TCP\nNodePort:               http    30301/TCP\nEndpoints:              10.180.1.6:8080\nSession Affinity:       None\nEvents:\n  FirstSeen LastSeen    Count   From            SubObjectPath   Type        Reason          Message\n  --------- --------    -----   ----            -------------   --------    ------          -------\n  1m        1m      1   {service-controller }           Normal      Type            ClusterIP -&gt; LoadBalancer\n  1m        1m      1   {service-controller }           Normal      CreatingLoadBalancer    Creating load balancer\n  16s       16s     1   {service-controller }           Normal      CreatedLoadBalancer Created load balancer\n\n$ curl 108.59.87.136\nCLIENT VALUES:\nclient_address=10.240.0.3\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://108.59.87.136:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nhost=108.59.87.136\nuser-agent=curl/7.46.0\nBODY:\n-no body in request-\n\n$ kubectl patch svc http-svc -p '{\"spec\":{\"type\": \"NodePort\"}}'\n\"http-svc\" patched\n</code></pre>"},{"location":"examples/affinity/cookie/","title":"Sticky sessions","text":"<p>This example demonstrates how to achieve session affinity using cookies.</p>"},{"location":"examples/affinity/cookie/#deployment","title":"Deployment","text":"<p>Session affinity can be configured using the following annotations:</p> Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to <code>cookie</code> to enable session affinity string (NGINX only supports <code>cookie</code>) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use <code>balanced</code> to redistribute some sessions when scaling pods or <code>persistent</code> for maximum stickiness. <code>balanced</code> (default) or <code>persistent</code> nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is <code>sticky</code>, and canaries respect session affinity configuration. Set this to <code>legacy</code> to restore original canary behavior, when session affinity parameters were not respected. <code>sticky</code> (default) or <code>legacy</code> nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to <code>INGRESSCOOKIE</code>) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request <code>\"true\"</code> or <code>\"false\"</code> nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite <code>SameSite</code> attribute to apply to the cookie Browser accepted values are <code>None</code>, <code>Lax</code>, and <code>Strict</code> nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit <code>SameSite=None</code> attribute for older browsers which reject the more-recently defined <code>SameSite=None</code> value <code>\"true\"</code> or <code>\"false\"</code> nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the <code>Max-Age</code> cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an <code>Expires</code> cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to <code>false</code> nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to <code>true</code> and previous attempt failed, sticky cookie will be changed to point to another upstream. <code>true</code> or <code>false</code> (defaults to <code>false</code>) <p>You can create the session affinity example Ingress to test this:</p> <pre><code>kubectl create -f ingress.yaml\n</code></pre>"},{"location":"examples/affinity/cookie/#validation","title":"Validation","text":"<p>You can confirm that the Ingress works:</p> <pre><code>$ kubectl describe ing nginx-test\nName:           nginx-test\nNamespace:      default\nAddress:\nDefault backend:    default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)\nRules:\n  Host                          Path    Backends\n  ----                          ----    --------\n  stickyingress.example.com\n                                /        nginx-service:80 (&lt;none&gt;)\nAnnotations:\n  affinity: cookie\n  session-cookie-name:      INGRESSCOOKIE\n  session-cookie-expires: 172800\n  session-cookie-max-age: 172800\nEvents:\n  FirstSeen LastSeen    Count   From                SubObjectPath   Type        Reason  Message\n  --------- --------    -----   ----                -------------   --------    ------  -------\n  7s        7s      1   {ingress-nginx-controller }         Normal      CREATE  default/nginx-test\n\n\n$ curl -I http://stickyingress.example.com\nHTTP/1.1 200 OK\nServer: nginx/1.11.9\nDate: Fri, 10 Feb 2017 14:11:12 GMT\nContent-Type: text/html\nContent-Length: 612\nConnection: keep-alive\nSet-Cookie: INGRESSCOOKIE=a9907b79b248140b56bb13723f72b67697baac3d; Expires=Sun, 12-Feb-17 14:11:12 GMT; Max-Age=172800; Path=/; HttpOnly\nLast-Modified: Tue, 24 Jan 2017 14:02:19 GMT\nETag: \"58875e6b-264\"\nAccept-Ranges: bytes\n</code></pre> <p>In the example above, you can see that the response contains a <code>Set-Cookie</code> header with the settings we have defined. This cookie is created by the Ingress-Nginx Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an <code>Expires</code> directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie.</p> <p>If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded.</p> <p>When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change.</p>"},{"location":"examples/affinity/cookie/#caveats","title":"Caveats","text":"<p>When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this.</p>"},{"location":"examples/auth/basic/","title":"Basic Authentication","text":"<p>This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with <code>htpasswd</code>. It's important the file generated is named <code>auth</code> (actually - that the secret has a key <code>data.auth</code>), otherwise the ingress-controller returns a 503.</p>"},{"location":"examples/auth/basic/#create-htpasswd-file","title":"Create htpasswd file","text":"<pre><code>$ htpasswd -c auth foo\nNew password: &lt;bar&gt;\nNew password:\nRe-type new password:\nAdding password for user foo\n</code></pre>"},{"location":"examples/auth/basic/#convert-htpasswd-into-a-secret","title":"Convert htpasswd into a secret","text":"<pre><code>$ kubectl create secret generic basic-auth --from-file=auth\nsecret \"basic-auth\" created\n</code></pre>"},{"location":"examples/auth/basic/#examine-secret","title":"Examine secret","text":"<pre><code>$ kubectl get secret basic-auth -o yaml\napiVersion: v1\ndata:\n  auth: Zm9vOiRhcHIxJE9GRzNYeWJwJGNrTDBGSERBa29YWUlsSDkuY3lzVDAK\nkind: Secret\nmetadata:\n  name: basic-auth\n  namespace: default\ntype: Opaque\n</code></pre>"},{"location":"examples/auth/basic/#using-kubectl-create-an-ingress-tied-to-the-basic-auth-secret","title":"Using kubectl, create an ingress tied to the basic-auth secret","text":"<pre><code>$ echo \"\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-with-auth\n  annotations:\n    # type of authentication\n    nginx.ingress.kubernetes.io/auth-type: basic\n    # name of the secret that contains the user/password definitions\n    nginx.ingress.kubernetes.io/auth-secret: basic-auth\n    # message to display with an appropriate context why the authentication is required\n    nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required - foo'\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: foo.bar.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service: \n            name: http-svc\n            port: \n              number: 80\n\" | kubectl create -f -\n</code></pre>"},{"location":"examples/auth/basic/#use-curl-to-confirm-authorization-is-required-by-the-ingress","title":"Use curl to confirm authorization is required by the ingress","text":"<pre><code>$ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com'\n*   Trying 10.2.29.4...\n* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: foo.bar.com\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 401 Unauthorized\n&lt; Server: nginx/1.10.0\n&lt; Date: Wed, 11 May 2016 05:27:23 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 195\n&lt; Connection: keep-alive\n&lt; WWW-Authenticate: Basic realm=\"Authentication Required - foo\"\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;401 Authorization Required&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;401 Authorization Required&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.10.0&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 10.2.29.4 left intact\n</code></pre>"},{"location":"examples/auth/basic/#use-curl-with-the-correct-credentials-to-connect-to-the-ingress","title":"Use curl with the correct credentials to connect to the ingress","text":"<pre><code>$ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com' -u 'foo:bar'\n*   Trying 10.2.29.4...\n* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0)\n* Server auth using Basic with user 'foo'\n&gt; GET / HTTP/1.1\n&gt; Host: foo.bar.com\n&gt; Authorization: Basic Zm9vOmJhcg==\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.10.0\n&lt; Date: Wed, 11 May 2016 06:05:26 GMT\n&lt; Content-Type: text/plain\n&lt; Transfer-Encoding: chunked\n&lt; Connection: keep-alive\n&lt; Vary: Accept-Encoding\n&lt;\nCLIENT VALUES:\nclient_address=10.2.29.4\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://foo.bar.com:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nconnection=close\nhost=foo.bar.com\nuser-agent=curl/7.43.0\nx-request-id=e426c7829ef9f3b18d40730857c3eddb\nx-forwarded-for=10.2.29.1\nx-forwarded-host=foo.bar.com\nx-forwarded-port=80\nx-forwarded-proto=http\nx-real-ip=10.2.29.1\nx-scheme=http\nBODY:\n* Connection #0 to host 10.2.29.4 left intact\n-no body in request-\n</code></pre>"},{"location":"examples/auth/client-certs/","title":"Client Certificate Authentication","text":"<p>It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource.</p> <p>Before getting started you must have the following Certificates configured:</p> <ol> <li>CA certificate and Key (Intermediate Certs need to be in CA)</li> <li>Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use)</li> <li>Client Certificate (Signed by CA) and Key</li> </ol> <p>For more details on the generation process, checkout the Prerequisite docs.</p> <p>You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following:</p> <pre><code>openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem\n</code></pre> <p>Then, you can concatenate them all into one file, named 'ca.crt' with the following:</p> <pre><code>cat certificate1.crt certificate2.crt certificate3.crt &gt;&gt; ca.crt\n</code></pre> <p>Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error.</p>"},{"location":"examples/auth/client-certs/#creating-certificate-secrets","title":"Creating Certificate Secrets","text":"<p>There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly.</p> <ul> <li> <p>You can create a secret containing just the CA certificate and another     Secret containing the Server Certificate which is Signed by the CA.</p> <pre><code>kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt\nkubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key\n</code></pre> </li> <li> <p>You can create a secret containing CA certificate along with the Server     Certificate that can be used for both TLS and Client Auth.</p> <pre><code>kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt\n</code></pre> </li> <li> <p>If you want to also enable Certificate Revocation List verification you can    create the secret also containing the CRL file in PEM format:    <pre><code>kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt --from-file=ca.crl=ca.crl\n</code></pre></p> </li> </ul> <p>Note: The CA Certificate must contain the trusted certificate authority chain to verify client certificates.</p>"},{"location":"examples/auth/client-certs/#setup-instructions","title":"Setup Instructions","text":"<ol> <li>Add the annotations as provided in the ingress.yaml example to your own ingress resources as required.</li> <li>Test by performing a curl against the Ingress Path without the Client Cert and expect a Status Code 400.</li> <li>Test by performing a curl against the Ingress Path with the Client Cert and expect a Status Code 200.</li> </ol>"},{"location":"examples/auth/external-auth/","title":"External Basic Authentication","text":""},{"location":"examples/auth/external-auth/#example-1","title":"Example 1","text":"<p>Use an external service (Basic Auth) located in <code>https://httpbin.org</code></p> <pre><code>$ kubectl create -f ingress.yaml\ningress \"external-auth\" created\n\n$ kubectl get ing external-auth\nNAME            HOSTS                         ADDRESS       PORTS     AGE\nexternal-auth   external-auth-01.sample.com   172.17.4.99   80        13s\n\n$ kubectl get ing external-auth -o yaml\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd\n  creationTimestamp: 2016-10-03T13:50:35Z\n  generation: 1\n  name: external-auth\n  namespace: default\n  resourceVersion: \"2068378\"\n  selfLink: /apis/networking/v1/namespaces/default/ingresses/external-auth\n  uid: 5c388f1d-8970-11e6-9004-080027d2dc94\nspec:\n  rules:\n  - host: external-auth-01.sample.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service: \n            name: http-svc\n            port: \n              number: 80\nstatus:\n  loadBalancer:\n    ingress:\n    - ip: 172.17.4.99\n$\n</code></pre>"},{"location":"examples/auth/external-auth/#test-1-no-usernamepassword-expect-code-401","title":"Test 1: no username/password (expect code 401)","text":"<pre><code>$ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com'\n* Rebuilt URL to: http://172.17.4.99/\n*   Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: external-auth-01.sample.com\n&gt; User-Agent: curl/7.50.1\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 401 Unauthorized\n&lt; Server: nginx/1.11.3\n&lt; Date: Mon, 03 Oct 2016 14:52:08 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 195\n&lt; Connection: keep-alive\n&lt; WWW-Authenticate: Basic realm=\"Fake Realm\"\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;401 Authorization Required&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;401 Authorization Required&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.11.3&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 172.17.4.99 left intact\n</code></pre>"},{"location":"examples/auth/external-auth/#test-2-valid-usernamepassword-expect-code-200","title":"Test 2: valid username/password (expect code 200)","text":"<pre><code>$ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:passwd'\n* Rebuilt URL to: http://172.17.4.99/\n*   Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n* Server auth using Basic with user 'user'\n&gt; GET / HTTP/1.1\n&gt; Host: external-auth-01.sample.com\n&gt; Authorization: Basic dXNlcjpwYXNzd2Q=\n&gt; User-Agent: curl/7.50.1\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.3\n&lt; Date: Mon, 03 Oct 2016 14:52:50 GMT\n&lt; Content-Type: text/plain\n&lt; Transfer-Encoding: chunked\n&lt; Connection: keep-alive\n&lt;\nCLIENT VALUES:\nclient_address=10.2.60.2\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://external-auth-01.sample.com:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nauthorization=Basic dXNlcjpwYXNzd2Q=\nconnection=close\nhost=external-auth-01.sample.com\nuser-agent=curl/7.50.1\nx-forwarded-for=10.2.60.1\nx-forwarded-host=external-auth-01.sample.com\nx-forwarded-port=80\nx-forwarded-proto=http\nx-real-ip=10.2.60.1\nBODY:\n* Connection #0 to host 172.17.4.99 left intact\n-no body in request-\n</code></pre>"},{"location":"examples/auth/external-auth/#test-3-invalid-usernamepassword-expect-code-401","title":"Test 3: invalid username/password (expect code 401)","text":"<pre><code>curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:user'\n* Rebuilt URL to: http://172.17.4.99/\n*   Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n* Server auth using Basic with user 'user'\n&gt; GET / HTTP/1.1\n&gt; Host: external-auth-01.sample.com\n&gt; Authorization: Basic dXNlcjp1c2Vy\n&gt; User-Agent: curl/7.50.1\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 401 Unauthorized\n&lt; Server: nginx/1.11.3\n&lt; Date: Mon, 03 Oct 2016 14:53:04 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 195\n&lt; Connection: keep-alive\n* Authentication problem. Ignoring this.\n&lt; WWW-Authenticate: Basic realm=\"Fake Realm\"\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;401 Authorization Required&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;401 Authorization Required&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.11.3&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 172.17.4.99 left intact\n</code></pre>"},{"location":"examples/auth/oauth-external-auth/","title":"External OAUTH Authentication","text":""},{"location":"examples/auth/oauth-external-auth/#overview","title":"Overview","text":"<p>The <code>auth-url</code> and <code>auth-signin</code> annotations allow you to use an external authentication provider to protect your Ingress resources.</p> <p>Important</p> <p>This annotation requires <code>ingress-nginx-controller v0.9.0</code> or greater.</p>"},{"location":"examples/auth/oauth-external-auth/#key-detail","title":"Key Detail","text":"<p>This functionality is enabled by deploying multiple Ingress objects for a single host. One Ingress object has no special annotations and handles authentication.</p> <p>Other Ingress objects can then be annotated in such a way that require the user to authenticate against the first Ingress's endpoint, and can redirect <code>401</code>s to the same endpoint.</p> <p>Sample:</p> <pre><code>...\nmetadata:\n  name: application\n  annotations:\n    nginx.ingress.kubernetes.io/auth-url: \"https://$host/oauth2/auth\"\n    nginx.ingress.kubernetes.io/auth-signin: \"https://$host/oauth2/start?rd=$escaped_request_uri\"\n...\n</code></pre>"},{"location":"examples/auth/oauth-external-auth/#example-oauth2-proxy-kubernetes-dashboard","title":"Example: OAuth2 Proxy + Kubernetes-Dashboard","text":"<p>This example will show you how to deploy <code>oauth2_proxy</code> into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using GitHub as the OAuth2 provider.</p>"},{"location":"examples/auth/oauth-external-auth/#prepare","title":"Prepare","text":"<ol> <li> <p>Install the kubernetes dashboard</p> <pre><code>kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml\n</code></pre> </li> <li> <p>Create a custom GitHub OAuth application</p> <p></p> <ul> <li>Homepage URL is the FQDN in the Ingress rule, like <code>https://foo.bar.com</code></li> <li>Authorization callback URL is the same as the base FQDN plus <code>/oauth2/callback</code>, like <code>https://foo.bar.com/oauth2/callback</code></li> </ul> <p></p> </li> <li> <p>Configure values in the file <code>oauth2-proxy.yaml</code> with the values:</p> <ul> <li>OAUTH2_PROXY_CLIENT_ID with the github <code>&lt;Client ID&gt;</code></li> <li>OAUTH2_PROXY_CLIENT_SECRET with the github <code>&lt;Client Secret&gt;</code></li> <li>OAUTH2_PROXY_COOKIE_SECRET with value of <code>python -c 'import os,base64; print(base64.b64encode(os.urandom(16)).decode(\"ascii\"))'</code></li> <li>(optional, but recommended) OAUTH2_PROXY_GITHUB_USERS with GitHub usernames to allow to login</li> <li><code>__INGRESS_HOST__</code> with a valid FQDN (e.g. <code>foo.bar.com</code>)</li> <li><code>__INGRESS_SECRET__</code> with a Secret with a valid SSL certificate</li> </ul> </li> <li> <p>Deploy the oauth2 proxy and the ingress rules by running:</p> <pre><code>$ kubectl create -f oauth2-proxy.yaml\n</code></pre> </li> </ol>"},{"location":"examples/auth/oauth-external-auth/#test","title":"Test","text":"<p>Test the integration by accessing the configured URL, e.g. <code>https://foo.bar.com</code></p> <p></p> <p></p> <p></p>"},{"location":"examples/auth/oauth-external-auth/#example-vouch-proxy-kubernetes-dashboard","title":"Example: Vouch Proxy + Kubernetes-Dashboard","text":"<p>This example will show you how to deploy <code>Vouch Proxy</code> into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using GitHub as the OAuth2 provider.</p>"},{"location":"examples/auth/oauth-external-auth/#prepare_1","title":"Prepare","text":"<ol> <li> <p>Install the kubernetes dashboard</p> <pre><code>kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml\n</code></pre> </li> <li> <p>Create a custom GitHub OAuth application</p> <p></p> <ul> <li>Homepage URL is the FQDN in the Ingress rule, like <code>https://foo.bar.com</code></li> <li>Authorization callback URL is the same as the base FQDN plus <code>/oauth2/auth</code>, like <code>https://foo.bar.com/oauth2/auth</code></li> </ul> <p></p> </li> <li> <p>Configure Vouch Proxy values in the file <code>vouch-proxy.yaml</code> with the values:</p> <ul> <li>VOUCH_COOKIE_DOMAIN with value of <code>&lt;Ingress Host&gt;</code></li> <li>OAUTH_CLIENT_ID with the github <code>&lt;Client ID&gt;</code></li> <li>OAUTH_CLIENT_SECRET with the github <code>&lt;Client Secret&gt;</code></li> <li>(optional, but recommended) VOUCH_WHITELIST with GitHub usernames to allow to login</li> <li><code>__INGRESS_HOST__</code> with a valid FQDN (e.g. <code>foo.bar.com</code>)</li> <li><code>__INGRESS_SECRET__</code> with a Secret with a valid SSL certificate</li> </ul> </li> <li> <p>Deploy Vouch Proxy and the ingress rules by running:</p> <pre><code>$ kubectl create -f vouch-proxy.yaml\n</code></pre> </li> </ol>"},{"location":"examples/auth/oauth-external-auth/#test_1","title":"Test","text":"<p>Test the integration by accessing the configured URL, e.g. <code>https://foo.bar.com</code></p> <p></p> <p></p> <p></p>"},{"location":"examples/canary/","title":"Canary","text":"<p>Ingress Nginx Has the ability to handle canary routing by setting specific annotations, the following is an example of how to configure a canary deployment with weighted canary routing.</p>"},{"location":"examples/canary/#create-your-main-deployment-and-service","title":"Create your main deployment and service","text":"<p>This is the main deployment of your application with the service that will be used to route to it</p> <pre><code>echo \"\n---\n# Deployment\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: production\n  labels:\n    app: production\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: production\n  template:\n    metadata:\n      labels:\n        app: production\n    spec:\n      containers:\n      - name: production\n        image: registry.k8s.io/ingress-nginx/e2e-test-echo@sha256:6fc5aa2994c86575975bb20a5203651207029a0d28e3f491d8a127d08baadab4\n        ports:\n        - containerPort: 80\n        env:\n          - name: NODE_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: spec.nodeName\n          - name: POD_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.name\n          - name: POD_NAMESPACE\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.namespace\n          - name: POD_IP\n            valueFrom:\n              fieldRef:\n                fieldPath: status.podIP\n---\n# Service\napiVersion: v1\nkind: Service\nmetadata:\n  name: production\n  labels:\n    app: production\nspec:\n  ports:\n  - port: 80\n    targetPort: 80\n    protocol: TCP\n    name: http\n  selector:\n    app: production\n\" | kubectl apply -f -\n</code></pre>"},{"location":"examples/canary/#create-the-canary-deployment-and-service","title":"Create the canary deployment and service","text":"<p>This is the canary deployment that will take a weighted amount of requests instead of the main deployment</p> <pre><code>echo \"\n---\n# Deployment\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: canary\n  labels:\n    app: canary\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: canary\n  template:\n    metadata:\n      labels:\n        app: canary\n    spec:\n      containers:\n      - name: canary\n        image: registry.k8s.io/ingress-nginx/e2e-test-echo@sha256:6fc5aa2994c86575975bb20a5203651207029a0d28e3f491d8a127d08baadab4\n        ports:\n        - containerPort: 80\n        env:\n          - name: NODE_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: spec.nodeName\n          - name: POD_NAME\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.name\n          - name: POD_NAMESPACE\n            valueFrom:\n              fieldRef:\n                fieldPath: metadata.namespace\n          - name: POD_IP\n            valueFrom:\n              fieldRef:\n                fieldPath: status.podIP\n---\n# Service\napiVersion: v1\nkind: Service\nmetadata:\n  name: canary\n  labels:\n    app: canary\nspec:\n  ports:\n  - port: 80\n    targetPort: 80\n    protocol: TCP\n    name: http\n  selector:\n    app: canary\n\" | kubectl apply -f -\n</code></pre>"},{"location":"examples/canary/#create-ingress-pointing-to-your-main-deployment","title":"Create Ingress Pointing To Your Main Deployment","text":"<p>Next you will need to expose your main deployment with an ingress resource, note there are no canary specific annotations on this ingress</p> <pre><code>echo \"\n---\n# Ingress\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: production\n  annotations:\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: echo.prod.mydomain.com\n    http:\n      paths:\n      - pathType: Prefix\n        path: /\n        backend:\n          service:\n            name: production\n            port:\n              number: 80\n\" | kubectl apply -f -\n</code></pre>"},{"location":"examples/canary/#create-ingress-pointing-to-your-canary-deployment","title":"Create Ingress Pointing To Your Canary Deployment","text":"<p>You will then create an Ingress that has the canary specific configuration, please pay special notice of the following:</p> <ul> <li>The host name is identical to the main ingress host name</li> <li>The <code>nginx.ingress.kubernetes.io/canary: \"true\"</code> annotation is required and   defines this as a canary annotation (if you do not have this the Ingresses   will clash)</li> <li>The <code>nginx.ingress.kubernetes.io/canary-weight: \"50\"</code> annotation dictates the   weight of the routing, in this case there is a \"50%\" chance a request will   hit the canary deployment over the main deployment <pre><code>echo \"\n---\n# Ingress\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: canary\n  annotations:\n    nginx.ingress.kubernetes.io/canary: \\\"true\\\"\n    nginx.ingress.kubernetes.io/canary-weight: \\\"50\\\"\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: echo.prod.mydomain.com\n    http:\n      paths:\n      - pathType: Prefix\n        path: /\n        backend:\n          service:\n            name: canary\n            port:\n              number: 80\n\" | kubectl apply -f -\n</code></pre></li> </ul>"},{"location":"examples/canary/#testing-your-setup","title":"Testing your setup","text":"<p>You can use the following command to test your setup (replacing INGRESS_CONTROLLER_IP with your ingresse controllers IP Address)</p> <pre><code>for i in $(seq 1 10); do curl -s --resolve echo.prod.mydomain.com:80:$INGRESS_CONTROLLER_IP echo.prod.mydomain.com  | grep \"Hostname\"; done\n</code></pre> <p>You will get the following output showing that your canary setup is working as expected:</p> <pre><code>Hostname: production-5c5f65d859-phqzc\nHostname: canary-6697778457-zkfjf\nHostname: canary-6697778457-zkfjf\nHostname: production-5c5f65d859-phqzc\nHostname: canary-6697778457-zkfjf\nHostname: production-5c5f65d859-phqzc\nHostname: production-5c5f65d859-phqzc\nHostname: production-5c5f65d859-phqzc\nHostname: canary-6697778457-zkfjf\nHostname: production-5c5f65d859-phqzc\n</code></pre>"},{"location":"examples/customization/configuration-snippets/","title":"Configuration Snippets","text":""},{"location":"examples/customization/configuration-snippets/#ingress","title":"Ingress","text":"<p>The Ingress in this example adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at an example of specifying custom headers.</p> <pre><code>kubectl apply -f ingress.yaml\n</code></pre>"},{"location":"examples/customization/configuration-snippets/#test","title":"Test","text":"<p>Check if the contents of the annotation are present in the nginx.conf file using:</p> <pre><code>kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf\n</code></pre>"},{"location":"examples/customization/custom-configuration/","title":"Custom Configuration","text":"<p>Using a ConfigMap is possible to customize the NGINX configuration</p> <p>For example, if we want to change the timeouts we need to create a ConfigMap:</p> <pre><code>$ cat configmap.yaml\napiVersion: v1\ndata:\n  proxy-connect-timeout: \"10\"\n  proxy-read-timeout: \"120\"\n  proxy-send-timeout: \"120\"\nkind: ConfigMap\nmetadata:\n  name: ingress-nginx-controller\n</code></pre> <pre><code>curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-configuration/configmap.yaml \\\n    | kubectl apply -f -\n</code></pre> <p>If the Configmap is updated, NGINX will be reloaded with the new configuration.</p>"},{"location":"examples/customization/custom-errors/","title":"Custom Errors","text":"<p>This example demonstrates how to use a custom backend to render custom error pages.</p> <p>If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment.</p>"},{"location":"examples/customization/custom-errors/#customized-default-backend","title":"Customized default backend","text":"<p>First, create the custom <code>default-backend</code>. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository.</p> <pre><code>$ kubectl create -f custom-default-backend.yaml\nservice \"nginx-errors\" created\ndeployment.apps \"nginx-errors\" created\n</code></pre> <p>This should have created a Deployment and a Service with the name <code>nginx-errors</code>.</p> <pre><code>$ kubectl get deploy,svc\nNAME                           DESIRED   CURRENT   READY     AGE\ndeployment.apps/nginx-errors   1         1         1         10s\n\nNAME                   TYPE        CLUSTER-IP  EXTERNAL-IP   PORT(S)   AGE\nservice/nginx-errors   ClusterIP   10.0.0.12   &lt;none&gt;        80/TCP    10s\n</code></pre>"},{"location":"examples/customization/custom-errors/#ingress-controller-configuration","title":"Ingress controller configuration","text":"<p>If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps:</p> <ol> <li> <p>Edit the <code>ingress-nginx-controller</code> Deployment and set the value of the <code>--default-backend-service</code> flag to the name of the    newly created error backend.</p> </li> <li> <p>Edit the <code>ingress-nginx-controller</code> ConfigMap and create the key <code>custom-http-errors</code> with a value of <code>404,503</code>.</p> </li> <li> <p>Take note of the IP address assigned to the Ingress-Nginx Controller Service.     <pre><code>$ kubectl get svc ingress-nginx\nNAME            TYPE        CLUSTER-IP  EXTERNAL-IP   PORT(S)          AGE\ningress-nginx   ClusterIP   10.0.0.13   &lt;none&gt;        80/TCP,443/TCP   10m\n</code></pre></p> </li> </ol> <p>Note</p> <p>The <code>ingress-nginx</code> Service is of type <code>ClusterIP</code> in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example.</p>"},{"location":"examples/customization/custom-errors/#testing-error-pages","title":"Testing error pages","text":"<p>Let us send a couple of HTTP requests using cURL and validate everything is working as expected.</p> <p>A request to the default backend returns a 404 error with a custom message:</p> <pre><code>$ curl -D- http://10.0.0.13/\nHTTP/1.1 404 Not Found\nServer: nginx/1.13.12\nDate: Tue, 12 Jun 2018 19:11:24 GMT\nContent-Type: */*\nTransfer-Encoding: chunked\nConnection: keep-alive\n\n&lt;span&gt;The page you're looking for could not be found.&lt;/span&gt;\n</code></pre> <p>A request with a custom <code>Accept</code> header returns the corresponding document type (JSON):</p> <pre><code>$ curl -D- -H 'Accept: application/json' http://10.0.0.13/\nHTTP/1.1 404 Not Found\nServer: nginx/1.13.12\nDate: Tue, 12 Jun 2018 19:12:36 GMT\nContent-Type: application/json\nTransfer-Encoding: chunked\nConnection: keep-alive\nVary: Accept-Encoding\n\n{ \"message\": \"The page you're looking for could not be found\" }\n</code></pre> <p>To go further with this example, feel free to deploy your own applications and Ingress objects, and validate that the responses are still in the correct format when a backend returns 503 (eg. if you scale a Deployment down to 0 replica).</p>"},{"location":"examples/customization/custom-headers/","title":"Custom Headers","text":""},{"location":"examples/customization/custom-headers/#caveats","title":"Caveats","text":"<p>Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers.</p>"},{"location":"examples/customization/custom-headers/#workaround","title":"Workaround","text":"<p>To work around this limitation, perform a rolling restart of the deployment.</p>"},{"location":"examples/customization/custom-headers/#example","title":"Example","text":"<p>This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server.</p> <p>custom-headers.yaml defines a ConfigMap in the <code>ingress-nginx</code> namespace named <code>custom-headers</code>, holding several custom X-prefixed HTTP headers.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml\n</code></pre> <p>configmap.yaml defines a ConfigMap in the <code>ingress-nginx</code> namespace named <code>ingress-nginx-controller</code>. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key <code>proxy-set-headers</code> is set to cite the previously-created <code>ingress-nginx/custom-headers</code> ConfigMap.</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml\n</code></pre> <p>The Ingress-Nginx Controller will read the <code>ingress-nginx/ingress-nginx-controller</code> ConfigMap, find the <code>proxy-set-headers</code> key, read HTTP headers from the <code>ingress-nginx/custom-headers</code> ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends.</p> <p>The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml\n</code></pre>"},{"location":"examples/customization/custom-headers/#test","title":"Test","text":"<p>Check the contents of the ConfigMaps are present in the nginx.conf file using: <code>kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf</code></p>"},{"location":"examples/customization/external-auth-headers/","title":"External authentication, authentication service response headers propagation","text":"<p>This example demonstrates propagation of selected authentication service response headers to a backend service.</p> <p>Sample configuration includes:</p> <ul> <li>Sample authentication service producing several response headers</li> <li>Authentication logic is based on HTTP header: requests with header <code>User</code> containing string <code>internal</code> are considered authenticated</li> <li>After successful authentication service generates response headers <code>UserID</code> and <code>UserRole</code></li> <li>Sample echo service displaying header information</li> <li>Two ingress objects pointing to echo service</li> <li>Public, which allows access from unauthenticated users</li> <li>Private, which allows access from authenticated users only</li> </ul> <p>You can deploy the controller as follows:</p> <pre><code>$ kubectl create -f deploy/\ndeployment \"demo-auth-service\" created\nservice \"demo-auth-service\" created\ningress \"demo-auth-service\" created\ndeployment \"demo-echo-service\" created\nservice \"demo-echo-service\" created\ningress \"public-demo-echo-service\" created\ningress \"secure-demo-echo-service\" created\n\n$ kubectl get po\nNAME                                        READY     STATUS    RESTARTS   AGE\ndemo-auth-service-2769076528-7g9mh          1/1       Running            0          30s\ndemo-echo-service-3636052215-3vw8c          1/1       Running            0          29s\n\nkubectl get ing\nNAME                       HOSTS                                 ADDRESS   PORTS     AGE\npublic-demo-echo-service   public-demo-echo-service.kube.local             80        1m\nsecure-demo-echo-service   secure-demo-echo-service.kube.local             80        1m\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-1-public-service-with-no-auth-header","title":"Test 1: public service with no auth header","text":"<pre><code>$ curl -H 'Host: public-demo-echo-service.kube.local' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: public-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:19:21 GMT\n&lt; Content-Type: text/plain; charset=utf-8\n&lt; Content-Length: 20\n&lt; Connection: keep-alive\n&lt;\n* Connection #0 to host 192.168.99.100 left intact\nUserID: , UserRole:\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-2-secure-service-with-no-auth-header","title":"Test 2: secure service with no auth header","text":"<pre><code>$ curl -H 'Host: secure-demo-echo-service.kube.local' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: secure-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt;\n&lt; HTTP/1.1 403 Forbidden\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:18:48 GMT\n&lt; Content-Type: text/html\n&lt; Content-Length: 170\n&lt; Connection: keep-alive\n&lt;\n&lt;html&gt;\n&lt;head&gt;&lt;title&gt;403 Forbidden&lt;/title&gt;&lt;/head&gt;\n&lt;body bgcolor=\"white\"&gt;\n&lt;center&gt;&lt;h1&gt;403 Forbidden&lt;/h1&gt;&lt;/center&gt;\n&lt;hr&gt;&lt;center&gt;nginx/1.11.10&lt;/center&gt;\n&lt;/body&gt;\n&lt;/html&gt;\n* Connection #0 to host 192.168.99.100 left intact\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-3-public-service-with-valid-auth-header","title":"Test 3: public service with valid auth header","text":"<pre><code>$ curl -H 'Host: public-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: public-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt; User:internal\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:19:59 GMT\n&lt; Content-Type: text/plain; charset=utf-8\n&lt; Content-Length: 44\n&lt; Connection: keep-alive\n&lt;\n* Connection #0 to host 192.168.99.100 left intact\nUserID: 1443635317331776148, UserRole: admin\n</code></pre>"},{"location":"examples/customization/external-auth-headers/#test-4-secure-service-with-valid-auth-header","title":"Test 4: secure service with valid auth header","text":"<pre><code>$ curl -H 'Host: secure-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100\n* Rebuilt URL to: 192.168.99.100/\n*   Trying 192.168.99.100...\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n&gt; GET / HTTP/1.1\n&gt; Host: secure-demo-echo-service.kube.local\n&gt; User-Agent: curl/7.43.0\n&gt; Accept: */*\n&gt; User:internal\n&gt;\n&lt; HTTP/1.1 200 OK\n&lt; Server: nginx/1.11.10\n&lt; Date: Mon, 13 Mar 2017 20:17:23 GMT\n&lt; Content-Type: text/plain; charset=utf-8\n&lt; Content-Length: 43\n&lt; Connection: keep-alive\n&lt;\n* Connection #0 to host 192.168.99.100 left intact\nUserID: 605394647632969758, UserRole: admin\n</code></pre>"},{"location":"examples/customization/jwt/","title":"Accommodation for JWT","text":"<p>JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it.</p>"},{"location":"examples/customization/jwt/#symptoms","title":"Symptoms","text":"<p>If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough.</p> <p>To be 100% sure look at the logs of the <code>ingress-nginx-controller</code> pod, you should see something like this:</p> <pre><code>upstream sent too big header while reading response header from upstream...\n</code></pre>"},{"location":"examples/customization/jwt/#increase-buffer-size-for-headers","title":"Increase buffer size for headers","text":"<p>In nginx, we want to modify the property <code>proxy-buffer-size</code>. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered.</p>"},{"location":"examples/customization/jwt/#using-helm","title":"Using helm","text":"<p>If you're using helm you can simply use the <code>config</code> properties. <pre><code> # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/\n  config: \n    proxy-buffer-size: 16k\n</code></pre></p>"},{"location":"examples/customization/jwt/#manually-in-kubernetes-config-files","title":"Manually in kubernetes config files","text":"<p>If you use an already generated config from for a provider, you will have to change the <code>controller-configmap.yaml</code></p> <pre><code>---\n# Source: ingress-nginx/templates/controller-configmap.yaml\napiVersion: v1\nkind: ConfigMap\n# ...\ndata:\n  #...\n  proxy-buffer-size: \"16k\"\n</code></pre> <p>References:  * Custom Configuration</p>"},{"location":"examples/customization/ssl-dh-param/","title":"Custom DH parameters for perfect forward secrecy","text":"<p>This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with \"Perfect Forward Secrecy\".</p>"},{"location":"examples/customization/ssl-dh-param/#custom-configuration","title":"Custom configuration","text":"<pre><code>$ cat configmap.yaml\napiVersion: v1\ndata:\n  ssl-dh-param: \"ingress-nginx/lb-dhparam\"\nkind: ConfigMap\nmetadata:\n  name: ingress-nginx-controller\n  namespace: ingress-nginx\n  labels:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\n</code></pre> <pre><code>$ kubectl create -f configmap.yaml\n</code></pre>"},{"location":"examples/customization/ssl-dh-param/#custom-dh-parameters-secret","title":"Custom DH parameters secret","text":"<pre><code>$ openssl dhparam 4096 2&gt; /dev/null | base64\nLS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\n</code></pre> <pre><code>$ cat ssl-dh-param.yaml\napiVersion: v1\ndata:\n  dhparam.pem: \"LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\"\nkind: Secret\nmetadata:\n  name: lb-dhparam\n  namespace: ingress-nginx\n  labels:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\n</code></pre> <pre><code>$ kubectl create -f ssl-dh-param.yaml\n</code></pre>"},{"location":"examples/customization/ssl-dh-param/#test","title":"Test","text":"<p>Check the contents of the configmap is present in the nginx.conf file using: <pre><code>$ kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf\n</code></pre></p>"},{"location":"examples/customization/sysctl/","title":"Sysctl tuning","text":"<p>This example aims to demonstrate the use of an Init Container to adjust sysctl default values using <code>kubectl patch</code>.</p> <pre><code>kubectl patch deployment -n ingress-nginx ingress-nginx-controller \\\n    --patch=\"$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)\"\n</code></pre> <p>Changes:</p> <ul> <li>Backlog Queue setting <code>net.core.somaxconn</code> from <code>128</code> to <code>32768</code></li> <li>Ephemeral Ports setting <code>net.ipv4.ip_local_port_range</code> from <code>32768 60999</code> to <code>1024 65000</code></li> </ul> <p>In a post from the NGINX blog, it is possible to see an explanation for the changes.</p>"},{"location":"examples/docker-registry/","title":"Docker registry","text":"<p>This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet.</p>"},{"location":"examples/docker-registry/#deployment","title":"Deployment","text":"<p>First we deploy the docker registry in the cluster:</p> <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml\n</code></pre> <p>Important</p> <p>DO NOT RUN THIS IN PRODUCTION</p> <p>This deployment uses <code>emptyDir</code> in the <code>volumeMount</code> which means the contents of the registry will be deleted when the pod dies.</p> <p>The next required step is creation of the ingress rules. To do this we have two options: with and without TLS</p>"},{"location":"examples/docker-registry/#without-tls","title":"Without TLS","text":"<p>Download and edit the yaml deployment replacing <code>registry.&lt;your domain&gt;</code> with a valid DNS name pointing to the ingress controller:</p> <pre><code>wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/ingress-without-tls.yaml\n</code></pre> <p>Important</p> <p>Running a docker registry without TLS requires we configure our local docker daemon with the insecure registry flag.</p> <p>Please check deploy a plain http registry</p>"},{"location":"examples/docker-registry/#with-tls","title":"With TLS","text":"<p>Download and edit the yaml deployment replacing <code>registry.&lt;your domain&gt;</code> with a valid DNS name pointing to the ingress controller:</p> <pre><code>wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/ingress-with-tls.yaml\n</code></pre> <p>Deploy kube lego use Let's Encrypt certificates or edit the ingress rule to use a secret with an existing SSL certificate.</p>"},{"location":"examples/docker-registry/#testing","title":"Testing","text":"<p>To test the registry is working correctly we download a known image from docker hub, create a tag pointing to the new registry and upload the image:</p> <pre><code>docker pull ubuntu:16.04\ndocker tag ubuntu:16.04 `registry.&lt;your domain&gt;/ubuntu:16.04`\ndocker push `registry.&lt;your domain&gt;/ubuntu:16.04`\n</code></pre> <p>Please replace <code>registry.&lt;your domain&gt;</code> with your domain.</p>"},{"location":"examples/grpc/","title":"gRPC","text":"<p>This example demonstrates how to route traffic to a gRPC service through the Ingress-NGINX controller.</p>"},{"location":"examples/grpc/#prerequisites","title":"Prerequisites","text":"<ol> <li>You have a kubernetes cluster running.</li> <li>You have a domain name such as <code>example.com</code> that is configured to route traffic to the Ingress-NGINX controller.</li> <li>You have the ingress-nginx-controller installed as per docs.</li> <li>You have a backend application running a gRPC server listening for TCP traffic.  If you want, you can use https://github.com/grpc/grpc-go/blob/91e0aeb192456225adf27966d04ada4cf8599915/examples/features/reflection/server/main.go as an example.</li> <li>You're also responsible for provisioning an SSL certificate for the ingress. So you need to have a valid SSL certificate, deployed as a Kubernetes secret of type <code>tls</code>, in the same namespace as the gRPC application.</li> </ol>"},{"location":"examples/grpc/#step-1-create-a-kubernetes-deployment-for-grpc-app","title":"Step 1: Create a Kubernetes <code>Deployment</code> for gRPC app","text":"<ul> <li>Make sure your gRPC application pod is running and listening for connections. For example you can try a kubectl command like this below:   <pre><code>$ kubectl get po -A -o wide | grep go-grpc-greeter-server\n</code></pre></li> <li> <p>If you have a gRPC app deployed in your cluster, then skip further notes in this Step 1, and continue from Step 2 below.</p> </li> <li> <p>As an example gRPC application, we can use this app https://github.com/grpc/grpc-go/blob/91e0aeb192456225adf27966d04ada4cf8599915/examples/features/reflection/server/main.go.</p> </li> <li> <p>To create a container image for this app, you can use this Dockerfile. </p> </li> <li> <p>If you use the Dockerfile mentioned above, to create a image, then you can use the following example Kubernetes manifest to create a deployment resource that uses that image. If necessary edit this manifest to suit your needs.</p> </li> </ul> <pre><code>cat &lt;&lt;EOF | kubectl apply -f -\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  labels:\n    app: go-grpc-greeter-server\n  name: go-grpc-greeter-server\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: go-grpc-greeter-server\n  template:\n    metadata:\n      labels:\n        app: go-grpc-greeter-server\n    spec:\n      containers:\n      - image: &lt;reponame&gt;/go-grpc-greeter-server   # Edit this for your reponame\n        resources:\n          limits:\n            cpu: 100m\n            memory: 100Mi\n          requests:\n            cpu: 50m\n            memory: 50Mi\n        name: go-grpc-greeter-server\n        ports:\n        - containerPort: 50051\nEOF\n</code></pre>"},{"location":"examples/grpc/#step-2-create-the-kubernetes-service-for-the-grpc-app","title":"Step 2: Create the Kubernetes <code>Service</code> for the gRPC app","text":"<ul> <li>You can use the following example manifest to create a service of type ClusterIP. Edit the name/namespace/label/port to match your deployment/pod.   <pre><code>cat &lt;&lt;EOF | kubectl apply -f -\napiVersion: v1\nkind: Service\nmetadata:\n  labels:\n    app: go-grpc-greeter-server\n  name: go-grpc-greeter-server\nspec:\n  ports:\n  - port: 80\n    protocol: TCP\n    targetPort: 50051\n  selector:\n    app: go-grpc-greeter-server\n  type: ClusterIP\nEOF\n</code></pre></li> <li>You can save the above example manifest to a file with name <code>service.go-grpc-greeter-server.yaml</code> and edit it to match your deployment/pod, if required. You can create the service resource with a kubectl command like this:</li> </ul> <pre><code>$ kubectl create -f service.go-grpc-greeter-server.yaml\n</code></pre>"},{"location":"examples/grpc/#step-3-create-the-kubernetes-ingress-resource-for-the-grpc-app","title":"Step 3: Create the Kubernetes <code>Ingress</code> resource for the gRPC app","text":"<ul> <li>Use the following example manifest of a ingress resource to create a ingress for your grpc app. If required, edit it to match your app's details like name, namespace, service, secret etc. Make sure you have the required SSL-Certificate, existing in your Kubernetes cluster in the same namespace where the gRPC app is. The certificate must be available as a kubernetes secret resource, of type \"kubernetes.io/tls\" https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets. This is because we are terminating TLS on the ingress.</li> </ul> <pre><code>cat &lt;&lt;EOF | kubectl apply -f -\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/ssl-redirect: \"true\"\n    nginx.ingress.kubernetes.io/backend-protocol: \"GRPC\"\n  name: fortune-ingress\n  namespace: default\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: grpctest.dev.mydomain.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: go-grpc-greeter-server\n            port:\n              number: 80\n  tls:\n  # This secret must exist beforehand\n  # The cert must also contain the subj-name grpctest.dev.mydomain.com\n  # https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/PREREQUISITES.md#tls-certificates\n  - secretName: wildcard.dev.mydomain.com\n    hosts:\n      - grpctest.dev.mydomain.com\nEOF\n</code></pre> <ul> <li>If you save the above example manifest as a file named <code>ingress.go-grpc-greeter-server.yaml</code> and edit it to match your deployment and service, you can create the ingress like this:</li> </ul> <pre><code>$ kubectl create -f ingress.go-grpc-greeter-server.yaml\n</code></pre> <ul> <li> <p>The takeaway is that we are not doing any TLS configuration on the server (as we are terminating TLS at the ingress level, gRPC traffic will travel unencrypted inside the cluster and arrive \"insecure\").</p> </li> <li> <p>For your own application you may or may not want to do this.  If you prefer to forward encrypted traffic to your POD and terminate TLS at the gRPC server itself, add the ingress annotation <code>nginx.ingress.kubernetes.io/backend-protocol: \"GRPCS\"</code>.</p> </li> <li> <p>A few more things to note:</p> </li> <li> <p>We've tagged the ingress with the annotation <code>nginx.ingress.kubernetes.io/backend-protocol: \"GRPC\"</code>.  This is the magic ingredient that sets up the appropriate nginx configuration to route http/2 traffic to our service.</p> </li> <li> <p>We're terminating TLS at the ingress and have configured an SSL certificate <code>wildcard.dev.mydomain.com</code>.  The ingress matches traffic arriving as <code>https://grpctest.dev.mydomain.com:443</code> and routes unencrypted messages to the backend Kubernetes service.</p> </li> </ul>"},{"location":"examples/grpc/#step-4-test-the-connection","title":"Step 4: test the connection","text":"<ul> <li>Once we've applied our configuration to Kubernetes, it's time to test that we can actually talk to the backend.  To do this, we'll use the grpcurl utility:</li> </ul> <pre><code>$ grpcurl grpctest.dev.mydomain.com:443 helloworld.Greeter/SayHello\n{\n  \"message\": \"Hello \"\n}\n</code></pre>"},{"location":"examples/grpc/#debugging-hints","title":"Debugging Hints","text":"<ol> <li>Obviously, watch the logs on your app.</li> <li>Watch the logs for the ingress-nginx-controller (increasing verbosity as    needed).</li> <li>Double-check your address and ports.</li> <li>Set the <code>GODEBUG=http2debug=2</code> environment variable to get detailed http/2    logging on the client and/or server.</li> <li>Study RFC 7540 (http/2) https://tools.ietf.org/html/rfc7540.</li> </ol> <p>If you are developing public gRPC endpoints, check out https://proto.stack.build, a protocol buffer / gRPC build service that can use to help make it easier for your users to consume your API.</p> <p>See also the specific gRPC settings of NGINX: https://nginx.org/en/docs/http/ngx_http_grpc_module.html</p>"},{"location":"examples/grpc/#notes-on-using-responserequest-streams","title":"Notes on using response/request streams","text":"<p><code>grpc_read_timeout</code> and <code>grpc_send_timeout</code> will be set as <code>proxy_read_timeout</code> and <code>proxy_send_timeout</code> when you set backend protocol to <code>GRPC</code> or <code>GRPCS</code>.</p> <ol> <li>If your server only does response streaming and you expect a stream to be open longer than 60 seconds, you will have to change the <code>grpc_read_timeout</code> to accommodate this.</li> <li>If your service only does request streaming and you expect a stream to be open longer than 60 seconds, you have to change the <code>grpc_send_timeout</code> and the <code>client_body_timeout</code>.</li> <li>If you do both response and request streaming with an open stream longer than 60 seconds, you have to change all three timeouts: <code>grpc_read_timeout</code>, <code>grpc_send_timeout</code> and <code>client_body_timeout</code>.</li> </ol>"},{"location":"examples/multi-tls/","title":"Multi TLS certificate termination","text":"<p>This example uses 2 different certificates to terminate SSL for 2 hostnames.</p> <ol> <li>Create tls secrets for foo.bar.com and bar.baz.com as indicated in the yaml</li> <li>Create multi-tls.yaml</li> </ol> <p>This should generate a segment like: <pre><code>$ kubectl exec -it ingress-nginx-controller-6vwd1 -- cat /etc/nginx/nginx.conf | grep \"foo.bar.com\" -B 7 -A 35\n    server {\n        listen 80;\n        listen 443 ssl http2;\n        ssl_certificate /etc/nginx-ssl/default-foobar.pem;\n        ssl_certificate_key /etc/nginx-ssl/default-foobar.pem;\n\n\n        server_name foo.bar.com;\n\n\n        if ($scheme = http) {\n            return 301 https://$host$request_uri;\n        }\n\n\n\n        location / {\n            proxy_set_header Host                   $host;\n\n            # Pass Real IP\n            proxy_set_header X-Real-IP              $remote_addr;\n\n            # Allow websocket connections\n            proxy_set_header                        Upgrade           $http_upgrade;\n            proxy_set_header                        Connection        $connection_upgrade;\n\n            proxy_set_header X-Forwarded-For        $proxy_add_x_forwarded_for;\n            proxy_set_header X-Forwarded-Host       $host;\n            proxy_set_header X-Forwarded-Proto      $pass_access_scheme;\n\n            proxy_connect_timeout                   5s;\n            proxy_send_timeout                      60s;\n            proxy_read_timeout                      60s;\n\n            proxy_redirect                          off;\n            proxy_buffering                         off;\n\n            proxy_http_version                      1.1;\n\n            proxy_pass http://default-http-svc-80;\n        }\n</code></pre></p> <p>And you should be able to reach your nginx service or http-svc service using a hostname switch: <pre><code>$  kubectl get ing\nNAME      RULE          BACKEND   ADDRESS                         AGE\nfoo-tls   -                       104.154.30.67                   13m\n          foo.bar.com\n          /             http-svc:80\n          bar.baz.com\n          /             nginx:80\n\n$ curl https://104.154.30.67 -H 'Host:foo.bar.com' -k\nCLIENT VALUES:\nclient_address=10.245.0.6\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://foo.bar.com:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nconnection=close\nhost=foo.bar.com\nuser-agent=curl/7.35.0\nx-forwarded-for=10.245.0.1\nx-forwarded-host=foo.bar.com\nx-forwarded-proto=https\n\n$ curl https://104.154.30.67 -H 'Host:bar.baz.com' -k\n&lt;!DOCTYPE html&gt;\n&lt;html&gt;\n&lt;head&gt;\n&lt;title&gt;Welcome to nginx on Debian!&lt;/title&gt;\n\n$ curl 104.154.30.67\ndefault backend - 404\n</code></pre></p>"},{"location":"examples/openpolicyagent/","title":"OpenPolicyAgent and pathType enforcing","text":"<p>Ingress API allows users to specify different pathType  on Ingress object. </p> <p>While pathType <code>Exact</code> and <code>Prefix</code> should allow only a small set of characters, pathType <code>ImplementationSpecific</code> allows any characters, as it may contain regexes, variables and other features that may be specific of the Ingress  Controller being used.</p> <p>This means that the Ingress Admins (the persona who deployed the Ingress Controller) should trust the users  allowed to use <code>pathType: ImplementationSpecific</code>, as this may allow arbitrary configuration, and this  configuration may end on the proxy (aka Nginx) configuration.</p>"},{"location":"examples/openpolicyagent/#example","title":"Example","text":"<p>The example in this repo uses Gatekeeper to block the usage of <code>pathType: ImplementationSpecific</code>,  allowing just a specific list of namespaces to use it.</p> <p>It is recommended that the admin modifies this rules to enforce a specific set of characters when the usage of ImplementationSpecific is allowed, or in ways that best suits their needs.</p> <p>First, the <code>ConstraintTemplate</code> from template.yaml will define a rule that validates if the Ingress object  is being created on an excempted namespace, and case not, will validate its pathType.</p> <p>Then, the rule <code>K8sBlockIngressPathType</code> contained in rule.yaml will define the parameters: what kind of  object should be verified (Ingress), what are the excempted namespaces, and what kinds of pathType are blocked.</p>"},{"location":"examples/psp/","title":"Pod Security Policy (PSP)","text":"<p>In most clusters today, by default, all resources (e.g. <code>Deployments</code> and <code>ReplicatSets</code>) have permissions to create pods. Kubernetes however provides a more fine-grained authorization policy called Pod Security Policy (PSP).</p> <p>PSP allows the cluster owner to define the permission of each object, for example creating a pod. If you have PSP enabled on the cluster, and you deploy ingress-nginx, you will need to provide the <code>Deployment</code> with the permissions to create pods.</p> <p>Before applying any objects, first apply the PSP permissions by running: <pre><code>kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/psp/psp.yaml\n</code></pre></p> <p>Note: PSP permissions must be granted before the creation of the <code>Deployment</code> and the <code>ReplicaSet</code>.</p>"},{"location":"examples/rewrite/","title":"Rewrite","text":"<p>This example demonstrates how to use <code>Rewrite</code> annotations.</p>"},{"location":"examples/rewrite/#prerequisites","title":"Prerequisites","text":"<p>You will need to make sure your Ingress targets exactly one Ingress controller by specifying the ingress.class annotation, and that you have an ingress controller running in your cluster.</p>"},{"location":"examples/rewrite/#deployment","title":"Deployment","text":"<p>Rewriting can be controlled using the following annotations:</p> Name Description Values nginx.ingress.kubernetes.io/rewrite-target Target URI where the traffic must be redirected string nginx.ingress.kubernetes.io/ssl-redirect Indicates if the location section is only accessible via SSL (defaults to True when Ingress contains a Certificate) bool nginx.ingress.kubernetes.io/force-ssl-redirect Forces the redirection to HTTPS even if the Ingress is not TLS Enabled bool nginx.ingress.kubernetes.io/app-root Defines the Application Root that the Controller must redirect if it's in <code>/</code> context string nginx.ingress.kubernetes.io/use-regex Indicates if the paths defined on an Ingress use regular expressions bool"},{"location":"examples/rewrite/#examples","title":"Examples","text":""},{"location":"examples/rewrite/#rewrite-target","title":"Rewrite Target","text":"<p>Attention</p> <p>Starting in Version 0.22.0, ingress definitions using the annotation <code>nginx.ingress.kubernetes.io/rewrite-target</code> are not backwards compatible with previous versions. In Version 0.22.0 and beyond, any substrings within the request URI that need to be passed to the rewritten path must explicitly be defined in a capture group.</p> <p>Note</p> <p>Captured groups are saved in numbered placeholders, chronologically, in the form <code>$1</code>, <code>$2</code> ... <code>$n</code>. These placeholders can be used as parameters in the <code>rewrite-target</code> annotation.</p> <p>Note</p> <p>Please see the FAQ for Validation Of <code>path</code></p> <p>Create an Ingress rule with a rewrite annotation:</p> <pre><code>$ echo '\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/use-regex: \"true\"\n    nginx.ingress.kubernetes.io/rewrite-target: /$2\n  name: rewrite\n  namespace: default\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: rewrite.bar.com\n    http:\n      paths:\n      - path: /something(/|$)(.*)\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: http-svc\n            port: \n              number: 80\n' | kubectl create -f -\n</code></pre> <p>In this ingress definition, any characters captured by <code>(.*)</code> will be assigned to the placeholder <code>$2</code>, which is then used as a parameter in the <code>rewrite-target</code> annotation.</p> <p>For example, the ingress definition above will result in the following rewrites:</p> <ul> <li><code>rewrite.bar.com/something</code> rewrites to <code>rewrite.bar.com/</code></li> <li><code>rewrite.bar.com/something/</code> rewrites to <code>rewrite.bar.com/</code></li> <li><code>rewrite.bar.com/something/new</code> rewrites to <code>rewrite.bar.com/new</code></li> </ul>"},{"location":"examples/rewrite/#app-root","title":"App Root","text":"<p>Create an Ingress rule with an app-root annotation: <pre><code>$ echo \"\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/app-root: /app1\n  name: approot\n  namespace: default\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: approot.bar.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: http-svc\n            port: \n              number: 80\n\" | kubectl create -f -\n</code></pre></p> <p>Check the rewrite is working</p> <pre><code>$ curl -I -k http://approot.bar.com/\nHTTP/1.1 302 Moved Temporarily\nServer: nginx/1.11.10\nDate: Mon, 13 Mar 2017 14:57:15 GMT\nContent-Type: text/html\nContent-Length: 162\nLocation: http://approot.bar.com/app1\nConnection: keep-alive\n</code></pre>"},{"location":"examples/static-ip/","title":"Static IPs","text":"<p>This example demonstrates how to assign a static-ip to an Ingress on through the Ingress-NGINX controller.</p>"},{"location":"examples/static-ip/#prerequisites","title":"Prerequisites","text":"<p>You need a TLS cert and a test HTTP service for this example. You will also need to make sure your Ingress targets exactly one Ingress controller by specifying the ingress.class annotation, and that you have an ingress controller running in your cluster.</p>"},{"location":"examples/static-ip/#acquiring-an-ip","title":"Acquiring an IP","text":"<p>Since instances of the ingress nginx controller actually run on nodes in your cluster, by default nginx Ingresses will only get static IPs if your cloudprovider supports static IP assignments to nodes. On GKE/GCE for example, even though nodes get static IPs, the IPs are not retained across upgrades.</p> <p>To acquire a static IP for the ingress-nginx-controller, simply put it behind a Service of <code>Type=LoadBalancer</code>.</p> <p>First, create a loadbalancer Service and wait for it to acquire an IP:</p> <pre><code>$ kubectl create -f static-ip-svc.yaml\nservice \"ingress-nginx-lb\" created\n\n$ kubectl get svc ingress-nginx-lb\nNAME               CLUSTER-IP     EXTERNAL-IP       PORT(S)                      AGE\ningress-nginx-lb   10.0.138.113   104.154.109.191   80:31457/TCP,443:32240/TCP   15m\n</code></pre> <p>Then, update the ingress controller so it adopts the static IP of the Service by passing the <code>--publish-service</code> flag (the example yaml used in the next step already has it set to \"ingress-nginx-lb\").</p> <pre><code>$ kubectl create -f ingress-nginx-controller.yaml\ndeployment \"ingress-nginx-controller\" created\n</code></pre>"},{"location":"examples/static-ip/#assigning-the-ip-to-an-ingress","title":"Assigning the IP to an Ingress","text":"<p>From here on every Ingress created with the <code>ingress.class</code> annotation set to <code>nginx</code> will get the IP allocated in the previous step.</p> <pre><code>$ kubectl create -f ingress-nginx.yaml\ningress \"ingress-nginx\" created\n\n$ kubectl get ing ingress-nginx\nNAME            HOSTS     ADDRESS           PORTS     AGE\ningress-nginx   *         104.154.109.191   80, 443   13m\n\n$ curl 104.154.109.191 -kL\nCLIENT VALUES:\nclient_address=10.180.1.25\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://104.154.109.191:8080/\n...\n</code></pre>"},{"location":"examples/static-ip/#retaining-the-ip","title":"Retaining the IP","text":"<p>You can test retention by deleting the Ingress:</p> <pre><code>$ kubectl delete ing ingress-nginx\ningress \"ingress-nginx\" deleted\n\n$ kubectl create -f ingress-nginx.yaml\ningress \"ingress-nginx\" created\n\n$ kubectl get ing ingress-nginx\nNAME            HOSTS     ADDRESS           PORTS     AGE\ningress-nginx   *         104.154.109.191   80, 443   13m\n</code></pre> <p>Note that unlike the GCE Ingress, the same loadbalancer IP is shared amongst all Ingresses, because all requests are proxied through the same set of nginx controllers.</p>"},{"location":"examples/static-ip/#promote-ephemeral-to-static-ip","title":"Promote ephemeral to static IP","text":"<p>To promote the allocated IP to static, you can update the Service manifest:</p> <pre><code>$ kubectl patch svc ingress-nginx-lb -p '{\"spec\": {\"loadBalancerIP\": \"104.154.109.191\"}}'\n\"ingress-nginx-lb\" patched\n</code></pre> <p>... and promote the IP to static (promotion works differently for cloudproviders, provided example is for GKE/GCE):</p> <pre><code>$ gcloud compute addresses create ingress-nginx-lb --addresses 104.154.109.191 --region us-central1\nCreated [https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/ingress-nginx-lb].\n---\naddress: 104.154.109.191\ncreationTimestamp: '2017-01-31T16:34:50.089-08:00'\ndescription: ''\nid: '5208037144487826373'\nkind: compute#address\nname: ingress-nginx-lb\nregion: us-central1\nselfLink: https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/ingress-nginx-lb\nstatus: IN_USE\nusers:\n- us-central1/forwardingRules/a09f6913ae80e11e6a8c542010af0000\n</code></pre> <p>Now even if the Service is deleted, the IP will persist, so you can recreate the Service with <code>spec.loadBalancerIP</code> set to <code>104.154.109.191</code>.</p>"},{"location":"examples/tls-termination/","title":"TLS termination","text":"<p>This example demonstrates how to terminate TLS through the Ingress-Nginx Controller.</p>"},{"location":"examples/tls-termination/#prerequisites","title":"Prerequisites","text":"<p>You need a TLS cert and a test HTTP service for this example.</p>"},{"location":"examples/tls-termination/#deployment","title":"Deployment","text":"<p>Create a <code>ingress.yaml</code> file.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: nginx-test\nspec:\n  tls:\n    - hosts:\n      - foo.bar.com\n      # This assumes tls-secret exists and the SSL\n      # certificate contains a CN for foo.bar.com\n      secretName: tls-secret\n  ingressClassName: nginx\n  rules:\n    - host: foo.bar.com\n      http:\n        paths:\n        - path: /\n          pathType: Prefix\n          backend:\n            # This assumes http-svc exists and routes to healthy endpoints\n            service:\n              name: http-svc\n              port:\n                number: 80\n</code></pre> <p>The following command instructs the controller to terminate traffic using the provided TLS cert, and forward un-encrypted HTTP traffic to the test HTTP service.</p> <pre><code>kubectl apply -f ingress.yaml\n</code></pre>"},{"location":"examples/tls-termination/#validation","title":"Validation","text":"<p>You can confirm that the Ingress works.</p> <pre><code>$ kubectl describe ing nginx-test\nName:           nginx-test\nNamespace:      default\nAddress:        104.198.183.6\nDefault backend:    default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)\nTLS:\n  tls-secret terminates\nRules:\n  Host  Path    Backends\n  ----  ----    --------\n  *\n            http-svc:80 (&lt;none&gt;)\nAnnotations:\nEvents:\n  FirstSeen LastSeen    Count   From                SubObjectPath   Type        Reason  Message\n  --------- --------    -----   ----                -------------   --------    ------  -------\n  7s        7s      1   {ingress-nginx-controller }         Normal      CREATE  default/nginx-test\n  7s        7s      1   {ingress-nginx-controller }         Normal      UPDATE  default/nginx-test\n  7s        7s      1   {ingress-nginx-controller }         Normal      CREATE  ip: 104.198.183.6\n  7s        7s      1   {ingress-nginx-controller }         Warning     MAPPING Ingress rule 'default/nginx-test' contains no path definition. Assuming /\n\n$ curl 104.198.183.6 -L\ncurl: (60) SSL certificate problem: self signed certificate\nMore details here: http://curl.haxx.se/docs/sslcerts.html\n\n$ curl 104.198.183.6 -Lk\nCLIENT VALUES:\nclient_address=10.240.0.4\ncommand=GET\nreal path=/\nquery=nil\nrequest_version=1.1\nrequest_uri=http://35.186.221.137:8080/\n\nSERVER VALUES:\nserver_version=nginx: 1.9.11 - lua: 10001\n\nHEADERS RECEIVED:\naccept=*/*\nconnection=Keep-Alive\nhost=35.186.221.137\nuser-agent=curl/7.46.0\nvia=1.1 google\nx-cloud-trace-context=f708ea7e369d4514fc90d51d7e27e91d/13322322294276298106\nx-forwarded-for=104.132.0.80, 35.186.221.137\nx-forwarded-proto=https\nBODY:\n</code></pre>"},{"location":"user-guide/basic-usage/","title":"Basic usage - host based routing","text":"<p>ingress-nginx can be used for many use cases, inside various cloud providers and supports a lot of configurations. In this section you can find a common usage scenario where a single load balancer powered by ingress-nginx will route traffic to 2 different HTTP backend services based on the host name.</p> <p>First of all follow the instructions to install ingress-nginx. Then imagine that you need to expose 2 HTTP services already installed, <code>myServiceA</code>, <code>myServiceB</code>, and configured as <code>type: ClusterIP</code>. </p> <p>Let's say that you want to expose the first at <code>myServiceA.foo.org</code> and the second at <code>myServiceB.foo.org</code>.</p> <p>If the cluster version is &lt; 1.19, you can create two ingress resources like this:</p> <pre><code>apiVersion: networking.k8s.io/v1beta1\nkind: Ingress\nmetadata:\n  name: ingress-myservicea\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: myservicea.foo.org\n    http:\n      paths:\n      - path: /\n        backend:\n          serviceName: myservicea\n          servicePort: 80\n---\napiVersion: networking.k8s.io/v1beta1\nkind: Ingress\nmetadata:\n  name: ingress-myserviceb\n  annotations:\n    # use the shared ingress-nginx\n    kubernetes.io/ingress.class: \"nginx\"\nspec:\n  rules:\n  - host: myserviceb.foo.org\n    http:\n      paths:\n      - path: /\n        backend:\n          serviceName: myserviceb\n          servicePort: 80\n</code></pre> <p>If the cluster uses Kubernetes version &gt;= 1.19.x, then its suggested to create 2 ingress resources, using yaml examples shown below. These examples are in conformity with the <code>networking.kubernetes.io/v1</code> api.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-myservicea\nspec:\n  rules:\n  - host: myservicea.foo.org\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: myservicea\n            port:\n              number: 80\n  ingressClassName: nginx\n---\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-myserviceb\nspec:\n  rules:\n  - host: myserviceb.foo.org\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: myserviceb\n            port:\n              number: 80\n  ingressClassName: nginx\n</code></pre> <p>When you apply this yaml, 2 ingress resources will be created managed by the ingress-nginx instance. Nginx is configured to automatically discover all ingress with the <code>kubernetes.io/ingress.class: \"nginx\"</code> annotation or where <code>ingressClassName: nginx</code> is present. Please note that the ingress resource should be placed inside the same namespace of the backend resource.</p> <p>On many cloud providers ingress-nginx will also create the corresponding Load Balancer resource. All you have to do is get the external IP and add a DNS <code>A record</code> inside your DNS provider that point myservicea.foo.org and myserviceb.foo.org to the nginx external IP. Get the external IP by running:</p> <pre><code>kubectl get services -n ingress-nginx\n</code></pre> <p>To test inside minikube refer to this documentation: Set up Ingress on Minikube with the NGINX Ingress Controller</p>"},{"location":"user-guide/cli-arguments/","title":"Command line arguments","text":"<p>The following command line arguments are accepted by the Ingress controller executable.</p> <p>They are set in the container spec of the <code>ingress-nginx-controller</code> Deployment manifest</p> Argument Description <code>--annotations-prefix</code> Prefix of the Ingress annotations specific to the NGINX controller. (default \"nginx.ingress.kubernetes.io\") <code>--apiserver-host</code> Address of the Kubernetes API server. Takes the form \"protocol://address:port\". If not specified, it is assumed the program runs inside a Kubernetes cluster and local discovery is attempted. <code>--certificate-authority</code> Path to a cert file for the certificate authority. This certificate is used only when the flag --apiserver-host is specified. <code>--configmap</code> Name of the ConfigMap containing custom global configurations for the controller. <code>--controller-class</code> Ingress Class Controller value this Ingress satisfies. The class of an Ingress object is set using the field IngressClassName in Kubernetes clusters version v1.19.0 or higher. The .spec.controller value of the IngressClass referenced in an Ingress Object should be the same value specified here to make this object be watched. <code>--deep-inspect</code> Enables ingress object security deep inspector. (default true) <code>--default-backend-service</code> Service used to serve HTTP requests not matching any known server name (catch-all). Takes the form \"namespace/name\". The controller configures NGINX to forward requests to the first port of this Service. <code>--default-server-port</code> Port to use for exposing the default server (catch-all). (default 8181) <code>--default-ssl-certificate</code> Secret containing a SSL certificate to be used by the default HTTPS server (catch-all). Takes the form \"namespace/name\". <code>--enable-annotation-validation</code> If true, will enable the annotation validation feature. This value will be defaulted to true on a future release. <code>--disable-catch-all</code> Disable support for catch-all Ingresses. (default false) <code>--disable-full-test</code> Disable full test of all merged ingresses at the admission stage and tests the template of the ingress being created or updated  (full test of all ingresses is enabled by default). <code>--disable-svc-external-name</code> Disable support for Services of type ExternalName. (default false) <code>--disable-sync-events</code> Disables the creation of 'Sync' Event resources, but still logs them <code>--dynamic-configuration-retries</code> Number of times to retry failed dynamic configuration before failing to sync an ingress. (default 15) <code>--election-id</code> Election id to use for Ingress status updates. (default \"ingress-controller-leader\") <code>--election-ttl</code> Duration a leader election is valid before it's getting re-elected, e.g. <code>15s</code>, <code>10m</code> or <code>1h</code>. (Default: 30s) <code>--enable-metrics</code> Enables the collection of NGINX metrics. (default true) <code>--enable-ssl-chain-completion</code> Autocomplete SSL certificate chains with missing intermediate CA certificates. Certificates uploaded to Kubernetes must have the \"Authority Information Access\" X.509 v3 extension for this to succeed. (default false) <code>--enable-ssl-passthrough</code> Enable SSL Passthrough. (default false) <code>--disable-leader-election</code> Disable Leader Election on Nginx Controller. (default false) <code>--enable-topology-aware-routing</code> Enable topology aware routing feature, needs service object annotation service.kubernetes.io/topology-mode sets to auto. (default false) <code>--exclude-socket-metrics</code> Set of socket request metrics to exclude which won't be exported nor being calculated. The possible socket request metrics to exclude are documented in the monitoring guide e.g. 'nginx_ingress_controller_request_duration_seconds,nginx_ingress_controller_response_size' <code>--health-check-path</code> URL path of the health check endpoint. Configured inside the NGINX status server. All requests received on the port defined by the healthz-port parameter are forwarded internally to this path. (default \"/healthz\") <code>--health-check-timeout</code> Time limit, in seconds, for a probe to health-check-path to succeed. (default 10) <code>--healthz-port</code> Port to use for the healthz endpoint. (default 10254) <code>--healthz-host</code> Address to bind the healthz endpoint. <code>--http-port</code> Port to use for servicing HTTP traffic. (default 80) <code>--https-port</code> Port to use for servicing HTTPS traffic. (default 443) <code>--ingress-class</code> Name of the ingress class this controller satisfies. The class of an Ingress object is set using the field IngressClassName in Kubernetes clusters version v1.18.0 or higher or the annotation \"kubernetes.io/ingress.class\" (deprecated). If this parameter is not set, or set to the default value of \"nginx\", it will handle ingresses with either an empty or \"nginx\" class name. <code>--ingress-class-by-name</code> Define if Ingress Controller should watch for Ingress Class by Name together with Controller Class. (default false). <code>--internal-logger-address</code> Address to be used when binding internal syslogger. (default 127.0.0.1:11514) <code>--kubeconfig</code> Path to a kubeconfig file containing authorization and API server information. <code>--length-buckets</code> Set of buckets which will be used for prometheus histogram metrics such as RequestLength, ResponseLength. (default <code>[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]</code>) <code>--maxmind-edition-ids</code> Maxmind edition ids to download GeoLite2 Databases. (default \"GeoLite2-City,GeoLite2-ASN\") <code>--maxmind-retries-timeout</code> Maxmind downloading delay between 1<sup>st</sup> and 2<sup>nd</sup> attempt, 0s - do not retry to download if something went wrong. (default 0s) <code>--maxmind-retries-count</code> Number of attempts to download the GeoIP DB. (default 1) <code>--maxmind-license-key</code> Maxmind license key to download GeoLite2 Databases. https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases . <code>--maxmind-mirror</code> Maxmind mirror url (example: http://geoip.local/databases. <code>--metrics-per-host</code> Export metrics per-host. (default true) <code>--monitor-max-batch-size</code> Max batch size of NGINX metrics. (default 10000) <code>--post-shutdown-grace-period</code> Additional delay in seconds before controller container exits. (default 10) <code>--profiler-port</code> Port to use for expose the ingress controller Go profiler when it is enabled. (default 10245) <code>--profiling</code> Enable profiling via web interface host:port/debug/pprof/ . (default true) <code>--publish-service</code> Service fronting the Ingress controller. Takes the form \"namespace/name\". When used together with update-status, the controller mirrors the address of this service's endpoints to the load-balancer status of all Ingress objects it satisfies. <code>--publish-status-address</code> Customized address (or addresses, separated by comma) to set as the load-balancer status of Ingress objects this controller satisfies. Requires the update-status parameter. <code>--report-node-internal-ip-address</code> Set the load-balancer status of Ingress objects to internal Node addresses instead of external. Requires the update-status parameter. (default false) <code>--report-status-classes</code> If true, report status classes in metrics (2xx, 3xx, 4xx and 5xx) instead of full status codes. (default false) <code>--ssl-passthrough-proxy-port</code> Port to use internally for SSL Passthrough. (default 442) <code>--status-port</code> Port to use for the lua HTTP endpoint configuration. (default 10246) <code>--status-update-interval</code> Time interval in seconds in which the status should check if an update is required. Default is 60 seconds. (default 60) <code>--stream-port</code> Port to use for the lua TCP/UDP endpoint configuration. (default 10247) <code>--sync-period</code> Period at which the controller forces the repopulation of its local object stores. Disabled by default. <code>--sync-rate-limit</code> Define the sync frequency upper limit. (default 0.3) <code>--tcp-services-configmap</code> Name of the ConfigMap containing the definition of the TCP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form \"namespace/name:port\", where \"port\" can either be a port number or name. TCP ports 80 and 443 are reserved by the controller for servicing HTTP traffic. <code>--time-buckets</code> Set of buckets which will be used for prometheus histogram metrics such as RequestTime, ResponseTime. (default <code>[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]</code>) <code>--udp-services-configmap</code> Name of the ConfigMap containing the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form \"namespace/name:port\", where \"port\" can either be a port name or number. <code>--update-status</code> Update the load-balancer status of Ingress objects this controller satisfies. Requires setting the publish-service parameter to a valid Service reference. (default true) <code>--update-status-on-shutdown</code> Update the load-balancer status of Ingress objects when the controller shuts down. Requires the update-status parameter. (default true) <code>--shutdown-grace-period</code> Seconds to wait after receiving the shutdown signal, before stopping the nginx process. (default 0) <code>--size-buckets</code> Set of buckets which will be used for prometheus histogram metrics such as BytesSent. (default <code>[10, 100, 1000, 10000, 100000, 1e+06, 1e+07]</code>) <code>-v, --v Level</code> number for the log level verbosity <code>--validating-webhook</code> The address to start an admission controller on to validate incoming ingresses. Takes the form \":port\". If not provided, no admission controller is started. <code>--validating-webhook-certificate</code> The path of the validating webhook certificate PEM. <code>--validating-webhook-key</code> The path of the validating webhook key PEM. <code>--version</code> Show release information about the Ingress-Nginx Controller and exit. <code>--watch-ingress-without-class</code> Define if Ingress Controller should also watch for Ingresses without an IngressClass or the annotation specified. (default false) <code>--watch-namespace</code> Namespace the controller watches for updates to Kubernetes objects. This includes Ingresses, Services and all configuration resources. All namespaces are watched if this parameter is left empty. <code>--watch-namespace-selector</code> The controller will watch namespaces whose labels match the given selector. This flag only takes effective when <code>--watch-namespace</code> is empty."},{"location":"user-guide/custom-errors/","title":"Custom errors","text":"<p>When the <code>custom-http-errors</code> option is enabled, the Ingress controller configures NGINX so that it passes several HTTP headers down to its <code>default-backend</code> in case of error:</p> Header Value <code>X-Code</code> HTTP status code returned by the request <code>X-Format</code> Value of the <code>Accept</code> header sent by the client <code>X-Original-URI</code> URI that caused the error <code>X-Namespace</code> Namespace where the backend Service is located <code>X-Ingress-Name</code> Name of the Ingress where the backend is defined <code>X-Service-Name</code> Name of the Service backing the backend <code>X-Service-Port</code> Port number of the Service backing the backend <code>X-Request-ID</code> Unique ID that identifies the request - same as for backend service <p>A custom error backend can use this information to return the best possible representation of an error page. For example, if the value of the <code>Accept</code> header send by the client was <code>application/json</code>, a carefully crafted backend could decide to return the error payload as a JSON document instead of HTML.</p> <p>Important</p> <p>The custom backend is expected to return the correct HTTP status code instead of <code>200</code>. NGINX does not change the response from the custom default backend.</p> <p>An example of such custom backend is available inside the source repository at images/custom-error-pages.</p> <p>See also the Custom errors example.</p>"},{"location":"user-guide/default-backend/","title":"Default backend","text":"<p>The default backend is a service which handles all URL paths and hosts the Ingress-NGINX controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).</p> <p>Basically a default backend exposes two URLs:</p> <ul> <li><code>/healthz</code> that returns 200</li> <li><code>/</code> that returns 404</li> </ul> <p>Example</p> <p>The sub-directory <code>/images/custom-error-pages</code> provides an additional service for the purpose of customizing the error pages served via the default backend.</p>"},{"location":"user-guide/exposing-tcp-udp-services/","title":"Exposing TCP and UDP services","text":"<p>While the Kubernetes Ingress resource only officially supports routing external HTTP(s) traffic to services, ingress-nginx can be configured to receive external TCP/UDP traffic from non-HTTP protocols and route them to internal services using TCP/UDP port mappings that are specified within a ConfigMap.</p> <p>To support this, the <code>--tcp-services-configmap</code> and <code>--udp-services-configmap</code> flags can be used to point to an existing config map where the key is the external port to use and the value indicates the service to expose using the format: <code>&lt;service port&gt;:&lt;namespace/service name&gt;:[PROXY]:[PROXY]</code></p> <p>It is also possible to use a number or the name of the port. The two last fields are optional. Adding <code>PROXY</code> in either or both of the two last fields we can use Proxy Protocol decoding (listen) and/or encoding (proxy_pass) in a TCP service.  The first <code>PROXY</code> controls the decode of the proxy protocol and the second <code>PROXY</code> controls the encoding using proxy protocol.  This allows an incoming connection to be decoded or an outgoing connection to be encoded. It is also possible to arbitrate between two different proxies by turning on the decode and encode on a TCP service. </p> <p>The next example shows how to expose the service <code>example-go</code> running in the namespace <code>default</code> in the port <code>8080</code> using the port <code>9000</code></p> <pre><code>apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: tcp-services\n  namespace: ingress-nginx\ndata:\n  9000: \"default/example-go:8080\"\n</code></pre> <p>Since 1.9.13 NGINX provides UDP Load Balancing. The next example shows how to expose the service <code>kube-dns</code> running in the namespace <code>kube-system</code> in the port <code>53</code> using the port <code>53</code></p> <pre><code>apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: udp-services\n  namespace: ingress-nginx\ndata:\n  53: \"kube-system/kube-dns:53\"\n</code></pre> <p>If TCP/UDP proxy support is used, then those ports need to be exposed in the Service defined for the Ingress.</p> <p><pre><code>apiVersion: v1\nkind: Service\nmetadata:\n  name: ingress-nginx\n  namespace: ingress-nginx\n  labels:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\nspec:\n  type: LoadBalancer\n  ports:\n    - name: http\n      port: 80\n      targetPort: 80\n      protocol: TCP\n    - name: https\n      port: 443\n      targetPort: 443\n      protocol: TCP\n    - name: proxied-tcp-9000\n      port: 9000\n      targetPort: 9000\n      protocol: TCP\n  selector:\n    app.kubernetes.io/name: ingress-nginx\n    app.kubernetes.io/part-of: ingress-nginx\n</code></pre> Then, the configmap should be added into ingress controller's deployment args. <pre><code> args:\n    - /nginx-ingress-controller\n    - --tcp-services-configmap=ingress-nginx/tcp-services\n</code></pre></p>"},{"location":"user-guide/external-articles/","title":"External Articles","text":"<ul> <li>Pain(less) NGINX Ingress</li> <li>Accessing Kubernetes Pods from Outside of the Cluster</li> <li>Kubernetes - Redirect HTTP to HTTPS with ELB and the Ingress-Nginx Controller</li> <li>Configure Nginx Ingress Controller for TLS termination on Kubernetes on Azure</li> <li>Secure your Nginx Ingress controller behind Google Cloud Armor or Identity-Aware Proxy (IAP)</li> </ul>"},{"location":"user-guide/fcgi-services/","title":"Exposing FastCGI Servers","text":"<p>FastCGI is a binary protocol for interfacing interactive programs with a web server. [...] (It's) aim is to reduce the overhead related to interfacing between web server and CGI programs, allowing a server to handle more web page requests per unit of time.</p> <p>\u2014 Wikipedia</p> <p>The ingress-nginx ingress controller can be used to directly expose FastCGI servers.  Enabling FastCGI in your Ingress only requires setting the backend-protocol annotation to <code>FCGI</code>, and with a couple more annotations you can customize the way ingress-nginx handles the communication with your FastCGI server.</p>"},{"location":"user-guide/fcgi-services/#example-objects-to-expose-a-fastcgi-pod","title":"Example Objects to Expose a FastCGI Pod","text":"<p>The Pod example object below exposes port <code>9000</code>, which is the conventional FastCGI port.</p> <pre><code>apiVersion: v1\nkind: Pod\nmetadata:\n  name: example-app\nlabels:\n  app: example-app\nspec:\n  containers:\n  - name: example-app\n    image: example-app:1.0\n    ports:\n    - containerPort: 9000\n      name: fastcgi\n</code></pre> <p>The Service object example below matches port <code>9000</code> from the Pod object above.</p> <pre><code>apiVersion: v1\nkind: Service\nmetadata:\n  name: example-service\nspec:\n  selector:\n    app: example-app\n  ports:\n  - port: 9000\n    targetPort: 9000\n    name: fastcgi\n</code></pre> <p>And the Ingress and ConfigMap objects below demonstrates the supported FastCGI specific annotations (NGINX actually has 50 FastCGI directives, all of which have not been exposed in the ingress yet), and matches the service <code>example-service</code>, and the port named <code>fastcgi</code> from above. The ConfigMap must be created first for the Ingress Controller to be able to find it when the Ingress object is created, otherwise you will need to restart the Ingress Controller pods.</p> <pre><code># The ConfigMap MUST be created first for the ingress controller to be able to\n# find it when the Ingress object is created.\n\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: example-cm\ndata:\n  SCRIPT_FILENAME: \"/example/index.php\"\n\n---\n\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/backend-protocol: \"FCGI\"\n    nginx.ingress.kubernetes.io/fastcgi-index: \"index.php\"\n    nginx.ingress.kubernetes.io/fastcgi-params-configmap: \"example-cm\"\n  name: example-app\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: app.example.com\n    http:\n      paths:\n      - path: /\n        pathType: Prefix\n        backend:\n          service:\n            name: example-service\n            port:\n              name: fastcgi\n</code></pre>"},{"location":"user-guide/fcgi-services/#fastcgi-ingress-annotations","title":"FastCGI Ingress Annotations","text":"<p>To enable FastCGI, the <code>nginx.ingress.kubernetes.io/backend-protocol</code> annotation needs to be set to <code>FCGI</code>, which overrides the default <code>HTTP</code> value.</p> <p><code>nginx.ingress.kubernetes.io/backend-protocol: \"FCGI\"</code></p> <p>This enables the FastCGI mode for all paths defined in the Ingress object</p>"},{"location":"user-guide/fcgi-services/#the-nginxingresskubernetesiofastcgi-index-annotation","title":"The <code>nginx.ingress.kubernetes.io/fastcgi-index</code> Annotation","text":"<p>To specify an index file, the <code>fastcgi-index</code> annotation value can optionally be set.  In the example below, the value is set to <code>index.php</code>.  This annotation corresponds to the NGINX <code>fastcgi_index</code> directive.</p> <p><code>nginx.ingress.kubernetes.io/fastcgi-index: \"index.php\"</code></p>"},{"location":"user-guide/fcgi-services/#the-nginxingresskubernetesiofastcgi-params-configmap-annotation","title":"The <code>nginx.ingress.kubernetes.io/fastcgi-params-configmap</code> Annotation","text":"<p>To specify NGINX <code>fastcgi_param</code> directives, the <code>fastcgi-params-configmap</code> annotation is used, which in turn must lead to a ConfigMap object containing the NGINX <code>fastcgi_param</code> directives as key/values.</p> <p><code>nginx.ingress.kubernetes.io/fastcgi-params-configmap: \"example-configmap\"</code></p> <p>And the ConfigMap object to specify the <code>SCRIPT_FILENAME</code> and <code>HTTP_PROXY</code> NGINX's <code>fastcgi_param</code> directives will look like the following:</p> <p><pre><code>apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: example-configmap\ndata:\n  SCRIPT_FILENAME: \"/example/index.php\"\n  HTTP_PROXY: \"\"\n</code></pre> Using the namespace/ prefix is also supported, for example:</p> <p><code>nginx.ingress.kubernetes.io/fastcgi-params-configmap: \"example-namespace/example-configmap\"</code></p>"},{"location":"user-guide/ingress-path-matching/","title":"Ingress Path Matching","text":""},{"location":"user-guide/ingress-path-matching/#regular-expression-support","title":"Regular Expression Support","text":"<p>Important</p> <p>Regular expressions is not supported in the <code>spec.rules.host</code> field. The wildcard character '*' must appear by itself as the first DNS label and matches only a single label. You cannot have a wildcard label by itself (e.g. Host == \"*\").</p> <p>Note</p> <p>Please see the FAQ for Validation Of <code>path</code></p> <p>The ingress controller supports case insensitive regular expressions in the <code>spec.rules.http.paths.path</code> field. This can be enabled by setting the <code>nginx.ingress.kubernetes.io/use-regex</code> annotation to <code>true</code> (the default is false).</p> <p>Hint</p> <p>Kubernetes only accept expressions that comply with the RE2 engine syntax. It is possible that valid expressions accepted by NGINX cannot be used with ingress-nginx, because the PCRE library (used in NGINX) supports a wider syntax than RE2. See the RE2 Syntax documentation for differences.</p> <p>See the description of the <code>use-regex</code> annotation for more details.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress\n  annotations:\n    nginx.ingress.kubernetes.io/use-regex: \"true\"\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/.*\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: test\n            port:\n              number: 80\n</code></pre> <p>The preceding ingress definition would translate to the following location block within the NGINX configuration for the <code>test.com</code> server:</p> <pre><code>location ~* \"^/foo/.*\" {\n  ...\n}\n</code></pre>"},{"location":"user-guide/ingress-path-matching/#path-priority","title":"Path Priority","text":"<p>In NGINX, regular expressions follow a first match policy. In order to enable more accurate path matching, ingress-nginx first orders the paths by descending length before writing them to the NGINX template as location blocks.</p> <p>Please read the warning before using regular expressions in your ingress definitions.</p>"},{"location":"user-guide/ingress-path-matching/#example","title":"Example","text":"<p>Let the following two ingress definitions be created:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress-1\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/bar\n        pathType: Prefix\n        backend:\n          service:\n            name: service1\n            port:\n              number: 80\n      - path: /foo/bar/\n        pathType: Prefix\n        backend:\n          service:\n            name: service2\n            port:\n              number: 80\n</code></pre> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress-2\n  annotations:\n    nginx.ingress.kubernetes.io/rewrite-target: /$1\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/bar/(.+)\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: service3\n            port: \n              number: 80\n</code></pre> <p>The ingress controller would define the following location blocks, in order of descending length, within the NGINX template for the <code>test.com</code> server:</p> <pre><code>location ~* ^/foo/bar/.+ {\n  ...\n}\n\nlocation ~* \"^/foo/bar/\" {\n  ...\n}\n\nlocation ~* \"^/foo/bar\" {\n  ...\n}\n</code></pre> <p>The following request URI's would match the corresponding location blocks:</p> <ul> <li><code>test.com/foo/bar/1</code> matches <code>~* ^/foo/bar/.+</code> and will go to service 3.</li> <li><code>test.com/foo/bar/</code> matches <code>~* ^/foo/bar/</code> and will go to service 2.</li> <li><code>test.com/foo/bar</code> matches <code>~* ^/foo/bar</code> and will go to service 1.</li> </ul> <p>IMPORTANT NOTES:</p> <ul> <li>If the <code>use-regex</code> OR <code>rewrite-target</code> annotation is used on any Ingress for a given host, then the case insensitive regular expression location modifier will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</li> </ul>"},{"location":"user-guide/ingress-path-matching/#warning","title":"Warning","text":"<p>The following example describes a case that may inflict unwanted path matching behavior.</p> <p>This case is expected and a result of NGINX's a first match policy for paths that use the regular expression location modifier. For more information about how a path is chosen, please read the following article: \"Understanding Nginx Server and Location Block Selection Algorithms\".</p>"},{"location":"user-guide/ingress-path-matching/#example_1","title":"Example","text":"<p>Let the following ingress be defined:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: test-ingress-3\n  annotations:\n    nginx.ingress.kubernetes.io/use-regex: \"true\"\nspec:\n  ingressClassName: nginx\n  rules:\n  - host: test.com\n    http:\n      paths:\n      - path: /foo/bar/bar\n        pathType: Prefix\n        backend:\n          service:\n            name: test\n            port: \n              number: 80\n      - path: /foo/bar/[A-Z0-9]{3}\n        pathType: ImplementationSpecific\n        backend:\n          service:\n            name: test\n            port: \n              number: 80\n</code></pre> <p>The ingress controller would define the following location blocks (in this order) within the NGINX template for the <code>test.com</code> server:</p> <pre><code>location ~* \"^/foo/bar/[A-Z0-9]{3}\" {\n  ...\n}\n\nlocation ~* \"^/foo/bar/bar\" {\n  ...\n}\n</code></pre> <p>A request to <code>test.com/foo/bar/bar</code> would match the <code>^/foo/bar/[A-Z0-9]{3}</code> location block instead of the longest EXACT matching path.</p>"},{"location":"user-guide/k8s-122-migration/","title":"FAQ - Migration to Kubernetes 1.22 and apiVersion <code>networking.k8s.io/v1</code>","text":"<p>If you are using Ingress objects in your cluster (running Kubernetes older than v1.22), and you plan to upgrade to Kubernetes v1.22, this page is relevant to you.</p> <ul> <li>Please read this official blog on deprecated Ingress API versions</li> <li>Please read this official documentation on the IngressClass object</li> </ul>"},{"location":"user-guide/k8s-122-migration/#what-is-an-ingressclass-and-why-is-it-important-for-users-of-ingress-nginx-controller-now","title":"What is an IngressClass and why is it important for users of ingress-nginx controller now?","text":"<p>IngressClass is a Kubernetes resource. See the description below. It's important because until now, a default install of the ingress-nginx controller did not require a IngressClass object. From version 1.0.0 of the ingress-nginx controller, an IngressClass object is required.</p> <p>On clusters with more than one instance of the ingress-nginx controller, all instances of the controllers must be aware of which Ingress objects they serve. The <code>ingressClassName</code> field of an Ingress is the way to let the controller know about that.</p> <pre><code>kubectl explain ingressclass\n</code></pre> <pre><code>KIND:     IngressClass\nVERSION:  networking.k8s.io/v1\nDESCRIPTION:\n     IngressClass represents the class of the Ingress, referenced by the Ingress\n     Spec. The `ingressclass.kubernetes.io/is-default-class` annotation can be\n     used to indicate that an IngressClass should be considered default. When a\n     single IngressClass resource has this annotation set to true, new Ingress\n     resources without a class specified will be assigned this default class.\nFIELDS:\n   apiVersion   &lt;string&gt;\n     APIVersion defines the versioned schema of this representation of an\n     object. Servers should convert recognized schemas to the latest internal\n     value, and may reject unrecognized values. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources\n   kind &lt;string&gt;\n     Kind is a string value representing the REST resource this object\n     represents. Servers may infer this from the endpoint the client submits\n     requests to. Cannot be updated. In CamelCase. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds\n   metadata     &lt;Object&gt;\n     Standard object's metadata. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata\n   spec &lt;Object&gt;\n     Spec is the desired state of the IngressClass. More info:\n     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status`\n</code></pre>"},{"location":"user-guide/k8s-122-migration/#what-has-caused-this-change-in-behavior","title":"What has caused this change in behavior?","text":"<p>There are 2 primary reasons.</p>"},{"location":"user-guide/k8s-122-migration/#reason-1","title":"Reason 1","text":"<p>Until K8s version 1.21, it was possible to create an Ingress resource using deprecated versions of the Ingress API, such as:</p> <ul> <li><code>extensions/v1beta1</code></li> <li><code>networking.k8s.io/v1beta1</code>   You would get a message about deprecation, but the Ingress resource would get created.</li> </ul> <p>From K8s version 1.22 onwards, you can only access the Ingress API via the stable, <code>networking.k8s.io/v1</code> API. The reason is explained in the official blog on deprecated ingress API versions.</p>"},{"location":"user-guide/k8s-122-migration/#reason-2","title":"Reason #2","text":"<p>If you are already using the ingress-nginx controller and then upgrade to Kubernetes 1.22, there are several scenarios where your existing Ingress objects will not work how you expect.</p> <p>Read this FAQ to check which scenario matches your use case.</p>"},{"location":"user-guide/k8s-122-migration/#what-is-the-ingressclassname-field","title":"What is the <code>ingressClassName</code> field?","text":"<p><code>ingressClassName</code> is a field in the spec of an Ingress object.</p> <pre><code>kubectl explain ingress.spec.ingressClassName\n</code></pre> <pre><code>KIND:     Ingress\nVERSION:  networking.k8s.io/v1\nFIELD:    ingressClassName &lt;string&gt;\nDESCRIPTION:\n     IngressClassName is the name of the IngressClass cluster resource. The\n     associated IngressClass defines which controller will implement the\n     resource. This replaces the deprecated `kubernetes.io/ingress.class`\n     annotation. For backwards compatibility, when that annotation is set, it\n     must be given precedence over this field. The controller may emit a warning\n     if the field and annotation have different values. Implementations of this\n     API should ignore Ingresses without a class specified. An IngressClass\n     resource may be marked as default, which can be used to set a default value\n     for this field. For more information, refer to the IngressClass\n     documentation.\n</code></pre> <p>The <code>.spec.ingressClassName</code> behavior has precedence over the deprecated <code>kubernetes.io/ingress.class</code> annotation.</p>"},{"location":"user-guide/k8s-122-migration/#i-have-only-one-ingress-controller-in-my-cluster-what-should-i-do","title":"I have only one ingress controller in my cluster. What should I do?","text":"<p>If a single instance of the ingress-nginx controller is the sole Ingress controller running in your cluster, you should add the annotation \"ingressclass.kubernetes.io/is-default-class\" in your IngressClass, so any new Ingress objects will have this one as default IngressClass.</p> <p>When using Helm, you can enable this annotation by setting <code>.controller.ingressClassResource.default: true</code> in your Helm chart installation's values file.</p> <p>If you have any old Ingress objects remaining without an IngressClass set, you can do one or more of the following to make the ingress-nginx controller aware of the old objects:</p> <ul> <li>You can manually set the <code>.spec.ingressClassName</code> field in the manifest of your own Ingress resources.</li> <li>You can re-create them after setting the <code>ingressclass.kubernetes.io/is-default-class</code> annotation to <code>true</code> on the IngressClass</li> <li>Alternatively you can make the ingress-nginx controller watch Ingress objects without the ingressClassName field set by starting your ingress-nginx with the flag --watch-ingress-without-class=true.   When using Helm, you can configure your Helm chart installation's values file with <code>.controller.watchIngressWithoutClass: true</code>.</li> </ul> <p>We recommend that you create the IngressClass as shown below:</p> <pre><code>---\napiVersion: networking.k8s.io/v1\nkind: IngressClass\nmetadata:\n  labels:\n    app.kubernetes.io/component: controller\n  name: nginx\n  annotations:\n    ingressclass.kubernetes.io/is-default-class: \"true\"\nspec:\n  controller: k8s.io/ingress-nginx\n</code></pre> <p>and add the value <code>spec.ingressClassName=nginx</code> in your Ingress objects.</p>"},{"location":"user-guide/k8s-122-migration/#i-have-many-ingress-objects-in-my-cluster-what-should-i-do","title":"I have many ingress objects in my cluster. What should I do?","text":"<p>If you have a lot of ingress objects without ingressClass configuration, you can run the ingress controller with the flag <code>--watch-ingress-without-class=true</code>.</p>"},{"location":"user-guide/k8s-122-migration/#what-is-the-flag-watch-ingress-without-class","title":"What is the flag <code>--watch-ingress-without-class</code>?","text":"<p>It's a flag that is passed, as an argument, to the <code>nginx-ingress-controller</code> executable. In the configuration, it looks like this:</p> <pre><code># ...\nargs:\n  - /nginx-ingress-controller\n  - --watch-ingress-without-class=true\n  - --controller-class=k8s.io/ingress-nginx\n  # ...\n# ...\n</code></pre>"},{"location":"user-guide/k8s-122-migration/#i-have-more-than-one-controller-in-my-cluster-and-im-already-using-the-annotation","title":"I have more than one controller in my cluster, and I'm already using the annotation","text":"<p>No problem. This should still keep working, but we highly recommend you to test! Even though <code>kubernetes.io/ingress.class</code> is deprecated, the ingress-nginx controller still understands that annotation. If you want to follow good practice, you should consider migrating to use IngressClass and <code>.spec.ingressClassName</code>.</p>"},{"location":"user-guide/k8s-122-migration/#i-have-more-than-one-controller-running-in-my-cluster-and-i-want-to-use-the-new-api","title":"I have more than one controller running in my cluster, and I want to use the new API","text":"<p>In this scenario, you need to create multiple IngressClasses (see the example above).</p> <p>Be aware that IngressClass works in a very specific way: you will need to change the <code>.spec.controller</code> value in your IngressClass and configure the controller to expect the exact same value.</p> <p>Let's see an example, supposing that you have three IngressClasses:</p> <ul> <li>IngressClass <code>ingress-nginx-one</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx1</code></li> <li>IngressClass <code>ingress-nginx-two</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx2</code></li> <li>IngressClass <code>ingress-nginx-three</code>, with <code>.spec.controller</code> equal to <code>example.com/ingress-nginx1</code></li> </ul> <p>For private use, you can also use a controller name that doesn't contain a <code>/</code>, e.g. <code>ingress-nginx1</code>.</p> <p>When deploying your ingress controllers, you will have to change the <code>--controller-class</code> field as follows:</p> <ul> <li>Ingress-Nginx A, configured to use controller class name <code>example.com/ingress-nginx1</code></li> <li>Ingress-Nginx B, configured to use controller class name <code>example.com/ingress-nginx2</code></li> </ul> <p>When you create an Ingress object with its <code>ingressClassName</code> set to <code>ingress-nginx-two</code>, only controllers looking for the <code>example.com/ingress-nginx2</code> controller class pay attention to the new object.</p> <p>Given that Ingress-Nginx B is set up that way, it will serve that object, whereas Ingress-Nginx A ignores the new Ingress.</p> <p>Bear in mind that if you start Ingress-Nginx B with the command line argument <code>--watch-ingress-without-class=true</code>, it will serve:</p> <ol> <li>Ingresses without any <code>ingressClassName</code> set</li> <li>Ingresses where the deprecated annotation (<code>kubernetes.io/ingress.class</code>) matches the value set in the command line argument <code>--ingress-class</code></li> <li>Ingresses that refer to any IngressClass that has the same <code>spec.controller</code> as configured in <code>--controller-class</code></li> <li>If you start Ingress-Nginx B with the command line argument <code>--watch-ingress-without-class=true</code> and you run Ingress-Nginx A with the command line argument <code>--watch-ingress-without-class=false</code> then this is a supported configuration.    If you have two ingress-nginx controllers for the same cluster, both running with <code>--watch-ingress-without-class=true</code> then there is likely to be a conflict.</li> </ol>"},{"location":"user-guide/k8s-122-migration/#why-am-i-seeing-ingress-class-annotation-is-not-equal-to-the-expected-by-ingress-controller-in-my-controller-logs","title":"Why am I seeing \"ingress class annotation is not equal to the expected by Ingress Controller\" in my controller logs?","text":"<p>It is highly likely that you will also see the name of the ingress resource in the same error message. This error message has been observed on use the deprecated annotation (<code>kubernetes.io/ingress.class</code>) in an Ingress resource manifest. It is recommended to use the <code>.spec.ingressClassName</code> field of the Ingress resource, to specify the name of the IngressClass of the Ingress you are defining.</p>"},{"location":"user-guide/k8s-122-migration/#how-can-i-easily-install-multiple-instances-of-the-ingress-nginx-controller-in-the-same-cluster","title":"How can I easily install multiple instances of the ingress-nginx controller in the same cluster?","text":"<p>You can install them in different namespaces.</p> <ul> <li>Create a new namespace   <pre><code>kubectl create namespace ingress-nginx-2\n</code></pre></li> <li>Use Helm to install the additional instance of the ingress controller</li> <li>Ensure you have Helm working (refer to the Helm documentation)</li> <li>We have to assume that you have the helm repo for the ingress-nginx controller already added to your Helm config.   But, if you have not added the helm repo then you can do this to add the repo to your helm config;   <pre><code>helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx\n</code></pre></li> <li>Make sure you have updated the helm repo data;   <pre><code>helm repo update\n</code></pre></li> <li>Now, install an additional instance of the ingress-nginx controller like this:   <pre><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx  \\\n--namespace ingress-nginx-2 \\\n--set controller.ingressClassResource.name=nginx-two \\\n--set controller.ingressClass=nginx-two \\\n--set controller.ingressClassResource.controllerValue=\"example.com/ingress-nginx-2\" \\\n--set controller.ingressClassResource.enabled=true \\\n--set controller.ingressClassByName=true\n</code></pre></li> </ul> <p>If you need to install yet another instance, then repeat the procedure to create a new namespace, change the values such as names &amp; namespaces (for example from \"-2\" to \"-3\"), or anything else that meets your needs.</p> <p>Note that <code>controller.ingressClassResource.name</code> and <code>controller.ingressClass</code> have to be set correctly. The first is to create the IngressClass object and the other is to modify the deployment of the actual ingress controller pod.</p>"},{"location":"user-guide/k8s-122-migration/#i-cant-use-multiple-namespaces-what-should-i-do","title":"I can't use multiple namespaces, what should I do?","text":"<p>If you need to install all instances in the same namespace, then you need to specify a different election id, like this:</p> <pre><code>helm install ingress-nginx-2 ingress-nginx/ingress-nginx  \\\n--namespace kube-system \\\n--set controller.electionID=nginx-two-leader \\\n--set controller.ingressClassResource.name=nginx-two \\\n--set controller.ingressClass=nginx-two \\\n--set controller.ingressClassResource.controllerValue=\"example.com/ingress-nginx-2\" \\\n--set controller.ingressClassResource.enabled=true \\\n--set controller.ingressClassByName=true\n</code></pre>"},{"location":"user-guide/miscellaneous/","title":"Miscellaneous","text":""},{"location":"user-guide/miscellaneous/#source-ip-address","title":"Source IP address","text":"<p>By default NGINX uses the content of the header <code>X-Forwarded-For</code> as the source of truth to get information about the client IP address. This works without issues in L7 if we configure the setting <code>proxy-real-ip-cidr</code> with the correct information of the IP/network address of trusted external load balancer.</p> <p>If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR.</p> <p>Another option is to enable proxy protocol using <code>use-proxy-protocol: \"true\"</code>.</p> <p>In this mode NGINX does not use the content of the header to get the source IP address of the connection.</p>"},{"location":"user-guide/miscellaneous/#path-types","title":"Path types","text":"<p>Each path in an Ingress is required to have a corresponding path type. Paths that do not include an explicit pathType will fail validation. By default NGINX path type is Prefix to not break existing definitions</p>"},{"location":"user-guide/miscellaneous/#proxy-protocol","title":"Proxy Protocol","text":"<p>If you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the Proxy Protocol for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself.</p> <p>Amongst others ELBs in AWS and HAProxy support Proxy Protocol.</p>"},{"location":"user-guide/miscellaneous/#websockets","title":"Websockets","text":"<p>Support for websockets is provided by NGINX out of the box. No special configuration required.</p> <p>The only requirement to avoid the close of connections is the increase of the values of <code>proxy-read-timeout</code> and <code>proxy-send-timeout</code>.</p> <p>The default value of these settings is <code>60 seconds</code>.</p> <p>A more adequate value to support websockets is a value higher than one hour (<code>3600</code>).</p> <p>Important</p> <p>If the Ingress-Nginx Controller is exposed with a service <code>type=LoadBalancer</code> make sure the protocol between the loadbalancer and NGINX is TCP.</p>"},{"location":"user-guide/miscellaneous/#optimizing-tls-time-to-first-byte-tttfb","title":"Optimizing TLS Time To First Byte (TTTFB)","text":"<p>NGINX provides the configuration option ssl_buffer_size to allow the optimization of the TLS record size.</p> <p>This improves the TLS Time To First Byte (TTTFB). The default value in the Ingress controller is <code>4k</code> (NGINX default is <code>16k</code>).</p>"},{"location":"user-guide/miscellaneous/#retries-in-non-idempotent-methods","title":"Retries in non-idempotent methods","text":"<p>Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error. The previous behavior can be restored using <code>retry-non-idempotent=true</code> in the configuration ConfigMap.</p>"},{"location":"user-guide/miscellaneous/#limitations","title":"Limitations","text":"<ul> <li>Ingress rules for TLS require the definition of the field <code>host</code></li> </ul>"},{"location":"user-guide/miscellaneous/#why-endpoints-and-not-services","title":"Why endpoints and not services","text":"<p>The Ingress-Nginx Controller does not use Services to route traffic to the pods. Instead it uses the Endpoints API in order to bypass kube-proxy to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT.</p>"},{"location":"user-guide/monitoring/","title":"Monitoring","text":"<p>Two different methods to install and configure Prometheus and Grafana are described in this doc. * Prometheus and Grafana installation using Pod Annotations. This installs Prometheus and Grafana in the same namespace as NGINX Ingress * Prometheus and Grafana installation using Service Monitors. This installs Prometheus and Grafana in two different namespaces. This is the preferred method, and helm charts supports this by default.</p>"},{"location":"user-guide/monitoring/#prometheus-and-grafana-installation-using-pod-annotations","title":"Prometheus and Grafana installation using Pod Annotations","text":"<p>This tutorial will show you how to install Prometheus and Grafana for scraping the metrics of the Ingress-Nginx Controller.</p> <p>Important</p> <p>This example uses <code>emptyDir</code> volumes for Prometheus and Grafana. This means once the pod gets terminated you will lose all the data.</p>"},{"location":"user-guide/monitoring/#before-you-begin","title":"Before You Begin","text":"<ul> <li> <p>The Ingress-Nginx Controller should already be deployed according to the deployment instructions here.</p> </li> <li> <p>The controller should be configured for exporting metrics. This requires 3 configurations to the controller. These configurations are :</p> </li> <li>controller.metrics.enabled=true</li> <li>controller.podAnnotations.\"prometheus.io/scrape\"=\"true\"</li> <li> <p>controller.podAnnotations.\"prometheus.io/port\"=\"10254\"</p> </li> <li> <p>The easiest way to configure the controller for metrics is via helm upgrade. Assuming you have installed the ingress-nginx controller as a helm release named ingress-nginx, then you can simply type the command shown below :   <pre><code>helm upgrade ingress-nginx ingress-nginx \\\n--repo https://kubernetes.github.io/ingress-nginx \\\n--namespace ingress-nginx \\\n--set controller.metrics.enabled=true \\\n--set-string controller.podAnnotations.\"prometheus\\.io/scrape\"=\"true\" \\\n--set-string controller.podAnnotations.\"prometheus\\.io/port\"=\"10254\"\n</code></pre></p> </li> <li>You can validate that the controller is configured for metrics by looking at the values of the installed release, like this:   <pre><code>helm get values ingress-nginx --namespace ingress-nginx\n</code></pre></li> <li>You should be able to see the values shown below:   <pre><code>..\ncontroller:\n  metrics:\n    enabled: true\n  podAnnotations:\n    prometheus.io/port: \"10254\"\n    prometheus.io/scrape: \"true\"\n..\n</code></pre></li> <li>If you are not using helm, you will have to edit your manifests like this:<ul> <li>Service manifest:    <pre><code>apiVersion: v1\nkind: Service\n..\nspec:\n  ports:\n    - name: prometheus\n      port: 10254\n      targetPort: prometheus\n      ..\n</code></pre></li> <li>Deployment manifest:      <pre><code>apiVersion: v1\nkind: Deployment\n..\nspec:\n  template:\n    metadata:\n      annotations:\n        prometheus.io/scrape: \"true\"\n        prometheus.io/port: \"10254\"\n    spec:\n      containers:\n        - name: controller\n          ports:\n            - name: prometheus\n              containerPort: 10254\n            ..\n</code></pre></li> </ul> </li> </ul>"},{"location":"user-guide/monitoring/#deploy-and-configure-prometheus-server","title":"Deploy and configure Prometheus Server","text":"<p>Note that the kustomize bases used in this tutorial are stored in the deploy folder of the GitHub repository kubernetes/ingress-nginx.</p> <ul> <li> <p>The Prometheus server must be configured so that it can discover endpoints of services. If a Prometheus server is already running in the cluster and if it is configured in a way that it can find the ingress controller pods, no extra configuration is needed.</p> </li> <li> <p>If there is no existing Prometheus server running, the rest of this tutorial will guide you through the steps needed to deploy a properly configured Prometheus server.</p> </li> <li> <p>Running the following command deploys prometheus in Kubernetes:</p> </li> </ul> <pre><code>kubectl apply --kustomize github.com/kubernetes/ingress-nginx/deploy/prometheus/\n</code></pre>"},{"location":"user-guide/monitoring/#prometheus-dashboard","title":"Prometheus Dashboard","text":"<ul> <li>Open Prometheus dashboard in a web browser:</li> </ul> <pre><code>kubectl get svc -n ingress-nginx\nNAME                   TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                      AGE\ndefault-http-backend   ClusterIP   10.103.59.201   &lt;none&gt;        80/TCP                                       3d\ningress-nginx          NodePort    10.97.44.72     &lt;none&gt;        80:30100/TCP,443:30154/TCP,10254:32049/TCP   5h\nprometheus-server      NodePort    10.98.233.86    &lt;none&gt;        9090:32630/TCP                               1m\n</code></pre> <ul> <li>Obtain the IP address of the nodes in the running cluster:</li> </ul> <pre><code>kubectl get nodes -o wide\n</code></pre> <ul> <li>In some cases where the node only have internal IP addresses we need to execute:</li> </ul> <pre><code>kubectl get nodes --selector=kubernetes.io/role!=master -o jsonpath={.items[*].status.addresses[?\\(@.type==\\\"InternalIP\\\"\\)].address}\n10.192.0.2 10.192.0.3 10.192.0.4\n</code></pre> <ul> <li> <p>Open your browser and visit the following URL: http://{node IP address}:{prometheus-svc-nodeport} to load the Prometheus Dashboard.</p> </li> <li> <p>According to the above example, this URL will be http://10.192.0.3:32630</p> </li> </ul> <p></p>"},{"location":"user-guide/monitoring/#grafana","title":"Grafana","text":"<ul> <li>Install grafana using the below command   <pre><code>kubectl apply --kustomize github.com/kubernetes/ingress-nginx/deploy/grafana/\n</code></pre></li> <li> <p>Look at the services   <pre><code>kubectl get svc -n ingress-nginx\nNAME                   TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                      AGE\ndefault-http-backend   ClusterIP   10.103.59.201   &lt;none&gt;        80/TCP                                       3d\ningress-nginx          NodePort    10.97.44.72     &lt;none&gt;        80:30100/TCP,443:30154/TCP,10254:32049/TCP   5h\nprometheus-server      NodePort    10.98.233.86    &lt;none&gt;        9090:32630/TCP                               10m\ngrafana                NodePort    10.98.233.87    &lt;none&gt;        3000:31086/TCP                               10m\n</code></pre></p> </li> <li> <p>Open your browser and visit the following URL: http://{node IP address}:{grafana-svc-nodeport} to load the Grafana Dashboard. According to the above example, this URL will be http://10.192.0.3:31086</p> </li> </ul> <p>The username and password is <code>admin</code></p> <ul> <li> <p>After the login you can import the Grafana dashboard from official dashboards, by following steps given below :</p> <ul> <li>Navigate to lefthand panel of grafana</li> <li>Hover on the gearwheel icon for Configuration and click \"Data Sources\"</li> <li>Click \"Add data source\"</li> <li>Select \"Prometheus\"</li> <li>Enter the details (note: I used http://CLUSTER_IP_PROMETHEUS_SVC:9090)</li> <li>Left menu (hover over +) -&gt; Dashboard</li> <li>Click \"Import\"</li> <li>Enter the copy pasted json from https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/grafana/dashboards/nginx.json</li> <li>Click Import JSON</li> <li>Select the Prometheus data source</li> <li>Click \"Import\"</li> </ul> </li> </ul> <p></p>"},{"location":"user-guide/monitoring/#caveats","title":"Caveats","text":""},{"location":"user-guide/monitoring/#wildcard-ingresses","title":"Wildcard ingresses","text":"<ul> <li>By default request metrics are labeled with the hostname. When you have a wildcard domain ingress, then there will be no metrics for that ingress (to prevent the metrics from exploding in cardinality). To get metrics in this case you need to run the ingress controller with <code>--metrics-per-host=false</code> (you will lose labeling by hostname, but still have labeling by ingress).</li> </ul>"},{"location":"user-guide/monitoring/#grafana-dashboard-using-ingress-resource","title":"Grafana dashboard using ingress resource","text":"<ul> <li>If you want to expose the dashboard for grafana using an ingress resource, then you can :<ul> <li>change the service type of the prometheus-server service and the grafana service to \"ClusterIP\" like this : <pre><code>kubectl -n ingress-nginx edit svc grafana\n</code></pre></li> <li>This will open the currently deployed service grafana in the default editor configured in your shell (vi/nvim/nano/other)</li> <li>scroll down to line 34 that looks like \"type: NodePort\"</li> <li>change it to look like \"type: ClusterIP\". Save and exit.</li> <li>create an ingress resource with backend as \"grafana\" and port as \"3000\"</li> </ul> </li> <li>Similarly, you can edit the service \"prometheus-server\" and add an ingress resource.</li> </ul>"},{"location":"user-guide/monitoring/#prometheus-and-grafana-installation-using-service-monitors","title":"Prometheus and Grafana installation using Service Monitors","text":"<p>This document assumes you're using helm and using the kube-prometheus-stack package to install Prometheus and Grafana.</p>"},{"location":"user-guide/monitoring/#verify-ingress-nginx-controller-is-installed","title":"Verify Ingress-Nginx Controller is installed","text":"<ul> <li> <p>The Ingress-Nginx Controller should already be deployed according to the deployment instructions here.</p> </li> <li> <p>To check if Ingress controller is deployed,   <pre><code>kubectl get pods -n ingress-nginx\n</code></pre></p> </li> <li>The result should look something like:   <code>NAME                                        READY   STATUS    RESTARTS   AGE   ingress-nginx-controller-7c489dc7b7-ccrf6   1/1     Running   0          19h</code></li> </ul>"},{"location":"user-guide/monitoring/#verify-prometheus-is-installed","title":"Verify Prometheus is installed","text":"<ul> <li>To check if Prometheus is already deployed, run the following command:</li> </ul> <p><pre><code>helm ls -A\n</code></pre> <pre><code>NAME          NAMESPACE       REVISION    UPDATED                                 STATUS      CHART                           APP VERSION\ningress-nginx ingress-nginx   10          2022-01-20 18:08:55.267373 -0800 PST    deployed    ingress-nginx-4.0.16            1.1.1\nprometheus    prometheus      1           2022-01-20 16:07:25.086828 -0800 PST    deployed    kube-prometheus-stack-30.1.0    0.53.1\n</code></pre> - Notice that prometheus is installed in a differenet namespace than ingress-nginx</p> <ul> <li>If prometheus is not installed, then you can install from here</li> </ul>"},{"location":"user-guide/monitoring/#re-configure-ingress-nginx-controller","title":"Re-configure Ingress-Nginx Controller","text":"<ul> <li>The Ingress NGINX controller needs to be reconfigured for exporting metrics. This requires 3 additional configurations to the controller. These configurations are :   <pre><code>controller.metrics.enabled=true\ncontroller.metrics.serviceMonitor.enabled=true\ncontroller.metrics.serviceMonitor.additionalLabels.release=\"prometheus\"\n</code></pre></li> <li>The easiest way of doing this is to helm upgrade   <pre><code>helm upgrade ingress-nginx ingress-nginx/ingress-nginx \\\n--namespace ingress-nginx \\\n--set controller.metrics.enabled=true \\\n--set controller.metrics.serviceMonitor.enabled=true \\\n--set controller.metrics.serviceMonitor.additionalLabels.release=\"prometheus\"\n</code></pre></li> <li> <p>Here <code>controller.metrics.serviceMonitor.additionalLabels.release=\"prometheus\"</code> should match the name of the helm release of the <code>kube-prometheus-stack</code></p> </li> <li> <p>You can validate that the controller has been successfully reconfigured to export metrics by looking at the values of the installed release, like this:   <pre><code>helm get values ingress-nginx --namespace ingress-nginx\n</code></pre> <pre><code>controller:\n  metrics:\n    enabled: true\n    serviceMonitor:\n      additionalLabels:\n        release: prometheus\n      enabled: true\n</code></pre></p> </li> </ul>"},{"location":"user-guide/monitoring/#configure-prometheus","title":"Configure Prometheus","text":"<ul> <li>Since Prometheus is running in a different namespace and not in the ingress-nginx namespace, it would not be able to discover ServiceMonitors in other namespaces when installed. Reconfigure your kube-prometheus-stack Helm installation to set <code>serviceMonitorSelectorNilUsesHelmValues</code> flag to false. By default, Prometheus only discovers PodMonitors within its own namespace. This should be disabled by setting <code>podMonitorSelectorNilUsesHelmValues</code> to false</li> <li>The configurations required are:   <pre><code>prometheus.prometheusSpec.podMonitorSelectorNilUsesHelmValues=false\nprometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues=false\n</code></pre></li> <li>The easiest way of doing this is to use <code>helm upgrade ...</code> <pre><code>helm upgrade prometheus prometheus-community/kube-prometheus-stack \\\n--namespace prometheus  \\\n--set prometheus.prometheusSpec.podMonitorSelectorNilUsesHelmValues=false \\\n--set prometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues=false\n</code></pre></li> <li>You can validate that Prometheus has been reconfigured by looking at the values of the installed release, like this:   <pre><code>helm get values prometheus --namespace prometheus\n</code></pre></li> <li>You should be able to see the values shown below:   <pre><code>prometheus:\n  prometheusSpec:\n    podMonitorSelectorNilUsesHelmValues: false\n    serviceMonitorSelectorNilUsesHelmValues: false\n</code></pre></li> </ul>"},{"location":"user-guide/monitoring/#connect-and-view-prometheus-dashboard","title":"Connect and view Prometheus dashboard","text":"<ul> <li>Port forward to Prometheus service. Find out the name of the prometheus service by using the following command:   <pre><code>kubectl get svc -n prometheus\n</code></pre></li> </ul> <p>The result of this command would look like:   <pre><code>NAME                                      TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE\nalertmanager-operated                     ClusterIP   None             &lt;none&gt;        9093/TCP,9094/TCP,9094/UDP   7h46m\nprometheus-grafana                        ClusterIP   10.106.28.162    &lt;none&gt;        80/TCP                       7h46m\nprometheus-kube-prometheus-alertmanager   ClusterIP   10.108.125.245   &lt;none&gt;        9093/TCP                     7h46m\nprometheus-kube-prometheus-operator       ClusterIP   10.110.220.1     &lt;none&gt;        443/TCP                      7h46m\nprometheus-kube-prometheus-prometheus     ClusterIP   10.102.72.134    &lt;none&gt;        9090/TCP                     7h46m\nprometheus-kube-state-metrics             ClusterIP   10.104.231.181   &lt;none&gt;        8080/TCP                     7h46m\nprometheus-operated                       ClusterIP   None             &lt;none&gt;        9090/TCP                     7h46m\nprometheus-prometheus-node-exporter       ClusterIP   10.96.247.128    &lt;none&gt;        9100/TCP                     7h46m\n</code></pre>   prometheus-kube-prometheus-prometheus is the service we want to port forward to. We can do so using the following command:   <pre><code>kubectl port-forward svc/prometheus-kube-prometheus-prometheus -n prometheus 9090:9090\n</code></pre>   When you run the above command, you should see something like:   <pre><code>Forwarding from 127.0.0.1:9090 -&gt; 9090\nForwarding from [::1]:9090 -&gt; 9090\n</code></pre> - Open your browser and visit the following URL http://localhost:{port-forwarded-port} according to the above example it would be, http://localhost:9090</p> <p></p>"},{"location":"user-guide/monitoring/#connect-and-view-grafana-dashboard","title":"Connect and view Grafana dashboard","text":"<ul> <li>Port forward to Grafana service. Find out the name of the Grafana service by using the following command:   <pre><code>kubectl get svc -n prometheus\n</code></pre></li> </ul> <p>The result of this command would look like:   <pre><code>NAME                                      TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE\nalertmanager-operated                     ClusterIP   None             &lt;none&gt;        9093/TCP,9094/TCP,9094/UDP   7h46m\nprometheus-grafana                        ClusterIP   10.106.28.162    &lt;none&gt;        80/TCP                       7h46m\nprometheus-kube-prometheus-alertmanager   ClusterIP   10.108.125.245   &lt;none&gt;        9093/TCP                     7h46m\nprometheus-kube-prometheus-operator       ClusterIP   10.110.220.1     &lt;none&gt;        443/TCP                      7h46m\nprometheus-kube-prometheus-prometheus     ClusterIP   10.102.72.134    &lt;none&gt;        9090/TCP                     7h46m\nprometheus-kube-state-metrics             ClusterIP   10.104.231.181   &lt;none&gt;        8080/TCP                     7h46m\nprometheus-operated                       ClusterIP   None             &lt;none&gt;        9090/TCP                     7h46m\nprometheus-prometheus-node-exporter       ClusterIP   10.96.247.128    &lt;none&gt;        9100/TCP                     7h46m\n</code></pre>   prometheus-grafana is the service we want to port forward to. We can do so using the following command:   <pre><code>kubectl port-forward svc/prometheus-grafana  3000:80 -n prometheus\n</code></pre>   When you run the above command, you should see something like:   <pre><code>Forwarding from 127.0.0.1:3000 -&gt; 3000\nForwarding from [::1]:3000 -&gt; 3000\n</code></pre> - Open your browser and visit the following URL http://localhost:{port-forwarded-port} according to the above example it would be, http://localhost:3000   The default username/ password is admin/prom-operator - After the login you can import the Grafana dashboard from official dashboards, by following steps given below :</p> <ul> <li>Navigate to lefthand panel of grafana</li> <li>Hover on the gearwheel icon for Configuration and click \"Data Sources\"</li> <li>Click \"Add data source\"</li> <li>Select \"Prometheus\"</li> <li>Enter the details (note: I used http://10.102.72.134:9090 which is the CLUSTER-IP for Prometheus service)</li> <li>Left menu (hover over +) -&gt; Dashboard</li> <li>Click \"Import\"</li> <li>Enter the copy pasted json from https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/grafana/dashboards/nginx.json</li> <li>Click Import JSON</li> <li>Select the Prometheus data source</li> <li>Click \"Import\"</li> </ul> <p></p>"},{"location":"user-guide/monitoring/#exposed-metrics","title":"Exposed metrics","text":"<p>Prometheus metrics are exposed on port 10254.</p>"},{"location":"user-guide/monitoring/#request-metrics","title":"Request metrics","text":"<ul> <li> <p><code>nginx_ingress_controller_request_duration_seconds</code> Histogram\\   The request processing (time elapsed between the first bytes were read from the client and the log write after the last bytes were sent to the client) time in seconds (affected by client speed).\\   nginx var: <code>request_time</code></p> </li> <li> <p><code>nginx_ingress_controller_response_duration_seconds</code> Histogram\\   The time spent on receiving the response from the upstream server in seconds (affected by client speed when the response is bigger than proxy buffers).\\   Note: can be up to several millis bigger than the <code>nginx_ingress_controller_request_duration_seconds</code> because of the different measuring method.   nginx var: <code>upstream_response_time</code></p> </li> <li> <p><code>nginx_ingress_controller_header_duration_seconds</code> Histogram\\   The time spent on receiving first header from the upstream server\\   nginx var: <code>upstream_header_time</code></p> </li> <li> <p><code>nginx_ingress_controller_connect_duration_seconds</code> Histogram\\   The time spent on establishing a connection with the upstream server\\   nginx var: <code>upstream_connect_time</code></p> </li> <li> <p><code>nginx_ingress_controller_response_size</code> Histogram\\   The response length (including request line, header, and request body)\\   nginx var: <code>bytes_sent</code></p> </li> <li> <p><code>nginx_ingress_controller_request_size</code> Histogram\\   The request length (including request line, header, and request body)\\   nginx var: <code>request_length</code></p> </li> <li> <p><code>nginx_ingress_controller_requests</code> Counter\\   The total number of client requests</p> </li> <li> <p><code>nginx_ingress_controller_bytes_sent</code> Histogram\\   The number of bytes sent to a client. Deprecated, use <code>nginx_ingress_controller_response_size</code>\\   nginx var: <code>bytes_sent</code></p> </li> <li> <p><code>nginx_ingress_controller_ingress_upstream_latency_seconds</code> Summary\\   Upstream service latency per Ingress. Deprecated, use <code>nginx_ingress_controller_connect_duration_seconds</code>\\   nginx var: <code>upstream_connect_time</code></p> </li> </ul> <pre><code># HELP nginx_ingress_controller_bytes_sent The number of bytes sent to a client. DEPRECATED! Use nginx_ingress_controller_response_size\n# TYPE nginx_ingress_controller_bytes_sent histogram\n# HELP nginx_ingress_controller_connect_duration_seconds The time spent on establishing a connection with the upstream server\n# TYPE nginx_ingress_controller_connect_duration_seconds nginx_ingress_controller_connect_duration_seconds\n* HELP nginx_ingress_controller_header_duration_seconds The time spent on receiving first header from the upstream server\n# TYPE nginx_ingress_controller_header_duration_seconds histogram\n# HELP nginx_ingress_controller_ingress_upstream_latency_seconds Upstream service latency per Ingress DEPRECATED! Use nginx_ingress_controller_connect_duration_seconds\n# TYPE nginx_ingress_controller_ingress_upstream_latency_seconds summary\n# HELP nginx_ingress_controller_request_duration_seconds The request processing time in milliseconds\n# TYPE nginx_ingress_controller_request_duration_seconds histogram\n# HELP nginx_ingress_controller_request_size The request length (including request line, header, and request body)\n# TYPE nginx_ingress_controller_request_size histogram\n# HELP nginx_ingress_controller_requests The total number of client requests.\n# TYPE nginx_ingress_controller_requests counter\n# HELP nginx_ingress_controller_response_duration_seconds The time spent on receiving the response from the upstream server\n# TYPE nginx_ingress_controller_response_duration_seconds histogram\n# HELP nginx_ingress_controller_response_size The response length (including request line, header, and request body)\n# TYPE nginx_ingress_controller_response_size histogram\n</code></pre>"},{"location":"user-guide/monitoring/#nginx-process-metrics","title":"Nginx process metrics","text":"<pre><code># HELP nginx_ingress_controller_nginx_process_connections current number of client connections with state {active, reading, writing, waiting}\n# TYPE nginx_ingress_controller_nginx_process_connections gauge\n# HELP nginx_ingress_controller_nginx_process_connections_total total number of connections with state {accepted, handled}\n# TYPE nginx_ingress_controller_nginx_process_connections_total counter\n# HELP nginx_ingress_controller_nginx_process_cpu_seconds_total Cpu usage in seconds\n# TYPE nginx_ingress_controller_nginx_process_cpu_seconds_total counter\n# HELP nginx_ingress_controller_nginx_process_num_procs number of processes\n# TYPE nginx_ingress_controller_nginx_process_num_procs gauge\n# HELP nginx_ingress_controller_nginx_process_oldest_start_time_seconds start time in seconds since 1970/01/01\n# TYPE nginx_ingress_controller_nginx_process_oldest_start_time_seconds gauge\n# HELP nginx_ingress_controller_nginx_process_read_bytes_total number of bytes read\n# TYPE nginx_ingress_controller_nginx_process_read_bytes_total counter\n# HELP nginx_ingress_controller_nginx_process_requests_total total number of client requests\n# TYPE nginx_ingress_controller_nginx_process_requests_total counter\n# HELP nginx_ingress_controller_nginx_process_resident_memory_bytes number of bytes of memory in use\n# TYPE nginx_ingress_controller_nginx_process_resident_memory_bytes gauge\n# HELP nginx_ingress_controller_nginx_process_virtual_memory_bytes number of bytes of memory in use\n# TYPE nginx_ingress_controller_nginx_process_virtual_memory_bytes gauge\n# HELP nginx_ingress_controller_nginx_process_write_bytes_total number of bytes written\n# TYPE nginx_ingress_controller_nginx_process_write_bytes_total counter\n</code></pre>"},{"location":"user-guide/monitoring/#controller-metrics","title":"Controller metrics","text":"<pre><code># HELP nginx_ingress_controller_build_info A metric with a constant '1' labeled with information about the build.\n# TYPE nginx_ingress_controller_build_info gauge\n# HELP nginx_ingress_controller_check_success Cumulative number of Ingress controller syntax check operations\n# TYPE nginx_ingress_controller_check_success counter\n# HELP nginx_ingress_controller_config_hash Running configuration hash actually running\n# TYPE nginx_ingress_controller_config_hash gauge\n# HELP nginx_ingress_controller_config_last_reload_successful Whether the last configuration reload attempt was successful\n# TYPE nginx_ingress_controller_config_last_reload_successful gauge\n# HELP nginx_ingress_controller_config_last_reload_successful_timestamp_seconds Timestamp of the last successful configuration reload.\n# TYPE nginx_ingress_controller_config_last_reload_successful_timestamp_seconds gauge\n# HELP nginx_ingress_controller_ssl_certificate_info Hold all labels associated to a certificate\n# TYPE nginx_ingress_controller_ssl_certificate_info gauge\n# HELP nginx_ingress_controller_success Cumulative number of Ingress controller reload operations\n# TYPE nginx_ingress_controller_success counter\n# HELP nginx_ingress_controller_orphan_ingress Gauge reporting status of ingress orphanity, 1 indicates orphaned ingress. 'namespace' is the string used to identify namespace of ingress, 'ingress' for ingress name and 'type' for 'no-service' or 'no-endpoint' of orphanity\n# TYPE nginx_ingress_controller_orphan_ingress gauge\n</code></pre>"},{"location":"user-guide/monitoring/#admission-metrics","title":"Admission metrics","text":"<pre><code># HELP nginx_ingress_controller_admission_config_size The size of the tested configuration\n# TYPE nginx_ingress_controller_admission_config_size gauge\n# HELP nginx_ingress_controller_admission_render_duration The processing duration of ingresses rendering by the admission controller (float seconds)\n# TYPE nginx_ingress_controller_admission_render_duration gauge\n# HELP nginx_ingress_controller_admission_render_ingresses The length of ingresses rendered by the admission controller\n# TYPE nginx_ingress_controller_admission_render_ingresses gauge\n# HELP nginx_ingress_controller_admission_roundtrip_duration The complete duration of the admission controller at the time to process a new event (float seconds)\n# TYPE nginx_ingress_controller_admission_roundtrip_duration gauge\n# HELP nginx_ingress_controller_admission_tested_duration The processing duration of the admission controller tests (float seconds)\n# TYPE nginx_ingress_controller_admission_tested_duration gauge\n# HELP nginx_ingress_controller_admission_tested_ingresses The length of ingresses processed by the admission controller\n# TYPE nginx_ingress_controller_admission_tested_ingresses gauge\n</code></pre>"},{"location":"user-guide/monitoring/#histogram-buckets","title":"Histogram buckets","text":"<p>You can configure buckets for histogram metrics using these command line options (here are their default values): * <code>--time-buckets=[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]</code> * <code>--length-buckets=[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]</code> * <code>--size-buckets=[10, 100, 1000, 10000, 100000, 1e+06, 1e+07]</code></p>"},{"location":"user-guide/multiple-ingress/","title":"Multiple Ingress controllers","text":"<p>By default, deploying multiple Ingress controllers (e.g., <code>ingress-nginx</code> &amp; <code>gce</code>) will result in all controllers simultaneously racing to update Ingress status fields in confusing ways.</p> <p>To fix this problem, use IngressClasses. The <code>kubernetes.io/ingress.class</code> annotation is not being preferred or suggested to use as it can be deprecated in the future. Better to use the field <code>ingress.spec.ingressClassName</code>. But, when user has deployed with <code>scope.enabled</code>, then the ingress class resource field is not used.</p>"},{"location":"user-guide/multiple-ingress/#using-ingressclasses","title":"Using IngressClasses","text":"<p>If all ingress controllers respect IngressClasses (e.g. multiple instances of ingress-nginx v1.0), you can deploy two Ingress controllers by granting them control over two different IngressClasses, then selecting one of the two IngressClasses with <code>ingressClassName</code>.</p> <p>First, ensure the <code>--controller-class=</code> and <code>--ingress-class</code> are set to something different on each ingress controller, If your additional ingress controller is to be installed in a namespace, where there is/are one/more-than-one ingress-nginx-controller(s) already installed, then you need to specify a different unique <code>--election-id</code> for the new instance of the controller.</p> <pre><code># ingress-nginx Deployment/Statefulset\nspec:\n  template:\n     spec:\n       containers:\n         - name: ingress-nginx-internal-controller\n           args:\n             - /nginx-ingress-controller\n             - '--election-id=ingress-controller-leader'\n             - '--controller-class=k8s.io/internal-ingress-nginx'\n             - '--ingress-class=k8s.io/internal-nginx'\n            ...\n</code></pre> <p>Then use the same value in the IngressClass:</p> <pre><code># ingress-nginx IngressClass\napiVersion: networking.k8s.io/v1\nkind: IngressClass\nmetadata:\n  name: internal-nginx\nspec:\n  controller: k8s.io/internal-ingress-nginx\n  ...\n</code></pre> <p>And refer to that IngressClass in your Ingress:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: my-ingress\nspec:\n  ingressClassName: internal-nginx\n  ...\n</code></pre> <p>or if installing with Helm:</p> <pre><code>controller:\n  electionID: ingress-controller-leader\n  ingressClassResource:\n    name: internal-nginx  # default: nginx\n    enabled: true\n    default: false\n    controllerValue: \"k8s.io/internal-ingress-nginx\"  # default: k8s.io/ingress-nginx\n</code></pre> <p>Important</p> <p>When running multiple ingress-nginx controllers, it will only process an unset class annotation if one of the controllers uses the default <code>--controller-class</code> value (see <code>IsValid</code> method in <code>internal/ingress/annotations/class/main.go</code>), otherwise the class annotation becomes required.</p> <p>If <code>--controller-class</code> is set to the default value of <code>k8s.io/ingress-nginx</code>, the controller will monitor Ingresses with no class annotation and Ingresses with annotation class set to <code>nginx</code>. Use a non-default value for <code>--controller-class</code>, to ensure that the controller only satisfied the specific class of Ingresses.</p>"},{"location":"user-guide/multiple-ingress/#using-the-kubernetesioingressclass-annotation-in-deprecation","title":"Using the kubernetes.io/ingress.class annotation (in deprecation)","text":"<p>If you're running multiple ingress controllers where one or more do not support IngressClasses, you must specify the annotation <code>kubernetes.io/ingress.class: \"nginx\"</code> in all ingresses that you would like ingress-nginx to claim.</p> <p>For instance,</p> <pre><code>metadata:\n  name: foo\n  annotations:\n    kubernetes.io/ingress.class: \"gce\"\n</code></pre> <p>will target the GCE controller, forcing the Ingress-NGINX controller to ignore it, while an annotation like:</p> <pre><code>metadata:\n  name: foo\n  annotations:\n    kubernetes.io/ingress.class: \"nginx\"\n</code></pre> <p>will target the Ingress-NGINX controller, forcing the GCE controller to ignore it.</p> <p>You can change the value \"nginx\" to something else by setting the <code>--ingress-class</code> flag:</p> <pre><code>spec:\n  template:\n     spec:\n       containers:\n         - name: ingress-nginx-internal-controller\n           args:\n             - /nginx-ingress-controller\n             - --ingress-class=internal-nginx\n</code></pre> <p>then setting the corresponding <code>kubernetes.io/ingress.class: \"internal-nginx\"</code> annotation on your Ingresses.</p> <p>To reiterate, setting the annotation to any value which does not match a valid ingress class will force the Ingress-Nginx Controller to ignore your Ingress. If you are only running a single Ingress-Nginx Controller, this can be achieved by setting the annotation to any value except \"nginx\" or an empty string.</p> <p>Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.</p>"},{"location":"user-guide/retaining-client-ipaddress/","title":"Retaining client ipaddress","text":""},{"location":"user-guide/retaining-client-ipaddress/#retaining-client-ipaddress","title":"Retaining Client IPAddress","text":"<p>Please read this https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/#source-ip-address , to get details of retaining the client IPAddress.</p>"},{"location":"user-guide/retaining-client-ipaddress/#using-proxy-protocol","title":"Using proxy-protocol","text":"<p>Please read this https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/#proxy-protocol , to use proxy-protocol for retaining client IPAddress</p>"},{"location":"user-guide/retaining-client-ipaddress/#using-the-k8s-spec-servicespecexternaltrafficpolicy","title":"Using the K8S spec service.spec.externalTrafficPolicy","text":"<pre><code>% kubectl explain service.spec.externalTrafficPolicy\nKIND:       Service\nVERSION:    v1\n\nFIELD: externalTrafficPolicy &lt;string&gt;\n\nDESCRIPTION:\n    externalTrafficPolicy describes how nodes distribute service traffic they\n    receive on one of the Service's \"externally-facing\" addresses (NodePorts,\n    ExternalIPs, and LoadBalancer IPs). If set to \"Local\", the proxy will\n    configure the service in a way that assumes that external load balancers\n    will take care of balancing the service traffic between nodes, and so each\n    node will deliver traffic only to the node-local endpoints of the service,\n    without masquerading the client source IP. (Traffic mistakenly sent to a\n    node with no endpoints will be dropped.) The default value, \"Cluster\", uses\n    the standard behavior of routing to all endpoints evenly (possibly modified\n    by topology and other features). Note that traffic sent to an External IP or\n    LoadBalancer IP from within the cluster will always get \"Cluster\" semantics,\n    but clients sending to a NodePort from within the cluster may need to take\n    traffic policy into account when picking a node.\n\n    Possible enum values:\n     - `\"Cluster\"` routes traffic to all endpoints.\n     - `\"Local\"` preserves the source IP of the traffic by routing only to\n    endpoints on the same node as the traffic was received on (dropping the\n    traffic if there are no local endpoints).\n</code></pre> <ul> <li>Setting the field <code>externalTrafficPolicy</code>, in the ingress-controller service, to a value of <code>Local</code> retains the client's ipaddress, within the scope explained above</li> </ul>"},{"location":"user-guide/tls/","title":"TLS/HTTPS","text":""},{"location":"user-guide/tls/#tls-secrets","title":"TLS Secrets","text":"<p>Anytime we reference a TLS secret, we mean a PEM-encoded X.509, RSA (2048) secret.</p> <p>Warning</p> <p>Ensure that the certificate order is leaf-&gt;intermediate-&gt;root, otherwise the controller will not be able to import the certificate, and you'll see this error in the logs <code>W1012 09:15:45.920000       6 backend_ssl.go:46] Error obtaining X.509 certificate: unexpected error creating SSL Cert: certificate and private key does not have a matching public key: tls: private key does not match public key</code></p> <p>You can generate a self-signed certificate and private key with:</p> <pre><code>$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${CERT_FILE} -subj \"/CN=${HOST}/O=${HOST}\" -addext \"subjectAltName = DNS:${HOST}\"\n</code></pre> <p>Then create the secret in the cluster via:</p> <pre><code>kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE}\n</code></pre> <p>The resulting secret will be of type <code>kubernetes.io/tls</code>.</p>"},{"location":"user-guide/tls/#host-names","title":"Host names","text":"<p>Ensure that the relevant ingress rules specify a matching host name.</p>"},{"location":"user-guide/tls/#default-ssl-certificate","title":"Default SSL Certificate","text":"<p>NGINX provides the option to configure a server as a catch-all with server_name for requests that do not match any of the configured server names. This configuration works out-of-the-box for HTTP traffic. For HTTPS, a certificate is naturally required.</p> <p>For this reason the Ingress controller provides the flag <code>--default-ssl-certificate</code>. The secret referred to by this flag contains the default certificate to be used when accessing the catch-all server. If this flag is not provided NGINX will use a self-signed certificate.</p> <p>For instance, if you have a TLS secret <code>foo-tls</code> in the <code>default</code> namespace, add <code>--default-ssl-certificate=default/foo-tls</code> in the <code>nginx-controller</code> deployment.</p> <p>The default certificate will also be used for ingress <code>tls:</code> sections that do not have a <code>secretName</code> option.</p> <p>To force redirects for Ingresses that do not specify a TLS-block at all, take a look at <code>force-ssl-redirect</code> in ConfigMap.</p>"},{"location":"user-guide/tls/#ssl-passthrough","title":"SSL Passthrough","text":"<p>The <code>--enable-ssl-passthrough</code> flag enables the SSL Passthrough feature, which is disabled by default. This is required to enable passthrough backends in Ingress objects.</p> <p>Warning</p> <p>This feature is implemented by intercepting all traffic on the configured HTTPS port (default: 443) and handing it over to a local TCP proxy. This bypasses NGINX completely and introduces a non-negligible performance penalty.</p> <p>SSL Passthrough leverages SNI and reads the virtual domain from the TLS negotiation, which requires compatible clients. After a connection has been accepted by the TLS listener, it is handled by the controller itself and piped back and forth between the backend and the client.</p> <p>If there is no hostname matching the requested host name, the request is handed over to NGINX on the configured passthrough proxy port (default: 442), which proxies the request to the default backend.</p> <p>Note</p> <p>Unlike HTTP backends, traffic to Passthrough backends is sent to the clusterIP of the backing Service instead of individual Endpoints.</p>"},{"location":"user-guide/tls/#http-strict-transport-security","title":"HTTP Strict Transport Security","text":"<p>HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS.</p> <p>HSTS is enabled by default.</p> <p>To disable this behavior use <code>hsts: \"false\"</code> in the configuration ConfigMap.</p>"},{"location":"user-guide/tls/#server-side-https-enforcement-through-redirect","title":"Server-side HTTPS enforcement through redirect","text":"<p>By default the controller redirects HTTP clients to the HTTPS port 443 using a 308 Permanent Redirect response if TLS is enabled for that Ingress.</p> <p>This can be disabled globally using <code>ssl-redirect: \"false\"</code> in the NGINX config map, or per-Ingress with the <code>nginx.ingress.kubernetes.io/ssl-redirect: \"false\"</code> annotation in the particular resource.</p> <p>Tip</p> <p>When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is no TLS certificate available. This can be achieved by using the <code>nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"</code> annotation in the particular resource.</p>"},{"location":"user-guide/tls/#automated-certificate-management-with-cert-manager","title":"Automated Certificate Management with cert-manager","text":"<p>cert-manager automatically requests missing or expired certificates from a range of  supported issuers (including Let's Encrypt) by monitoring  ingress resources.</p> <p>To set up cert-manager you should take a look at this full example.</p> <p>To enable it for an ingress resource you have to deploy cert-manager, configure a certificate  issuer update the manifest:</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: ingress-demo\n  annotations:\n    cert-manager.io/issuer: \"letsencrypt-staging\" # Replace this with a production issuer once you've tested it\n    [..]\nspec:\n  tls:\n    - hosts:\n        - ingress-demo.example.com\n      secretName: ingress-demo-tls\n    [...]\n</code></pre>"},{"location":"user-guide/tls/#default-tls-version-and-ciphers","title":"Default TLS Version and Ciphers","text":"<p>To provide the most secure baseline configuration possible,</p> <p>ingress-nginx defaults to using TLS 1.2 and 1.3 only, with a secure set of TLS ciphers.</p>"},{"location":"user-guide/tls/#legacy-tls","title":"Legacy TLS","text":"<p>The default configuration, though secure, does not support some older browsers and operating systems.</p> <p>For instance, TLS 1.1+ is only enabled by default from Android 5.0 on. At the time of writing, May 2018, approximately 15% of Android devices are not compatible with ingress-nginx's default configuration.</p> <p>To change this default behavior, use a ConfigMap.</p> <p>A sample ConfigMap fragment to allow these older clients to connect could look something like the following (generated using the Mozilla SSL Configuration Generator)mozilla-ssl-config-old:</p> <pre><code>kind: ConfigMap\napiVersion: v1\nmetadata:\n  name: nginx-config\ndata:\n  ssl-ciphers: \"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA\"\n  ssl-protocols: \"TLSv1 TLSv1.1 TLSv1.2 TLSv1.3\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/","title":"NGINX Configuration","text":"<p>There are three ways to customize NGINX:</p> <ol> <li>ConfigMap: using a Configmap to set global configurations in NGINX.</li> <li>Annotations: use this if you want a specific configuration for a particular Ingress rule.</li> <li>Custom template: when more specific settings are required, like open_file_cache, adjust listen options as <code>rcvbuf</code> or when is not possible to change the configuration through the ConfigMap.</li> </ol>"},{"location":"user-guide/nginx-configuration/annotations/","title":"Annotations","text":"<p>You can add these Kubernetes annotations to specific Ingress objects to customize their behavior.</p> <p>Tip</p> <p>Annotation keys and values can only be strings. Other types, such as boolean or numeric values must be quoted, i.e. <code>\"true\"</code>, <code>\"false\"</code>, <code>\"100\"</code>.</p> <p>Note</p> <p>The annotation prefix can be changed using the <code>--annotations-prefix</code> command line argument, but the default is <code>nginx.ingress.kubernetes.io</code>, as described in the table below.</p> Name type nginx.ingress.kubernetes.io/app-root string nginx.ingress.kubernetes.io/affinity cookie nginx.ingress.kubernetes.io/affinity-mode \"balanced\" or \"persistent\" nginx.ingress.kubernetes.io/affinity-canary-behavior \"sticky\" or \"legacy\" nginx.ingress.kubernetes.io/auth-realm string nginx.ingress.kubernetes.io/auth-secret string nginx.ingress.kubernetes.io/auth-secret-type string nginx.ingress.kubernetes.io/auth-type \"basic\" or \"digest\" nginx.ingress.kubernetes.io/auth-tls-secret string nginx.ingress.kubernetes.io/auth-tls-verify-depth number nginx.ingress.kubernetes.io/auth-tls-verify-client string nginx.ingress.kubernetes.io/auth-tls-error-page string nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/auth-tls-match-cn string nginx.ingress.kubernetes.io/auth-url string nginx.ingress.kubernetes.io/auth-cache-key string nginx.ingress.kubernetes.io/auth-cache-duration string nginx.ingress.kubernetes.io/auth-keepalive number nginx.ingress.kubernetes.io/auth-keepalive-share-vars \"true\" or \"false\" nginx.ingress.kubernetes.io/auth-keepalive-requests number nginx.ingress.kubernetes.io/auth-keepalive-timeout number nginx.ingress.kubernetes.io/auth-proxy-set-headers string nginx.ingress.kubernetes.io/auth-snippet string nginx.ingress.kubernetes.io/enable-global-auth \"true\" or \"false\" nginx.ingress.kubernetes.io/backend-protocol string nginx.ingress.kubernetes.io/canary \"true\" or \"false\" nginx.ingress.kubernetes.io/canary-by-header string nginx.ingress.kubernetes.io/canary-by-header-value string nginx.ingress.kubernetes.io/canary-by-header-pattern string nginx.ingress.kubernetes.io/canary-by-cookie string nginx.ingress.kubernetes.io/canary-weight number nginx.ingress.kubernetes.io/canary-weight-total number nginx.ingress.kubernetes.io/client-body-buffer-size string nginx.ingress.kubernetes.io/configuration-snippet string nginx.ingress.kubernetes.io/custom-http-errors []int nginx.ingress.kubernetes.io/custom-headers string nginx.ingress.kubernetes.io/default-backend string nginx.ingress.kubernetes.io/enable-cors \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-allow-origin string nginx.ingress.kubernetes.io/cors-allow-methods string nginx.ingress.kubernetes.io/cors-allow-headers string nginx.ingress.kubernetes.io/cors-expose-headers string nginx.ingress.kubernetes.io/cors-allow-credentials \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-max-age number nginx.ingress.kubernetes.io/force-ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/from-to-www-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/http2-push-preload \"true\" or \"false\" nginx.ingress.kubernetes.io/limit-connections number nginx.ingress.kubernetes.io/limit-rps number nginx.ingress.kubernetes.io/global-rate-limit number nginx.ingress.kubernetes.io/global-rate-limit-window duration nginx.ingress.kubernetes.io/global-rate-limit-key string nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs string nginx.ingress.kubernetes.io/permanent-redirect string nginx.ingress.kubernetes.io/permanent-redirect-code number nginx.ingress.kubernetes.io/temporal-redirect string nginx.ingress.kubernetes.io/preserve-trailing-slash \"true\" or \"false\" nginx.ingress.kubernetes.io/proxy-body-size string nginx.ingress.kubernetes.io/proxy-cookie-domain string nginx.ingress.kubernetes.io/proxy-cookie-path string nginx.ingress.kubernetes.io/proxy-connect-timeout number nginx.ingress.kubernetes.io/proxy-send-timeout number nginx.ingress.kubernetes.io/proxy-read-timeout number nginx.ingress.kubernetes.io/proxy-next-upstream string nginx.ingress.kubernetes.io/proxy-next-upstream-timeout number nginx.ingress.kubernetes.io/proxy-next-upstream-tries number nginx.ingress.kubernetes.io/proxy-request-buffering string nginx.ingress.kubernetes.io/proxy-redirect-from string nginx.ingress.kubernetes.io/proxy-redirect-to string nginx.ingress.kubernetes.io/proxy-http-version \"1.0\" or \"1.1\" nginx.ingress.kubernetes.io/proxy-ssl-secret string nginx.ingress.kubernetes.io/proxy-ssl-ciphers string nginx.ingress.kubernetes.io/proxy-ssl-name string nginx.ingress.kubernetes.io/proxy-ssl-protocols string nginx.ingress.kubernetes.io/proxy-ssl-verify string nginx.ingress.kubernetes.io/proxy-ssl-verify-depth number nginx.ingress.kubernetes.io/proxy-ssl-server-name string nginx.ingress.kubernetes.io/enable-rewrite-log \"true\" or \"false\" nginx.ingress.kubernetes.io/rewrite-target URI nginx.ingress.kubernetes.io/satisfy string nginx.ingress.kubernetes.io/server-alias string nginx.ingress.kubernetes.io/server-snippet string nginx.ingress.kubernetes.io/service-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-change-on-failure \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-domain string nginx.ingress.kubernetes.io/session-cookie-expires string nginx.ingress.kubernetes.io/session-cookie-max-age string nginx.ingress.kubernetes.io/session-cookie-name string nginx.ingress.kubernetes.io/session-cookie-path string nginx.ingress.kubernetes.io/session-cookie-samesite string nginx.ingress.kubernetes.io/session-cookie-secure string nginx.ingress.kubernetes.io/ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/ssl-passthrough \"true\" or \"false\" nginx.ingress.kubernetes.io/stream-snippet string nginx.ingress.kubernetes.io/upstream-hash-by string nginx.ingress.kubernetes.io/x-forwarded-prefix string nginx.ingress.kubernetes.io/load-balance string nginx.ingress.kubernetes.io/upstream-vhost string nginx.ingress.kubernetes.io/denylist-source-range CIDR nginx.ingress.kubernetes.io/whitelist-source-range CIDR nginx.ingress.kubernetes.io/proxy-buffering string nginx.ingress.kubernetes.io/proxy-buffers-number number nginx.ingress.kubernetes.io/proxy-buffer-size string nginx.ingress.kubernetes.io/proxy-max-temp-file-size string nginx.ingress.kubernetes.io/ssl-ciphers string nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers \"true\" or \"false\" nginx.ingress.kubernetes.io/connection-proxy-header string nginx.ingress.kubernetes.io/enable-access-log \"true\" or \"false\" nginx.ingress.kubernetes.io/enable-opentelemetry \"true\" or \"false\" nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span \"true\" or \"false\" nginx.ingress.kubernetes.io/use-regex bool nginx.ingress.kubernetes.io/enable-modsecurity bool nginx.ingress.kubernetes.io/enable-owasp-core-rules bool nginx.ingress.kubernetes.io/modsecurity-transaction-id string nginx.ingress.kubernetes.io/modsecurity-snippet string nginx.ingress.kubernetes.io/mirror-request-body string nginx.ingress.kubernetes.io/mirror-target string nginx.ingress.kubernetes.io/mirror-host string"},{"location":"user-guide/nginx-configuration/annotations/#canary","title":"Canary","text":"<p>In some cases, you may want to \"canary\" a new set of changes by sending a small number of requests to a different service than the production service. The canary annotation enables the Ingress spec to act as an alternative service for requests to route to depending on the rules applied. The following annotations to configure canary can be enabled after <code>nginx.ingress.kubernetes.io/canary: \"true\"</code> is set:</p> <ul> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-header</code>: The header to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the request header is set to <code>always</code>, it will be routed to the canary. When the header is set to <code>never</code>, it will never be routed to the canary. For any other value, the header will be ignored and the request compared against the other canary rules by precedence.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-header-value</code>: The header value to match for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the request header is set to this value, it will be routed to the canary. For any other header value, the header will be ignored and the request compared against the other canary rules by precedence. This annotation has to be used together with <code>nginx.ingress.kubernetes.io/canary-by-header</code>. The annotation is an extension of the <code>nginx.ingress.kubernetes.io/canary-by-header</code> to allow customizing the header value instead of using hardcoded values. It doesn't have any effect if the <code>nginx.ingress.kubernetes.io/canary-by-header</code> annotation is not defined.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-header-pattern</code>: This works the same way as <code>canary-by-header-value</code> except it does PCRE Regex matching. Note that when <code>canary-by-header-value</code> is set this annotation will be ignored. When the given Regex causes error during request processing, the request will be considered as not matching.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-by-cookie</code>: The cookie to use for notifying the Ingress to route the request to the service specified in the Canary Ingress. When the cookie value is set to <code>always</code>, it will be routed to the canary. When the cookie is set to <code>never</code>, it will never be routed to the canary. For any other value, the cookie will be ignored and the request compared against the other canary rules by precedence.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/canary-weight</code>: The integer based (0 - ) percent of random requests that should be routed to the service specified in the canary Ingress. A weight of 0 implies that no requests will be sent to the service in the Canary ingress by this canary rule. A weight of <code>&lt;weight-total&gt;</code> means implies all requests will be sent to the alternative service specified in the Ingress. <code>&lt;weight-total&gt;</code> defaults to 100, and can be increased via <code>nginx.ingress.kubernetes.io/canary-weight-total</code>. <li> <p><code>nginx.ingress.kubernetes.io/canary-weight-total</code>: The total weight of traffic. If unspecified, it defaults to 100.</p> </li> <p>Canary rules are evaluated in order of precedence. Precedence is as follows: <code>canary-by-header -&gt; canary-by-cookie -&gt; canary-weight</code></p> <p>Note that when you mark an ingress as canary, then all the other non-canary annotations will be ignored (inherited from the corresponding main ingress) except <code>nginx.ingress.kubernetes.io/load-balance</code>, <code>nginx.ingress.kubernetes.io/upstream-hash-by</code>, and annotations related to session affinity. If you want to restore the original behavior of canaries when session affinity was ignored, set <code>nginx.ingress.kubernetes.io/affinity-canary-behavior</code> annotation with value <code>legacy</code> on the canary ingress definition.</p> <p>Known Limitations</p> <p>Currently a maximum of one canary ingress can be applied per Ingress rule.</p>"},{"location":"user-guide/nginx-configuration/annotations/#rewrite","title":"Rewrite","text":"<p>In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404. Set the annotation <code>nginx.ingress.kubernetes.io/rewrite-target</code> to the path expected by the service.</p> <p>If the Application Root is exposed in a different path and needs to be redirected, set the annotation <code>nginx.ingress.kubernetes.io/app-root</code> to redirect requests for <code>/</code>.</p> <p>Example</p> <p>Please check the rewrite example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#session-affinity","title":"Session Affinity","text":"<p>The annotation <code>nginx.ingress.kubernetes.io/affinity</code> enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server. The only affinity type available for NGINX is <code>cookie</code>.</p> <p>The annotation <code>nginx.ingress.kubernetes.io/affinity-mode</code> defines the stickiness of a session. Setting this to <code>balanced</code> (default) will redistribute some sessions if a deployment gets scaled up, therefore rebalancing the load on the servers. Setting this to <code>persistent</code> will not rebalance sessions to new servers, therefore providing maximum stickiness.</p> <p>The annotation <code>nginx.ingress.kubernetes.io/affinity-canary-behavior</code> defines the behavior of canaries when session affinity is enabled. Setting this to <code>sticky</code> (default) will ensure that users that were served by canaries, will continue to be served by canaries. Setting this to <code>legacy</code> will restore original canary behavior, when session affinity was ignored.</p> <p>Attention</p> <p>If more than one Ingress is defined for a host and at least one Ingress uses <code>nginx.ingress.kubernetes.io/affinity: cookie</code>, then only paths on the Ingress using <code>nginx.ingress.kubernetes.io/affinity</code> will use session cookie affinity. All paths defined on other Ingresses for the host will be load balanced through the random selection of a backend server.</p> <p>Example</p> <p>Please check the affinity example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#cookie-affinity","title":"Cookie affinity","text":"<p>If you use the <code>cookie</code> affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation <code>nginx.ingress.kubernetes.io/session-cookie-name</code>. The default is to create a cookie named 'INGRESSCOOKIE'.</p> <p>The NGINX annotation <code>nginx.ingress.kubernetes.io/session-cookie-path</code> defines the path that will be set on the cookie. This is optional unless the annotation <code>nginx.ingress.kubernetes.io/use-regex</code> is set to true; Session cookie paths do not support regex.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-domain</code> to set the <code>Domain</code> attribute of the sticky cookie.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-samesite</code> to apply a <code>SameSite</code> attribute to the sticky cookie. Browser accepted values are <code>None</code>, <code>Lax</code>, and <code>Strict</code>. Some browsers reject cookies with <code>SameSite=None</code>, including those created before the <code>SameSite=None</code> specification (e.g. Chrome 5X). Other browsers mistakenly treat <code>SameSite=None</code> cookies as <code>SameSite=Strict</code> (e.g. Safari running on OSX 14). To omit <code>SameSite=None</code> from browsers with these incompatibilities, add the annotation <code>nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: \"true\"</code>.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-expires</code> to control the cookie expires, its value is a number of seconds until the cookie expires.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-path</code> to control the cookie path when use-regex is set to true.</p> <p>Use <code>nginx.ingress.kubernetes.io/session-cookie-change-on-failure</code> to control the cookie change after request failure.</p>"},{"location":"user-guide/nginx-configuration/annotations/#authentication","title":"Authentication","text":"<p>It is possible to add authentication by adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords.</p> <p>The annotations are: <pre><code>nginx.ingress.kubernetes.io/auth-type: [basic|digest]\n</code></pre></p> <p>Indicates the HTTP Authentication Type: Basic or Digest Access Authentication.</p> <pre><code>nginx.ingress.kubernetes.io/auth-secret: secretName\n</code></pre> <p>The name of the Secret that contains the usernames and passwords which are granted access to the <code>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> <pre><code>nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]\n</code></pre> <p>The <code>auth-secret</code> can have two forms:</p> <ul> <li><code>auth-file</code> - default, an htpasswd file in the key <code>auth</code> within the secret</li> <li><code>auth-map</code> - the keys of the secret are the usernames, and the values are the hashed passwords</li> </ul> <pre><code>nginx.ingress.kubernetes.io/auth-realm: \"realm string\"\n</code></pre> <p>Example</p> <p>Please check the auth example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-nginx-upstream-hashing","title":"Custom NGINX upstream hashing","text":"<p>NGINX supports load balancing by client-server mapping based on consistent hashing 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 ketama consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.</p> <p>There is a special mode of upstream hashing called subset. In this mode, upstream servers are grouped into subsets, and stickiness works by mapping keys to a subset instead of individual upstream servers. Specific server is chosen uniformly at random from the selected sticky subset. It provides a balance between stickiness and load distribution.</p> <p>To enable consistent hashing for a backend:</p> <p><code>nginx.ingress.kubernetes.io/upstream-hash-by</code>: the nginx variable, text value or any combination thereof to use for consistent hashing. For example: <code>nginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri\"</code> or <code>nginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri$host\"</code> or <code>nginx.ingress.kubernetes.io/upstream-hash-by: \"${request_uri}-text-value\"</code> to consistently hash upstream requests by the current request URI.</p> <p>\"subset\" hashing can be enabled setting <code>nginx.ingress.kubernetes.io/upstream-hash-by-subset</code>: \"true\". This maps requests to subset of nodes instead of a single one. <code>nginx.ingress.kubernetes.io/upstream-hash-by-subset-size</code> determines the size of each subset (default 3).</p> <p>Please check the chashsubset example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-nginx-load-balancing","title":"Custom NGINX load balancing","text":"<p>This is similar to <code>load-balance</code> in ConfigMap, but configures load balancing algorithm per ingress.</p> <p>Note that <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> takes preference over this. If this and <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> are not set then we fallback to using globally configured load balancing algorithm.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-nginx-upstream-vhost","title":"Custom NGINX upstream vhost","text":"<p>This configuration setting allows you to control the value for host in the following statement: <code>proxy_set_header Host $host</code>, which forms part of the location block.  This is useful if you need to call the upstream server by something other than <code>$host</code>.</p>"},{"location":"user-guide/nginx-configuration/annotations/#client-certificate-authentication","title":"Client Certificate Authentication","text":"<p>It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.</p> <p>Client Certificate Authentication is applied per host and it is not possible to specify rules that differ for individual paths.</p> <p>To enable, add the annotation <code>nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName</code>. This secret must have a file named <code>ca.crt</code> containing the full Certificate Authority chain <code>ca.crt</code> that is enabled to authenticate against this Ingress.</p> <p>You can further customize client certificate authentication and behavior with these annotations:</p> <ul> <li><code>nginx.ingress.kubernetes.io/auth-tls-verify-depth</code>: The validation depth between the provided client certificate and the Certification Authority chain. (default: 1)</li> <li><code>nginx.ingress.kubernetes.io/auth-tls-verify-client</code>: Enables verification of client certificates. Possible values are:<ul> <li><code>on</code>: Request a client certificate that must be signed by a certificate that is included in the secret key <code>ca.crt</code> of the secret specified by <code>nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName</code>. Failed certificate verification will result in a status code 400 (Bad Request) (default)</li> <li><code>off</code>: Don't request client certificates and don't do client certificate verification.</li> <li><code>optional</code>: Do optional client certificate validation against the CAs from <code>auth-tls-secret</code>. The request fails with status code 400 (Bad Request) when a certificate is provided that is not signed by the CA. When no or an otherwise invalid certificate is provided, the request does not fail, but instead the verification result is sent to the upstream service.</li> <li><code>optional_no_ca</code>: Do optional client certificate validation, but do not fail the request when the client certificate is not signed by the CAs from <code>auth-tls-secret</code>. Certificate verification result is sent to the upstream service.</li> </ul> </li> <li><code>nginx.ingress.kubernetes.io/auth-tls-error-page</code>: The URL/Page that user should be redirected in case of a Certificate Authentication Error</li> <li><code>nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream</code>: Indicates if the received certificates should be passed or not to the upstream server in the header <code>ssl-client-cert</code>. Possible values are \"true\" or \"false\" (default).</li> <li><code>nginx.ingress.kubernetes.io/auth-tls-match-cn</code>: Adds a sanity check for the CN of the client certificate that is sent over using a string / regex starting with \"CN=\", example: <code>\"CN=myvalidclient\"</code>. If the certificate CN sent during mTLS does not match your string / regex it will fail with status code 403. Another way of using this is by adding multiple options in your regex, example: <code>\"CN=(option1|option2|myvalidclient)\"</code>. In this case, as long as one of the options in the brackets matches the certificate CN then you will receive a 200 status code. </li> </ul> <p>The following headers are sent to the upstream service according to the <code>auth-tls-*</code> annotations:</p> <ul> <li><code>ssl-client-issuer-dn</code>: The issuer information of the client certificate. Example: \"CN=My CA\"</li> <li><code>ssl-client-subject-dn</code>: The subject information of the client certificate. Example: \"CN=My Client\"</li> <li><code>ssl-client-verify</code>: The result of the client verification. Possible values: \"SUCCESS\", \"FAILED: \" <li><code>ssl-client-cert</code>: The full client certificate in PEM format. Will only be sent when <code>nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream</code> is set to \"true\". Example: <code>-----BEGIN%20CERTIFICATE-----%0A...---END%20CERTIFICATE-----%0A</code></li> <p>Example</p> <p>Please check the client-certs example.</p> <p>Attention</p> <p>TLS with Client Authentication is not possible in Cloudflare and might result in unexpected behavior.</p> <p>Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/</p> <p>Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls</p>"},{"location":"user-guide/nginx-configuration/annotations/#backend-certificate-authentication","title":"Backend Certificate Authentication","text":"<p>It is possible to authenticate to a proxied HTTPS backend with certificate using additional annotations in Ingress Rule.</p> <ul> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-secret: secretName</code>:   Specifies a Secret with the certificate <code>tls.crt</code>, key <code>tls.key</code> in PEM format used for authentication to a proxied HTTPS server. It should also contain trusted CA certificates <code>ca.crt</code> in PEM format used to verify the certificate of the proxied HTTPS server.   This annotation expects the Secret name in the form \"namespace/secretName\".</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-verify</code>:   Enables or disables verification of the proxied HTTPS server certificate. (default: off)</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-verify-depth</code>:   Sets the verification depth in the proxied HTTPS server certificates chain. (default: 1)</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-ciphers</code>:   Specifies the enabled ciphers for requests to a proxied HTTPS server. The ciphers are specified in the format understood by the OpenSSL library.</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-name</code>:   Allows to set proxy_ssl_name. This allows overriding the server name used to verify the certificate of the proxied HTTPS server. This value is also passed through SNI when a connection is established to the proxied HTTPS server.</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-protocols</code>:   Enables the specified protocols for requests to a proxied HTTPS server.</li> <li><code>nginx.ingress.kubernetes.io/proxy-ssl-server-name</code>:   Enables passing of the server name through TLS Server Name Indication extension (SNI, RFC 6066) when establishing a connection with the proxied HTTPS server.</li> </ul>"},{"location":"user-guide/nginx-configuration/annotations/#configuration-snippet","title":"Configuration snippet","text":"<p>Using this annotation you can add additional configuration to the NGINX location. For example:</p> <pre><code>nginx.ingress.kubernetes.io/configuration-snippet: |\n  more_set_headers \"Request-Id: $req_id\";\n</code></pre> <p>Be aware this can be dangerous in multi-tenant clusters, as it can lead to people with otherwise limited permissions being able to retrieve all secrets on the cluster. The recommended mitigation for this threat is to disable this feature, so it may not work for you. See CVE-2021-25742 and the related issue on github for more information.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-http-errors","title":"Custom HTTP Errors","text":"<p>Like the <code>custom-http-errors</code> value in the ConfigMap, this annotation will set NGINX <code>proxy-intercept-errors</code>, but only for the NGINX location associated with this ingress. If a default backend annotation is specified on the ingress, the errors will be routed to that annotation's default backend service (instead of the global default backend). Different ingresses can specify different sets of error codes. Even if multiple ingress objects share the same hostname, this annotation can be used to intercept different error codes for each ingress (for example, different error codes to be intercepted for different paths on the same hostname, if each path is on a different ingress). If <code>custom-http-errors</code> is also specified globally, the error values specified in this annotation will override the global value for the given ingress' hostname and path.</p> <p>Example usage: <pre><code>nginx.ingress.kubernetes.io/custom-http-errors: \"404,415\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-headers","title":"Custom Headers","text":"<p>This annotation is of the form <code>nginx.ingress.kubernetes.io/custom-headers: custom-headers-configmap</code> to specify a configmap name that contains custom headers. This annotation uses <code>more_set_headers</code> nginx directive.</p> <p>Example configmap: <pre><code>apiVersion: v1\ndata:\n  Content-Type: application/json\nkind: ConfigMap\nmetadata:\n  name: custom-headers-configmap\n</code></pre></p> <p>Attention</p> <p>First define the allowed response headers in global-allowed-response-headers.</p>"},{"location":"user-guide/nginx-configuration/annotations/#default-backend","title":"Default Backend","text":"<p>This annotation is of the form <code>nginx.ingress.kubernetes.io/default-backend: &lt;svc name&gt;</code> to specify a custom default backend.  This <code>&lt;svc name&gt;</code> is a reference to a service inside of the same namespace in which you are applying this annotation. This annotation overrides the global default backend. In case the service has multiple ports, the first one is the one which will receive the backend traffic. </p> <p>This service will be used to handle the response when the configured service in the Ingress rule does not have any active endpoints. It will also be used to handle the error responses if both this annotation and the custom-http-errors annotation are set.</p>"},{"location":"user-guide/nginx-configuration/annotations/#enable-cors","title":"Enable CORS","text":"<p>To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule, add the annotation <code>nginx.ingress.kubernetes.io/enable-cors: \"true\"</code>. This will add a section in the server location enabling this functionality.</p> <p>CORS can be controlled with the following annotations:</p> <ul> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-methods</code>: Controls which methods are accepted.</p> <p>This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).</p> <ul> <li>Default: <code>GET, PUT, POST, DELETE, PATCH, OPTIONS</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-headers</code>: Controls which headers are accepted.</p> <p>This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.</p> <ul> <li>Default: <code>DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-expose-headers</code>: Controls which headers are exposed to response.</p> <p>This is a multi-valued field, separated by ',' and accepts letters, numbers, _, - and *.</p> <ul> <li>Default: empty</li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-expose-headers: \"*, X-CustomResponseHeader\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-origin</code>: Controls what's the accepted Origin for CORS.</p> <p>This is a multi-valued field, separated by ','. It must follow this format: <code>http(s)://origin-site.com</code> or <code>http(s)://origin-site.com:port</code></p> <ul> <li>Default: <code>*</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443, http://origin-site.com, https://example.org:1199\"</code></li> </ul> <p>It also supports single level wildcard subdomains and follows this format: <code>http(s)://*.foo.bar</code>, <code>http(s)://*.bar.foo:8080</code> or <code>http(s)://*.abc.bar.foo:9000</code> - Example: <code>nginx.ingress.kubernetes.io/cors-allow-origin: \"https://*.origin-site.com:4443, http://*.origin-site.com, https://example.org:1199\"</code></p> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-allow-credentials</code>: Controls if credentials can be passed during CORS operations.</p> <ul> <li>Default: <code>true</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-allow-credentials: \"false\"</code></li> </ul> </li> <li> <p><code>nginx.ingress.kubernetes.io/cors-max-age</code>: Controls how long preflight requests can be cached.</p> <ul> <li>Default: <code>1728000</code></li> <li>Example: <code>nginx.ingress.kubernetes.io/cors-max-age: 600</code></li> </ul> </li> </ul> <p>Note</p> <p>For more information please see https://enable-cors.org</p>"},{"location":"user-guide/nginx-configuration/annotations/#http2-push-preload","title":"HTTP2 Push Preload.","text":"<p>Enables automatic conversion of preload links specified in the \u201cLink\u201d response header fields into push requests.</p> <p>Example</p> <ul> <li><code>nginx.ingress.kubernetes.io/http2-push-preload: \"true\"</code></li> </ul>"},{"location":"user-guide/nginx-configuration/annotations/#server-alias","title":"Server Alias","text":"<p>Allows the definition of one or more aliases in the server definition of the NGINX configuration using the annotation <code>nginx.ingress.kubernetes.io/server-alias: \"&lt;alias 1&gt;,&lt;alias 2&gt;\"</code>. This will create a server with the same configuration, but adding new values to the <code>server_name</code> directive.</p> <p>Note</p> <p>A server-alias name cannot conflict with the hostname of an existing server. If it does, the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created, the new server configuration will take place over the alias configuration.</p> <p>For more information please see the <code>server_name</code> documentation.</p>"},{"location":"user-guide/nginx-configuration/annotations/#server-snippet","title":"Server snippet","text":"<p>Using the annotation <code>nginx.ingress.kubernetes.io/server-snippet</code> it is possible to add custom configuration in the server configuration block.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/server-snippet: |\n        set $agentflag 0;\n\n        if ($http_user_agent ~* \"(Mobile)\" ){\n          set $agentflag 1;\n        }\n\n        if ( $agentflag = 1 ) {\n          return 301 https://m.example.com;\n        }\n</code></pre> <p>Attention</p> <p>This annotation can be used only once per host.</p>"},{"location":"user-guide/nginx-configuration/annotations/#client-body-buffer-size","title":"Client Body Buffer Size","text":"<p>Sets buffer size for reading client request body per location. In case the request body is larger than the buffer, the whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages. This is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is applied to each location provided in the ingress rule.</p> <p>Note</p> <p>The annotation value must be given in a format understood by Nginx.</p> <p>Example</p> <ul> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\"</code> # 1000 bytes</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1k</code> # 1 kilobyte</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1K</code> # 1 kilobyte</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1m</code> # 1 megabyte</li> <li><code>nginx.ingress.kubernetes.io/client-body-buffer-size: 1M</code> # 1 megabyte</li> </ul> <p>For more information please see https://nginx.org</p>"},{"location":"user-guide/nginx-configuration/annotations/#external-authentication","title":"External Authentication","text":"<p>To use an existing service that provides authentication the Ingress rule can be annotated with <code>nginx.ingress.kubernetes.io/auth-url</code> to indicate the URL where the HTTP request should be sent.</p> <pre><code>nginx.ingress.kubernetes.io/auth-url: \"URL to the authentication service\"\n</code></pre> <p>Additionally it is possible to set:</p> <ul> <li><code>nginx.ingress.kubernetes.io/auth-keepalive</code>:   <code>&lt;Connections&gt;</code> to specify the maximum number of keepalive connections to <code>auth-url</code>. Only takes effect    when no variables are used in the host part of the URL. Defaults to <code>0</code> (keepalive disabled).</li> </ul> <p>Note: does not work with HTTP/2 listener because of a limitation in Lua subrequests. UseHTTP2 configuration should be disabled!</p> <ul> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-share-vars</code>:   Whether to share Nginx variables among the current request and the auth request. Example use case is to track requests: when set to \"true\" X-Request-ID HTTP header will be the same for the backend and the auth request.   Defaults to \"false\".</li> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-requests</code>:   <code>&lt;Requests&gt;</code> to specify the maximum number of requests that can be served through one keepalive connection.   Defaults to <code>1000</code> and only applied if <code>auth-keepalive</code> is set to higher than <code>0</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-timeout</code>:   <code>&lt;Timeout&gt;</code> to specify a duration in seconds which an idle keepalive connection to an upstream server will stay open.   Defaults to <code>60</code> and only applied if <code>auth-keepalive</code> is set to higher than <code>0</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-method</code>:   <code>&lt;Method&gt;</code> to specify the HTTP method to use.</li> <li><code>nginx.ingress.kubernetes.io/auth-signin</code>:   <code>&lt;SignIn_URL&gt;</code> to specify the location of the error page.</li> <li><code>nginx.ingress.kubernetes.io/auth-signin-redirect-param</code>:   <code>&lt;SignIn_URL&gt;</code> to specify the URL parameter in the error page which should contain the original URL for a failed signin request.</li> <li><code>nginx.ingress.kubernetes.io/auth-response-headers</code>:   <code>&lt;Response_Header_1, ..., Response_Header_n&gt;</code> to specify headers to pass to backend once authentication request completes.</li> <li><code>nginx.ingress.kubernetes.io/auth-proxy-set-headers</code>:   <code>&lt;ConfigMap&gt;</code> the name of a ConfigMap that specifies headers to pass to the authentication service</li> <li><code>nginx.ingress.kubernetes.io/auth-request-redirect</code>:   <code>&lt;Request_Redirect_URL&gt;</code>  to specify the X-Auth-Request-Redirect header value.</li> <li><code>nginx.ingress.kubernetes.io/auth-cache-key</code>:   <code>&lt;Cache_Key&gt;</code> this enables caching for auth requests. specify a lookup key for auth responses. e.g. <code>$remote_user$http_authorization</code>. Each server and location has it's own keyspace. Hence a cached response is only valid on a per-server and per-location basis.</li> <li><code>nginx.ingress.kubernetes.io/auth-cache-duration</code>:   <code>&lt;Cache_duration&gt;</code> to specify a caching time for auth responses based on their response codes, e.g. <code>200 202 30m</code>. See proxy_cache_valid for details. You may specify multiple, comma-separated values: <code>200 202 10m, 401 5m</code>. defaults to <code>200 202 401 5m</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-always-set-cookie</code>:   <code>&lt;Boolean_Flag&gt;</code> to set a cookie returned by auth request. By default, the cookie will be set only if an upstream reports with the code 200, 201, 204, 206, 301, 302, 303, 304, 307, or 308.</li> <li><code>nginx.ingress.kubernetes.io/auth-snippet</code>:   <code>&lt;Auth_Snippet&gt;</code> to specify a custom snippet to use with external authentication, e.g.</li> </ul> <pre><code>nginx.ingress.kubernetes.io/auth-url: http://foo.com/external-auth\nnginx.ingress.kubernetes.io/auth-snippet: |\n    proxy_set_header Foo-Header 42;\n</code></pre> <p>Note: <code>nginx.ingress.kubernetes.io/auth-snippet</code> is an optional annotation. However, it may only be used in conjunction with <code>nginx.ingress.kubernetes.io/auth-url</code> and will be ignored if <code>nginx.ingress.kubernetes.io/auth-url</code> is not set</p> <p>Example</p> <p>Please check the external-auth example.</p>"},{"location":"user-guide/nginx-configuration/annotations/#global-external-authentication","title":"Global External Authentication","text":"<p>By default the controller redirects all requests to an existing service that provides authentication if <code>global-auth-url</code> is set in the NGINX ConfigMap. If you want to disable this behavior for that ingress, you can use <code>enable-global-auth: \"false\"</code> in the NGINX ConfigMap. <code>nginx.ingress.kubernetes.io/enable-global-auth</code>:    indicates if GlobalExternalAuth configuration should be applied or not to this Ingress rule. Default values is set to <code>\"true\"</code>.</p> <p>Note</p> <p>For more information please see global-auth-url.</p>"},{"location":"user-guide/nginx-configuration/annotations/#rate-limiting","title":"Rate Limiting","text":"<p>These annotations define limits on connections and transmission rates.  These can be used to mitigate DDoS Attacks.</p> <ul> <li><code>nginx.ingress.kubernetes.io/limit-connections</code>: number of concurrent connections allowed from a single IP address. A 503 error is returned when exceeding this limit.</li> <li><code>nginx.ingress.kubernetes.io/limit-rps</code>: number of requests accepted from a given IP each second. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit,  limit-req-status-code default: 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rpm</code>: number of requests accepted from a given IP each minute. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit,  limit-req-status-code default: 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-burst-multiplier</code>: multiplier of the limit rate for burst size. The default burst multiplier is 5, this annotation override the default multiplier. When clients exceed this limit,  limit-req-status-code default: 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate-after</code>: initial number of kilobytes after which the further transmission of a response to a given connection will be rate limited. This feature must be used with proxy-buffering enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate</code>: number of kilobytes per second allowed to send to a given connection.  The zero value disables rate limiting. This feature must be used with proxy-buffering enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-whitelist</code>: client IP source ranges to be excluded from rate-limiting. The value is a comma separated list of CIDRs.</li> </ul> <p>If you specify multiple annotations in a single Ingress rule, limits are applied in the order <code>limit-connections</code>, <code>limit-rpm</code>, <code>limit-rps</code>.</p> <p>To configure settings globally for all Ingress rules, the <code>limit-rate-after</code> and <code>limit-rate</code> values may be set in the NGINX ConfigMap.  The value set in an Ingress annotation will override the global setting.</p> <p>The client IP address will be set based on the use of PROXY protocol or from the <code>X-Forwarded-For</code> header value when use-forwarded-headers is enabled.</p>"},{"location":"user-guide/nginx-configuration/annotations/#global-rate-limiting","title":"Global Rate Limiting","text":"<p>Note: Be careful when configuring both (Local) Rate Limiting and Global Rate Limiting at the same time. They are two completely different rate limiting implementations. Whichever limit exceeds first will reject the requests. It might be a good idea to configure both of them to ease load on Global Rate Limiting backend in cases of spike in traffic.</p> <p>The stock NGINX rate limiting does not share its counters among different NGINX instances. Given that most ingress-nginx deployments are elastic and number of replicas can change any day it is impossible to configure a proper rate limit using stock NGINX functionalities. Global Rate Limiting overcome this by using lua-resty-global-throttle. <code>lua-resty-global-throttle</code> shares its counters via a central store such as <code>memcached</code>. The obvious shortcoming of this is users have to deploy and operate a <code>memcached</code> instance in order to benefit from this functionality. Configure the <code>memcached</code> using these configmap settings.</p> <p>Here are a few remarks for ingress-nginx integration of <code>lua-resty-global-throttle</code>:</p> <ol> <li>We minimize <code>memcached</code> access by caching exceeding limit decisions. The expiry of cache entry is the desired delay <code>lua-resty-global-throttle</code> calculates for us. The Lua Shared Dictionary used for that is <code>global_throttle_cache</code>. Currently its size defaults to 10M. Customize it as per your needs using lua-shared-dicts. When we fail to cache the exceeding limit decision then we log an NGINX error. You can monitor for that error to decide if you need to bump the cache size. Without cache the cost of processing a request is two memcached commands: <code>GET</code>, and <code>INCR</code>. With the cache it is only <code>INCR</code>.</li> <li>Log NGINX variable <code>$global_rate_limit_exceeding</code>'s value to have some visibility into what portion of requests are rejected (value <code>y</code>), whether they are rejected using cached decision (value <code>c</code>), or if they are not rejected (default value <code>n</code>). You can use log-format-upstream to include that in access logs.</li> <li>In case of an error it will log the error message and fail open.</li> <li> <p>The annotations below creates Global Rate Limiting instance per ingress. That means if there are multiple paths configured under the same ingress, the Global Rate Limiting will count requests to all the paths under the same counter. Extract a path out into its own ingress if you need to isolate a certain path.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/global-rate-limit</code>: Configures maximum allowed number of requests per window. Required.</p> </li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-window</code>: Configures a time window (i.e <code>1m</code>) that the limit is applied. Required.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-key</code>: Configures a key for counting the samples. Defaults to <code>$remote_addr</code>. You can also combine multiple NGINX variables here, like <code>${remote_addr}-${http_x_api_client}</code> which would mean the limit will be applied to requests coming from the same API client (indicated by <code>X-API-Client</code> HTTP request header) with the same source IP address.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs</code>: comma separated list of IPs and CIDRs to match client IP against. When there's a match request is not considered for rate limiting.</li> </ol>"},{"location":"user-guide/nginx-configuration/annotations/#permanent-redirect","title":"Permanent Redirect","text":"<p>This annotation allows to return a permanent redirect (Return Code 301) instead of sending data to the upstream.  For example <code>nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com</code> would redirect everything to Google.</p>"},{"location":"user-guide/nginx-configuration/annotations/#permanent-redirect-code","title":"Permanent Redirect Code","text":"<p>This annotation allows you to modify the status code used for permanent redirects.  For example <code>nginx.ingress.kubernetes.io/permanent-redirect-code: '308'</code> would return your permanent-redirect with a 308.</p>"},{"location":"user-guide/nginx-configuration/annotations/#temporal-redirect","title":"Temporal Redirect","text":"<p>This annotation allows you to return a temporal redirect (Return Code 302) instead of sending data to the upstream. For example <code>nginx.ingress.kubernetes.io/temporal-redirect: https://www.google.com</code> would redirect everything to Google with a Return Code of 302 (Moved Temporarily)</p>"},{"location":"user-guide/nginx-configuration/annotations/#ssl-passthrough","title":"SSL Passthrough","text":"<p>The annotation <code>nginx.ingress.kubernetes.io/ssl-passthrough</code> instructs the controller to send TLS connections directly to the backend instead of letting NGINX decrypt the communication. See also TLS/HTTPS in the User guide.</p> <p>Note</p> <p>SSL Passthrough is disabled by default and requires starting the controller with the <code>--enable-ssl-passthrough</code> flag.</p> <p>Attention</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>"},{"location":"user-guide/nginx-configuration/annotations/#service-upstream","title":"Service Upstream","text":"<p>By default the Ingress-Nginx Controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.</p> <p>The <code>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> <p>This can be desirable for things like zero-downtime deployments . See issue #257.</p>"},{"location":"user-guide/nginx-configuration/annotations/#known-issues","title":"Known Issues","text":"<p>If the <code>service-upstream</code> annotation is specified the following things should be taken into consideration:</p> <ul> <li>Sticky Sessions will not work as only round-robin load balancing is supported.</li> <li>The <code>proxy_next_upstream</code> directive will not have any effect meaning on error the request will not be dispatched to another upstream.</li> </ul>"},{"location":"user-guide/nginx-configuration/annotations/#server-side-https-enforcement-through-redirect","title":"Server-side HTTPS enforcement through redirect","text":"<p>By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress. If you want to disable this behavior globally, you can use <code>ssl-redirect: \"false\"</code> in the NGINX ConfigMap.</p> <p>To configure this feature for specific ingress resources, you can use the <code>nginx.ingress.kubernetes.io/ssl-redirect: \"false\"</code> annotation in the particular resource.</p> <p>When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is no TLS certificate available. This can be achieved by using the <code>nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"</code> annotation in the particular resource.</p> <p>To preserve the trailing slash in the URI with <code>ssl-redirect</code>, set <code>nginx.ingress.kubernetes.io/preserve-trailing-slash: \"true\"</code> annotation for that particular resource.</p>"},{"location":"user-guide/nginx-configuration/annotations/#redirect-fromto-www","title":"Redirect from/to www","text":"<p>In some scenarios is required to redirect from <code>www.domain.com</code> to <code>domain.com</code> or vice versa. To enable this feature use the annotation <code>nginx.ingress.kubernetes.io/from-to-www-redirect: \"true\"</code></p> <p>Attention</p> <p>If at some point a new Ingress is created with a host equal to one of the options (like <code>domain.com</code>) the annotation will be omitted.</p> <p>Attention</p> <p>For HTTPS to HTTPS redirects is mandatory the SSL Certificate defined in the Secret, located in the TLS section of Ingress, contains both FQDN in the common name of the certificate.</p>"},{"location":"user-guide/nginx-configuration/annotations/#denylist-source-range","title":"Denylist source range","text":"<p>You can specify blocked client IP source ranges through the <code>nginx.ingress.kubernetes.io/denylist-source-range</code> annotation. The value is a comma separated list of CIDRs, e.g.  <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>denylist-source-range</code> value may be set in the NGINX ConfigMap.</p> <p>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p>"},{"location":"user-guide/nginx-configuration/annotations/#whitelist-source-range","title":"Whitelist source range","text":"<p>You can specify allowed client IP source ranges through the <code>nginx.ingress.kubernetes.io/whitelist-source-range</code> annotation. The value is a comma separated list of CIDRs, e.g.  <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>whitelist-source-range</code> value may be set in the NGINX ConfigMap.</p> <p>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-timeouts","title":"Custom timeouts","text":"<p>Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers. In some scenarios is required to have different values. To allow this we provide annotations that allows this customization:</p> <ul> <li><code>nginx.ingress.kubernetes.io/proxy-connect-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-send-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-read-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-tries</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-request-buffering</code></li> </ul> <p>If you indicate Backend Protocol as <code>GRPC</code> or <code>GRPCS</code>, the following grpc values will be set and inherited from proxy timeouts:</p> <ul> <li><code>grpc_connect_timeout=5s</code>, from <code>nginx.ingress.kubernetes.io/proxy-connect-timeout</code></li> <li><code>grpc_send_timeout=60s</code>, from <code>nginx.ingress.kubernetes.io/proxy-send-timeout</code></li> <li><code>grpc_read_timeout=60s</code>, from <code>nginx.ingress.kubernetes.io/proxy-read-timeout</code></li> </ul> <p>Note: All timeout values are unitless and in seconds e.g. <code>nginx.ingress.kubernetes.io/proxy-read-timeout: \"120\"</code> sets a valid 120 seconds proxy read timeout.</p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-redirect","title":"Proxy redirect","text":"<p>The annotations <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> and <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code> will set the first and second parameters of NGINX's proxy_redirect directive respectively. It is possible to set the text that should be changed in the <code>Location</code> and <code>Refresh</code> header fields of a proxied server response</p> <p>Setting \"off\" or \"default\" in the annotation <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> disables <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code>, otherwise, both annotations must be used in unison. Note that each annotation must be a string without spaces.</p> <p>By default the value of each annotation is \"off\".</p>"},{"location":"user-guide/nginx-configuration/annotations/#custom-max-body-size","title":"Custom max body size","text":"<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 <code>client_max_body_size</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-body-size</code> value may be set in the NGINX ConfigMap. To use custom values in an Ingress rule define these annotation:</p> <pre><code>nginx.ingress.kubernetes.io/proxy-body-size: 8m\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-cookie-domain","title":"Proxy cookie domain","text":"<p>Sets a text that should be changed in the domain attribute of the \"Set-Cookie\" header fields of a proxied server response.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-cookie-domain</code> value may be set in the NGINX ConfigMap.</p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-cookie-path","title":"Proxy cookie path","text":"<p>Sets a text that should be changed in the path attribute of the \"Set-Cookie\" header fields of a proxied server response.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-cookie-path</code> value may be set in the NGINX ConfigMap.</p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-buffering","title":"Proxy buffering","text":"<p>Enable or disable proxy buffering <code>proxy_buffering</code>. By default proxy buffering is disabled in the NGINX config.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-buffering</code> value may be set in the NGINX ConfigMap. To use custom values in an Ingress rule define these annotation:</p> <pre><code>nginx.ingress.kubernetes.io/proxy-buffering: \"on\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-buffers-number","title":"Proxy buffers Number","text":"<p>Sets the number of the buffers in <code>proxy_buffers</code> used for reading the first part of the response received from the proxied server. By default proxy buffers number is set as 4</p> <p>To configure this setting globally, set <code>proxy-buffers-number</code> in NGINX ConfigMap. To use custom values in an Ingress rule, define this annotation: <pre><code>nginx.ingress.kubernetes.io/proxy-buffers-number: \"4\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-buffer-size","title":"Proxy buffer size","text":"<p>Sets the size of the buffer <code>proxy_buffer_size</code> 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>proxy-buffer-size</code> in NGINX ConfigMap. To use custom values in an Ingress rule, define this annotation: <pre><code>nginx.ingress.kubernetes.io/proxy-buffer-size: \"8k\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-max-temp-file-size","title":"Proxy max temp file size","text":"<p>When <code>buffering</code> of responses from the proxied server is enabled, and the whole response does not fit into the buffers set by the <code>proxy_buffer_size</code> and <code>proxy_buffers</code> directives, a part of the response can be saved to a temporary file. This directive sets the maximum <code>size</code> of the temporary file setting the <code>proxy_max_temp_file_size</code>. The size of data written to the temporary file at a time is set by the <code>proxy_temp_file_write_size</code> directive.</p> <p>The zero value disables buffering of responses to temporary files.</p> <p>To use custom values in an Ingress rule, define this annotation: <pre><code>nginx.ingress.kubernetes.io/proxy-max-temp-file-size: \"1024m\"\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#proxy-http-version","title":"Proxy HTTP version","text":"<p>Using this annotation sets the <code>proxy_http_version</code> that the Nginx reverse proxy will use to communicate with the backend. By default this is set to \"1.1\".</p> <pre><code>nginx.ingress.kubernetes.io/proxy-http-version: \"1.0\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#ssl-ciphers","title":"SSL ciphers","text":"<p>Specifies the enabled ciphers.</p> <p>Using this annotation will set the <code>ssl_ciphers</code> directive at the server level. This configuration is active for all the paths in the host.</p> <pre><code>nginx.ingress.kubernetes.io/ssl-ciphers: \"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP\"\n</code></pre> <p>The following annotation will set the <code>ssl_prefer_server_ciphers</code> directive at the server level. This configuration specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols.</p> <pre><code>nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#connection-proxy-header","title":"Connection proxy header","text":"<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> <pre><code>nginx.ingress.kubernetes.io/connection-proxy-header: \"keep-alive\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#enable-access-log","title":"Enable Access Log","text":"<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> <pre><code>nginx.ingress.kubernetes.io/enable-access-log: \"false\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#enable-rewrite-log","title":"Enable Rewrite Log","text":"<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> <pre><code>nginx.ingress.kubernetes.io/enable-rewrite-log: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#enable-opentelemetry","title":"Enable Opentelemetry","text":"<p>Opentelemetry can be enabled or disabled globally through the ConfigMap but this will sometimes need to be overridden to enable it or disable it for a specific ingress (e.g. to turn off telemetry of external health check endpoints)</p> <pre><code>nginx.ingress.kubernetes.io/enable-opentelemetry: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#opentelemetry-trust-incoming-span","title":"Opentelemetry Trust Incoming Span","text":"<p>The option to trust incoming trace spans can be enabled or disabled globally through the ConfigMap but this will sometimes need to be overridden to enable it or disable it for a specific ingress (e.g. only enable on a private endpoint)</p> <pre><code>nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-spans: \"true\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#x-forwarded-prefix-header","title":"X-Forwarded-Prefix Header","text":"<p>To add the non-standard <code>X-Forwarded-Prefix</code> header to the upstream request with a string value, the following annotation can be used:</p> <pre><code>nginx.ingress.kubernetes.io/x-forwarded-prefix: \"/path\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#modsecurity","title":"ModSecurity","text":"<p>ModSecurity is an OpenSource Web Application firewall. It can be enabled for a particular set of ingress locations. The ModSecurity module must first be enabled by enabling ModSecurity in the ConfigMap. Note this will enable ModSecurity for all paths, and each path must be disabled manually.</p> <p>It can be enabled using the following annotation: <pre><code>nginx.ingress.kubernetes.io/enable-modsecurity: \"true\"\n</code></pre> ModSecurity will run in \"Detection-Only\" mode using the recommended configuration.</p> <p>You can enable the OWASP Core Rule Set by setting the following annotation: <pre><code>nginx.ingress.kubernetes.io/enable-owasp-core-rules: \"true\"\n</code></pre></p> <p>You can pass transactionIDs from nginx by setting up the following: <pre><code>nginx.ingress.kubernetes.io/modsecurity-transaction-id: \"$request_id\"\n</code></pre></p> <p>You can also add your own set of modsecurity rules via a snippet: <pre><code>nginx.ingress.kubernetes.io/modsecurity-snippet: |\nSecRuleEngine On\nSecDebugLog /tmp/modsec_debug.log\n</code></pre></p> <p>Note: If you use both <code>enable-owasp-core-rules</code> and <code>modsecurity-snippet</code> annotations together, only the <code>modsecurity-snippet</code> will take effect. If you wish to include the OWASP Core Rule Set or recommended configuration simply use the include statement:</p> <p>nginx 0.24.1 and below <pre><code>nginx.ingress.kubernetes.io/modsecurity-snippet: |\nInclude /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf\nInclude /etc/nginx/modsecurity/modsecurity.conf\n</code></pre> nginx 0.25.0 and above <pre><code>nginx.ingress.kubernetes.io/modsecurity-snippet: |\nInclude /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf\n</code></pre></p>"},{"location":"user-guide/nginx-configuration/annotations/#backend-protocol","title":"Backend Protocol","text":"<p>Using <code>backend-protocol</code> annotations is possible to indicate how NGINX should communicate with the backend service. (Replaces <code>secure-backends</code> in older versions) Valid Values: HTTP, HTTPS, AUTO_HTTP, GRPC, GRPCS and FCGI</p> <p>By default NGINX uses <code>HTTP</code>.</p> <p>Example:</p> <pre><code>nginx.ingress.kubernetes.io/backend-protocol: \"HTTPS\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#use-regex","title":"Use Regex","text":"<p>Attention</p> <p>When using this annotation with the NGINX annotation <code>nginx.ingress.kubernetes.io/affinity</code> of type <code>cookie</code>,  <code>nginx.ingress.kubernetes.io/session-cookie-path</code> must be also set; Session cookie paths do not support regex.</p> <p>Using the <code>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>false</code>.</p> <p>The following will indicate that regular expression paths are being used: <pre><code>nginx.ingress.kubernetes.io/use-regex: \"true\"\n</code></pre></p> <p>The following will indicate that regular expression paths are not being used: <pre><code>nginx.ingress.kubernetes.io/use-regex: \"false\"\n</code></pre></p> <p>When this annotation is set to <code>true</code>, the case insensitive regular expression location modifier will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p> <p>Additionally, if the <code>rewrite-target</code> annotation is used on any Ingress for a given host, then the case insensitive regular expression location modifier will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p> <p>Please read about ingress path matching before using this modifier.</p>"},{"location":"user-guide/nginx-configuration/annotations/#satisfy","title":"Satisfy","text":"<p>By default, a request would need to satisfy all authentication requirements in order to be allowed. By using this annotation, requests that satisfy either any or all authentication requirements are allowed, based on the configuration value.</p> <pre><code>nginx.ingress.kubernetes.io/satisfy: \"any\"\n</code></pre>"},{"location":"user-guide/nginx-configuration/annotations/#mirror","title":"Mirror","text":"<p>Enables a request to be mirrored to a mirror backend. Responses by mirror backends are ignored. This feature is useful, to see how requests will react in \"test\" backends.</p> <p>The mirror backend can be set by applying:</p> <pre><code>nginx.ingress.kubernetes.io/mirror-target: https://test.env.com/$request_uri\n</code></pre> <p>By default the request-body is sent to the mirror backend, but can be turned off by applying:</p> <pre><code>nginx.ingress.kubernetes.io/mirror-request-body: \"off\"\n</code></pre> <p>Also by default header Host for mirrored requests will be set the same as a host part of uri in the \"mirror-target\" annotation. You can override it by \"mirror-host\" annotation:</p> <pre><code>nginx.ingress.kubernetes.io/mirror-target: https://1.2.3.4/$request_uri\nnginx.ingress.kubernetes.io/mirror-host: \"test.env.com\"\n</code></pre> <p>Note: The mirror directive will be applied to all paths within the ingress resource.</p> <p>The request sent to the mirror is linked to the original request. If you have a slow mirror backend, then the original request will throttle.</p> <p>For more information on the mirror module see ngx_http_mirror_module</p>"},{"location":"user-guide/nginx-configuration/annotations/#stream-snippet","title":"Stream snippet","text":"<p>Using the annotation <code>nginx.ingress.kubernetes.io/stream-snippet</code> it is possible to add custom stream configuration.</p> <pre><code>apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/stream-snippet: |\n      server {\n        listen 8000;\n        proxy_pass 127.0.0.1:80;\n      }\n</code></pre>"},{"location":"user-guide/nginx-configuration/configmap/","title":"ConfigMaps","text":"<p>ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable.</p> <p>The ConfigMap API resource stores configuration data as key-value pairs. The data provides the configurations for system components for the nginx-controller.</p> <p>In order to overwrite nginx-controller configuration values as seen in config.go, you can add key-value pairs to the data section of the config-map. For Example:</p> <pre><code>data:\n  map-hash-bucket-size: \"128\"\n  ssl-protocols: SSLv2\n</code></pre> <p>Important</p> <p>The key and values in a ConfigMap can only be strings. This means that we want a value with boolean values we need to quote the values, like \"true\" or \"false\". Same for numbers, like \"100\".</p> <p>\"Slice\" types (defined below as <code>[]string</code> or <code>[]int</code>) can be provided as a comma-delimited string.</p>"},{"location":"user-guide/nginx-configuration/configmap/#configuration-options","title":"Configuration options","text":"<p>The following table shows a configuration option's name, type, and the default value:</p> name type default notes add-headers string \"\" allow-backend-server-header bool \"false\" allow-cross-namespace-resources bool \"true\" allow-snippet-annotations bool false annotations-risk-level string Critical annotation-value-word-blocklist string array \"\" hide-headers string array empty access-log-params string \"\" access-log-path string \"/var/log/nginx/access.log\" http-access-log-path string \"\" stream-access-log-path string \"\" enable-access-log-for-default-backend bool \"false\" error-log-path string \"/var/log/nginx/error.log\" enable-modsecurity bool \"false\" modsecurity-snippet string \"\" enable-owasp-modsecurity-crs bool \"false\" client-header-buffer-size string \"1k\" client-header-timeout int 60 client-body-buffer-size string \"8k\" client-body-timeout int 60 disable-access-log bool false disable-ipv6 bool false disable-ipv6-dns bool false enable-underscores-in-headers bool false enable-ocsp bool false ignore-invalid-headers bool true retry-non-idempotent bool \"false\" error-log-level string \"notice\" http2-max-field-size string \"\" DEPRECATED in favour of large_client_header_buffers http2-max-header-size string \"\" DEPRECATED in favour of large_client_header_buffers http2-max-requests int 0 DEPRECATED in favour of keepalive_requests http2-max-concurrent-streams int 128 hsts bool \"true\" hsts-include-subdomains bool \"true\" hsts-max-age string \"31536000\" hsts-preload bool \"false\" keep-alive int 75 keep-alive-requests int 1000 large-client-header-buffers string \"4 8k\" log-format-escape-none bool \"false\" log-format-escape-json bool \"false\" log-format-upstream string <code>$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id</code> log-format-stream string <code>[$remote_addr] [$time_local] $protocol $status $bytes_sent $bytes_received $session_time</code> enable-multi-accept bool \"true\" max-worker-connections int 16384 max-worker-open-files int 0 map-hash-bucket-size int 64 nginx-status-ipv4-whitelist []string \"127.0.0.1\" nginx-status-ipv6-whitelist []string \"::1\" proxy-real-ip-cidr []string \"0.0.0.0/0\" proxy-set-headers string \"\" server-name-hash-max-size int 1024 server-name-hash-bucket-size int <code>&lt;size of the processor\u2019s cache line&gt;</code> proxy-headers-hash-max-size int 512 proxy-headers-hash-bucket-size int 64 plugins []string reuse-port bool \"true\" server-tokens bool \"false\" ssl-ciphers string \"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384\" ssl-ecdh-curve string \"auto\" ssl-dh-param string \"\" ssl-protocols string \"TLSv1.2 TLSv1.3\" ssl-session-cache bool \"true\" ssl-session-cache-size string \"10m\" ssl-session-tickets bool \"false\" ssl-session-ticket-key string <code>&lt;Randomly Generated&gt;</code> ssl-session-timeout string \"10m\" ssl-buffer-size string \"4k\" use-proxy-protocol bool \"false\" proxy-protocol-header-timeout string \"5s\" enable-aio-write bool \"true\" use-gzip bool \"false\" use-geoip bool \"true\" use-geoip2 bool \"false\" geoip2-autoreload-in-minutes int \"0\" enable-brotli bool \"false\" brotli-level int 4 brotli-min-length int 20 brotli-types string \"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component\" use-http2 bool \"true\" gzip-disable string \"\" gzip-level int 1 gzip-min-length int 256 gzip-types string \"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-component\" worker-processes string <code>&lt;Number of CPUs&gt;</code> worker-cpu-affinity string \"\" worker-shutdown-timeout string \"240s\" enable-serial-reloads bool \"false\" load-balance string \"round_robin\" variables-hash-bucket-size int 128 variables-hash-max-size int 2048 upstream-keepalive-connections int 320 upstream-keepalive-time string \"1h\" upstream-keepalive-timeout int 60 upstream-keepalive-requests int 10000 limit-conn-zone-variable string \"$binary_remote_addr\" proxy-stream-timeout string \"600s\" proxy-stream-next-upstream bool \"true\" proxy-stream-next-upstream-timeout string \"600s\" proxy-stream-next-upstream-tries int 3 proxy-stream-responses int 1 bind-address []string \"\" use-forwarded-headers bool \"false\" enable-real-ip bool \"false\" forwarded-for-header string \"X-Forwarded-For\" compute-full-forwarded-for bool \"false\" proxy-add-original-uri-header bool \"false\" generate-request-id bool \"true\" jaeger-collector-host string \"\" jaeger-collector-port int 6831 jaeger-endpoint string \"\" jaeger-service-name string \"nginx\" jaeger-propagation-format string \"jaeger\" jaeger-sampler-type string \"const\" jaeger-sampler-param string \"1\" jaeger-sampler-host string \"http://127.0.0.1\" jaeger-sampler-port int 5778 jaeger-trace-context-header-name string uber-trace-id jaeger-debug-header string uber-debug-id jaeger-baggage-header string jaeger-baggage jaeger-trace-baggage-header-prefix string uberctx- datadog-collector-host string \"\" datadog-collector-port int 8126 datadog-service-name string \"nginx\" datadog-environment string \"prod\" datadog-operation-name-override string \"nginx.handle\" datadog-priority-sampling bool \"true\" datadog-sample-rate float 1.0 enable-opentelemetry bool \"false\" opentelemetry-trust-incoming-span bool \"true\" opentelemetry-operation-name string \"\" opentelemetry-config string \"/etc/nginx/opentelemetry.toml\" otlp-collector-host string \"\" otlp-collector-port int 4317 otel-max-queuesize int otel-schedule-delay-millis int otel-max-export-batch-size int otel-service-name string \"nginx\" otel-sampler string \"AlwaysOff\" otel-sampler-parent-based bool \"false\" otel-sampler-ratio float 0.01 main-snippet string \"\" http-snippet string \"\" server-snippet string \"\" stream-snippet string \"\" location-snippet string \"\" custom-http-errors []int []int{} proxy-body-size string \"1m\" proxy-connect-timeout int 5 proxy-read-timeout int 60 proxy-send-timeout int 60 proxy-buffers-number int 4 proxy-buffer-size string \"4k\" proxy-cookie-path string \"off\" proxy-cookie-domain string \"off\" proxy-next-upstream string \"error timeout\" proxy-next-upstream-timeout int 0 proxy-next-upstream-tries int 3 proxy-redirect-from string \"off\" proxy-request-buffering string \"on\" ssl-redirect bool \"true\" force-ssl-redirect bool \"false\" denylist-source-range []string []string{} whitelist-source-range []string []string{} skip-access-log-urls []string []string{} limit-rate int 0 limit-rate-after int 0 lua-shared-dicts string \"\" http-redirect-code int 308 proxy-buffering string \"off\" limit-req-status-code int 503 limit-conn-status-code int 503 enable-syslog bool false syslog-host string \"\" syslog-port int 514 no-tls-redirect-locations string \"/.well-known/acme-challenge\" global-allowed-response-headers string \"\" global-auth-url string \"\" global-auth-method string \"\" global-auth-signin string \"\" global-auth-signin-redirect-param string \"rd\" global-auth-response-headers string \"\" global-auth-request-redirect string \"\" global-auth-snippet string \"\" global-auth-cache-key string \"\" global-auth-cache-duration string \"200 202 401 5m\" no-auth-locations string \"/.well-known/acme-challenge\" block-cidrs []string \"\" block-user-agents []string \"\" block-referers []string \"\" proxy-ssl-location-only bool \"false\" default-type string \"text/html\" global-rate-limit-memcached-host string \"\" global-rate-limit-memcached-port int 11211 global-rate-limit-memcached-connect-timeout int 50 global-rate-limit-memcached-max-idle-timeout int 10000 global-rate-limit-memcached-pool-size int 50 global-rate-limit-status-code int 429 service-upstream bool \"false\" ssl-reject-handshake bool \"false\" debug-connections []string \"127.0.0.1,1.1.1.1/24\" strict-validate-path-type bool \"false\" (v1.7.x) grpc-buffer-size-kb int 0"},{"location":"user-guide/nginx-configuration/configmap/#add-headers","title":"add-headers","text":"<p>Sets custom headers from named configmap before sending traffic to the client. See proxy-set-headers. example</p>"},{"location":"user-guide/nginx-configuration/configmap/#allow-backend-server-header","title":"allow-backend-server-header","text":"<p>Enables the return of the header Server from the backend instead of the generic nginx string. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#allow-cross-namespace-resources","title":"allow-cross-namespace-resources","text":"<p>Enables users to consume cross namespace resource on annotations, when was previously enabled . default: true</p> <p>Annotations that may be impacted with this change: * <code>auth-secret</code> * <code>auth-proxy-set-header</code> * <code>auth-tls-secret</code> * <code>fastcgi-params-configmap</code> * <code>proxy-ssl-secret</code></p> <p>This option will be defaulted to false in the next major release</p>"},{"location":"user-guide/nginx-configuration/configmap/#allow-snippet-annotations","title":"allow-snippet-annotations","text":"<p>Enables Ingress to parse and add -snippet annotations/directives created by the user. _**default:*_ <code>false</code></p> <p>Warning: We recommend enabling this option only if you TRUST users with permission to create Ingress objects, as this may allow a user to add restricted configurations to the final nginx.conf file</p> <p>This option will be defaulted to false in the next major release</p>"},{"location":"user-guide/nginx-configuration/configmap/#annotations-risk-level","title":"annotations-risk-level","text":"<p>Represents the risk accepted on an annotation. If the risk is, for instance <code>Medium</code>, annotations with risk High and Critical will not be accepted.</p> <p>Accepted values are <code>Critical</code>, <code>High</code>, <code>Medium</code> and <code>Low</code>.</p> <p>Defaults to <code>Critical</code> but will be changed to <code>High</code> on the next minor release</p>"},{"location":"user-guide/nginx-configuration/configmap/#annotation-value-word-blocklist","title":"annotation-value-word-blocklist","text":"<p>Contains a comma-separated value of chars/words that are well known of being used to abuse Ingress configuration and must be blocked. Related to CVE-2021-25742</p> <p>When an annotation is detected with a value that matches one of the blocked bad words, the whole Ingress won't be configured.</p> <p>default: <code>\"\"</code></p> <p>When doing this, the default blocklist is override, which means that the Ingress admin should add all the words that should be blocked, here is a suggested block list.</p> <p>suggested: <code>\"load_module,lua_package,_by_lua,location,root,proxy_pass,serviceaccount,{,},',\\\"\"</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#hide-headers","title":"hide-headers","text":"<p>Sets additional header that will not be passed from the upstream server to the client response. default: empty</p> <p>References: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header</p>"},{"location":"user-guide/nginx-configuration/configmap/#access-log-params","title":"access-log-params","text":"<p>Additional params for access_log. For example, buffer=16k, gzip, flush=1m</p> <p>References: https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#access-log-path","title":"access-log-path","text":"<p>Access log path for both http and stream context. Goes to <code>/var/log/nginx/access.log</code> by default.</p> <p>Note: the file <code>/var/log/nginx/access.log</code> is a symlink to <code>/dev/stdout</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#http-access-log-path","title":"http-access-log-path","text":"<p>Access log path for http context globally. default: \"\"</p> <p>Note: If not specified, the <code>access-log-path</code> will be used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#stream-access-log-path","title":"stream-access-log-path","text":"<p>Access log path for stream context globally. default: \"\"</p> <p>Note: If not specified, the <code>access-log-path</code> will be used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-access-log-for-default-backend","title":"enable-access-log-for-default-backend","text":"<p>Enables logging access to default backend. default: is disabled.</p>"},{"location":"user-guide/nginx-configuration/configmap/#error-log-path","title":"error-log-path","text":"<p>Error log path. Goes to <code>/var/log/nginx/error.log</code> by default.</p> <p>Note: the file <code>/var/log/nginx/error.log</code> is a symlink to <code>/dev/stderr</code></p> <p>References: https://nginx.org/en/docs/ngx_core_module.html#error_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-modsecurity","title":"enable-modsecurity","text":"<p>Enables the modsecurity module for NGINX. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-owasp-modsecurity-crs","title":"enable-owasp-modsecurity-crs","text":"<p>Enables the OWASP ModSecurity Core Rule Set (CRS). default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#modsecurity-snippet","title":"modsecurity-snippet","text":"<p>Adds custom rules to modsecurity section of nginx configuration</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-header-buffer-size","title":"client-header-buffer-size","text":"<p>Allows to configure a custom buffer size for reading client request header.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_buffer_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-header-timeout","title":"client-header-timeout","text":"<p>Defines a timeout for reading client request header, in seconds.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-body-buffer-size","title":"client-body-buffer-size","text":"<p>Sets buffer size for reading client request body.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#client-body-timeout","title":"client-body-timeout","text":"<p>Defines a timeout for reading client request body, in seconds.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#disable-access-log","title":"disable-access-log","text":"<p>Disables the Access Log from the entire Ingress Controller. default: <code>false</code></p> <p>References: https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#disable-ipv6","title":"disable-ipv6","text":"<p>Disable listening on IPV6. default: <code>false</code>; IPv6 listening is enabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#disable-ipv6-dns","title":"disable-ipv6-dns","text":"<p>Disable IPV6 for nginx DNS resolver. default: <code>false</code>; IPv6 resolving enabled.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-underscores-in-headers","title":"enable-underscores-in-headers","text":"<p>Enables underscores in header names. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-ocsp","title":"enable-ocsp","text":"<p>Enables Online Certificate Status Protocol stapling (OCSP) support. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#ignore-invalid-headers","title":"ignore-invalid-headers","text":"<p>Set if header fields with invalid names should be ignored. default: is enabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#retry-non-idempotent","title":"retry-non-idempotent","text":"<p>Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error in the upstream server. The previous behavior can be restored using the value \"true\".</p>"},{"location":"user-guide/nginx-configuration/configmap/#error-log-level","title":"error-log-level","text":"<p>Configures the logging level of errors. Log levels above are listed in the order of increasing severity.</p> <p>References: https://nginx.org/en/docs/ngx_core_module.html#error_log</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-field-size","title":"http2-max-field-size","text":"<p>Warning</p> <p>This feature was deprecated in 1.1.3 and will be removed in 1.3.0. Use large-client-header-buffers instead.</p> <p>Limits the maximum size of an HPACK-compressed request header field.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_field_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-header-size","title":"http2-max-header-size","text":"<p>Warning</p> <p>This feature was deprecated in 1.1.3 and will be removed in 1.3.0. Use large-client-header-buffers instead.</p> <p>Limits the maximum size of the entire request header list after HPACK decompression.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_header_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-requests","title":"http2-max-requests","text":"<p>Warning</p> <p>This feature was deprecated in 1.1.3 and will be removed in 1.3.0. Use upstream-keepalive-requests instead.</p> <p>Sets the maximum number of requests (including push requests) that can be served through one HTTP/2 connection, after which the next client request will lead to connection closing and the need of establishing a new connection.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_requests</p>"},{"location":"user-guide/nginx-configuration/configmap/#http2-max-concurrent-streams","title":"http2-max-concurrent-streams","text":"<p>Sets the maximum number of concurrent HTTP/2 streams in a connection.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_concurrent_streams</p>"},{"location":"user-guide/nginx-configuration/configmap/#hsts","title":"hsts","text":"<p>Enables or disables the header HSTS in servers running SSL. HTTP Strict Transport Security (often abbreviated as HSTS) is a security feature (HTTP header) that tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. It provides protection against protocol downgrade attacks and cookie theft.</p> <p>References:</p> <ul> <li>https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security</li> <li>https://blog.qualys.com/securitylabs/2016/03/28/the-importance-of-a-proper-http-strict-transport-security-implementation-on-your-web-server</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#hsts-include-subdomains","title":"hsts-include-subdomains","text":"<p>Enables or disables the use of HSTS in all the subdomains of the server-name.</p>"},{"location":"user-guide/nginx-configuration/configmap/#hsts-max-age","title":"hsts-max-age","text":"<p>Sets the time, in seconds, that the browser should remember that this site is only to be accessed using HTTPS.</p>"},{"location":"user-guide/nginx-configuration/configmap/#hsts-preload","title":"hsts-preload","text":"<p>Enables or disables the preload attribute in the HSTS feature (when it is enabled).</p>"},{"location":"user-guide/nginx-configuration/configmap/#keep-alive","title":"keep-alive","text":"<p>Sets the time, in seconds, during which a keep-alive client connection will stay open on the server side. The zero value disables keep-alive client connections.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout</p> <p>Important</p> <p>Setting <code>keep-alive: '0'</code> will most likely break concurrent http/2 requests due to changes introduced with nginx 1.19.7</p> <pre><code>Changes with nginx 1.19.7                                        16 Feb 2021\n\n    *) Change: connections handling in HTTP/2 has been changed to better\n       match HTTP/1.x; the \"http2_recv_timeout\", \"http2_idle_timeout\", and\n       \"http2_max_requests\" directives have been removed, the\n       \"keepalive_timeout\" and \"keepalive_requests\" directives should be\n       used instead.\n</code></pre> <p>References: nginx change log nginx issue tracker nginx mailing list</p>"},{"location":"user-guide/nginx-configuration/configmap/#keep-alive-requests","title":"keep-alive-requests","text":"<p>Sets the maximum number of requests that can be served through one keep-alive connection.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests</p>"},{"location":"user-guide/nginx-configuration/configmap/#large-client-header-buffers","title":"large-client-header-buffers","text":"<p>Sets the maximum number and size of buffers used for reading large client request header. default: 4 8k</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-escape-none","title":"log-format-escape-none","text":"<p>Sets if the escape parameter is disabled entirely for character escaping in variables (\"true\") or controlled by log-format-escape-json (\"false\") Sets the nginx log format.</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-escape-json","title":"log-format-escape-json","text":"<p>Sets if the escape parameter allows JSON (\"true\") or default characters escaping in variables (\"false\") Sets the nginx log format.</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-upstream","title":"log-format-upstream","text":"<p>Sets the nginx log format. Example for json output:</p> <pre><code>log-format-upstream: '{\"time\": \"$time_iso8601\", \"remote_addr\": \"$proxy_protocol_addr\", \"x_forwarded_for\": \"$proxy_add_x_forwarded_for\", \"request_id\": \"$req_id\",\n  \"remote_user\": \"$remote_user\", \"bytes_sent\": $bytes_sent, \"request_time\": $request_time, \"status\": $status, \"vhost\": \"$host\", \"request_proto\": \"$server_protocol\",\n  \"path\": \"$uri\", \"request_query\": \"$args\", \"request_length\": $request_length, \"duration\": $request_time,\"method\": \"$request_method\", \"http_referrer\": \"$http_referer\",\n  \"http_user_agent\": \"$http_user_agent\" }'\n</code></pre> <p>Please check the log-format for definition of each field.</p>"},{"location":"user-guide/nginx-configuration/configmap/#log-format-stream","title":"log-format-stream","text":"<p>Sets the nginx stream format.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-multi-accept","title":"enable-multi-accept","text":"<p>If disabled, a worker process will accept one new connection at a time. Otherwise, a worker process will accept all new connections at a time. default: true</p> <p>References: https://nginx.org/en/docs/ngx_core_module.html#multi_accept</p>"},{"location":"user-guide/nginx-configuration/configmap/#max-worker-connections","title":"max-worker-connections","text":"<p>Sets the maximum number of simultaneous connections that can be opened by each worker process. 0 will use the value of max-worker-open-files. default: 16384</p> <p>Tip</p> <p>Using 0 in scenarios of high load improves performance at the cost of increasing RAM utilization (even on idle).</p>"},{"location":"user-guide/nginx-configuration/configmap/#max-worker-open-files","title":"max-worker-open-files","text":"<p>Sets the maximum number of files that can be opened by each worker process. The default of 0 means \"max open files (system's limit) - 1024\". default: 0</p>"},{"location":"user-guide/nginx-configuration/configmap/#map-hash-bucket-size","title":"map-hash-bucket-size","text":"<p>Sets the bucket size for the map variables hash tables. The details of setting up hash tables are provided in a separate document.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-real-ip-cidr","title":"proxy-real-ip-cidr","text":"<p>If <code>use-forwarded-headers</code> or <code>use-proxy-protocol</code> is enabled, <code>proxy-real-ip-cidr</code> defines the default IP/network address of your external load balancer. Can be a comma-separated list of CIDR blocks. default: \"0.0.0.0/0\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-set-headers","title":"proxy-set-headers","text":"<p>Sets custom headers from named configmap before sending traffic to backends. The value format is namespace/name.  See example</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-name-hash-max-size","title":"server-name-hash-max-size","text":"<p>Sets the maximum size of the server names hash tables used in server names,map directive\u2019s values, MIME types, names of request header strings, etc.</p> <p>References: https://nginx.org/en/docs/hash.html</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-name-hash-bucket-size","title":"server-name-hash-bucket-size","text":"<p>Sets the size of the bucket for the server names hash tables.</p> <p>References:</p> <ul> <li>https://nginx.org/en/docs/hash.html</li> <li>https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-headers-hash-max-size","title":"proxy-headers-hash-max-size","text":"<p>Sets the maximum size of the proxy headers hash tables.</p> <p>References:</p> <ul> <li>https://nginx.org/en/docs/hash.html</li> <li>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#reuse-port","title":"reuse-port","text":"<p>Instructs NGINX to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-headers-hash-bucket-size","title":"proxy-headers-hash-bucket-size","text":"<p>Sets the size of the bucket for the proxy headers hash tables.</p> <p>References:</p> <ul> <li>https://nginx.org/en/docs/hash.html</li> <li>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#plugins","title":"plugins","text":"<p>Activates plugins installed in <code>/etc/nginx/lua/plugins</code>. Refer to ingress-nginx plugins README for more information on how to write and install a plugin.</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-tokens","title":"server-tokens","text":"<p>Send NGINX Server header in responses and display NGINX version in error pages. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-ciphers","title":"ssl-ciphers","text":"<p>Sets the ciphers list to enable. The ciphers are specified in the format understood by the OpenSSL library.</p> <p>The default cipher list is:  <code>ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384</code>.</p> <p>The ordering of a ciphersuite is very important because it decides which algorithms are going to be selected in priority. The recommendation above prioritizes algorithms that provide perfect forward secrecy.</p> <p>DHE-based cyphers will not be available until DH parameter is configured Custom DH parameters for perfect forward secrecy</p> <p>Please check the Mozilla SSL Configuration Generator.</p> <p>Note: ssl_prefer_server_ciphers directive will be enabled by default for http context.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-ecdh-curve","title":"ssl-ecdh-curve","text":"<p>Specifies a curve for ECDHE ciphers.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-dh-param","title":"ssl-dh-param","text":"<p>Sets the name of the secret that contains Diffie-Hellman key to help with \"Perfect Forward Secrecy\".</p> <p>References:</p> <ul> <li>https://wiki.openssl.org/index.php/Diffie-Hellman_parameters</li> <li>https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam</li> <li>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-protocols","title":"ssl-protocols","text":"<p>Sets the SSL protocols to use. The default is: <code>TLSv1.2 TLSv1.3</code>.</p> <p>Please check the result of the configuration using <code>https://ssllabs.com/ssltest/analyze.html</code> or <code>https://testssl.sh</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-early-data","title":"ssl-early-data","text":"<p>Enables or disables TLS 1.3 early data, also known as Zero Round Trip Time Resumption (0-RTT).</p> <p>This requires <code>ssl-protocols</code> to have <code>TLSv1.3</code> enabled. Enable this with caution, because requests sent within early data are subject to replay attacks.</p> <p>ssl_early_data. The default is: <code>false</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-cache","title":"ssl-session-cache","text":"<p>Enables or disables the use of shared SSL cache among worker processes.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-cache-size","title":"ssl-session-cache-size","text":"<p>Sets the size of the SSL shared session cache between all worker processes.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-tickets","title":"ssl-session-tickets","text":"<p>Enables or disables session resumption through TLS session tickets.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-ticket-key","title":"ssl-session-ticket-key","text":"<p>Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string. To create a ticket: <code>openssl rand 80 | openssl enc -A -base64</code></p> <p>TLS session ticket-key, by default, a randomly generated key is used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-session-timeout","title":"ssl-session-timeout","text":"<p>Sets the time during which a client may reuse the session parameters stored in a cache.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-buffer-size","title":"ssl-buffer-size","text":"<p>Sets the size of the SSL buffer used for sending data. The default of 4k helps NGINX to improve TLS Time To First Byte (TTTFB).</p> <p>References: https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-proxy-protocol","title":"use-proxy-protocol","text":"<p>Enables or disables the PROXY protocol to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-protocol-header-timeout","title":"proxy-protocol-header-timeout","text":"<p>Sets the timeout value for receiving the proxy-protocol headers. The default of 5 seconds prevents the TLS passthrough handler from waiting indefinitely on a dropped connection. default: 5s</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-aio-write","title":"enable-aio-write","text":"<p>Enables or disables the directive aio_write that writes files asynchronously. default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-gzip","title":"use-gzip","text":"<p>Enables or disables compression of HTTP responses using the \"gzip\" module. MIME types to compress are controlled by gzip-types. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-geoip","title":"use-geoip","text":"<p>Enables or disables \"geoip\" module that creates variables with values depending on the client IP address, using the precompiled MaxMind databases. default: true</p> <p>Note: MaxMind legacy databases are discontinued and will not receive updates after 2019-01-02, cf. discontinuation notice. Consider use-geoip2 below.</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-geoip2","title":"use-geoip2","text":"<p>Enables the geoip2 module for NGINX. Since <code>0.27.0</code> and due to a change in the MaxMind databases a license is required to have access to the databases. For this reason, it is required to define a new flag <code>--maxmind-license-key</code> in the ingress controller deployment to download the databases needed during the initialization of the ingress controller. Alternatively, it is possible to use a volume to mount the files <code>/etc/ingress-controller/geoip/GeoLite2-City.mmdb</code> and <code>/etc/ingress-controller/geoip/GeoLite2-ASN.mmdb</code>, avoiding the overhead of the download.</p> <p>Important</p> <p>If the feature is enabled but the files are missing, GeoIP2 will not be enabled.</p> <p>default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#geoip2-autoreload-in-minutes","title":"geoip2-autoreload-in-minutes","text":"<p>Enables the geoip2 module autoreload in MaxMind databases setting the interval in minutes.</p> <p>default: 0</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-brotli","title":"enable-brotli","text":"<p>Enables or disables compression of HTTP responses using the \"brotli\" module. The default mime type list to compress is: <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>.  default: false</p> <p>Note: Brotli does not works in Safari &lt; 11. For more information see https://caniuse.com/#feat=brotli</p>"},{"location":"user-guide/nginx-configuration/configmap/#brotli-level","title":"brotli-level","text":"<p>Sets the Brotli Compression Level that will be used. default: 4</p>"},{"location":"user-guide/nginx-configuration/configmap/#brotli-min-length","title":"brotli-min-length","text":"<p>Minimum length of responses, in bytes, that will be eligible for brotli compression. default: 20</p>"},{"location":"user-guide/nginx-configuration/configmap/#brotli-types","title":"brotli-types","text":"<p>Sets the MIME Types that will be compressed on-the-fly by brotli. default: <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#use-http2","title":"use-http2","text":"<p>Enables or disables HTTP/2 support in secure connections.</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-disable","title":"gzip-disable","text":"<p>Disables gzipping of responses for requests with \"User-Agent\" header fields matching any of the specified regular expressions.</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-level","title":"gzip-level","text":"<p>Sets the gzip Compression Level that will be used. default: 1</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-min-length","title":"gzip-min-length","text":"<p>Minimum length of responses to be returned to the client before it is eligible for gzip compression, in bytes. default: 256</p>"},{"location":"user-guide/nginx-configuration/configmap/#gzip-types","title":"gzip-types","text":"<p>Sets the MIME types in addition to \"text/html\" to compress. The special value \"*\" matches any MIME type. Responses with the \"text/html\" type are always compressed if <code>use-gzip</code> is enabled. default: <code>application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#worker-processes","title":"worker-processes","text":"<p>Sets the number of worker processes. The default of \"auto\" means number of available CPU cores.</p>"},{"location":"user-guide/nginx-configuration/configmap/#worker-cpu-affinity","title":"worker-cpu-affinity","text":"<p>Binds worker processes to the sets of CPUs. worker_cpu_affinity. By default worker processes are not bound to any specific CPUs. The value can be:</p> <ul> <li>\"\": empty string indicate no affinity is applied.</li> <li>cpumask: e.g. <code>0001 0010 0100 1000</code> to bind processes to specific cpus.</li> <li>auto: binding worker processes automatically to available CPUs.</li> </ul>"},{"location":"user-guide/nginx-configuration/configmap/#worker-shutdown-timeout","title":"worker-shutdown-timeout","text":"<p>Sets a timeout for Nginx to wait for worker to gracefully shutdown. default: \"240s\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#load-balance","title":"load-balance","text":"<p>Sets the algorithm to use for load balancing. The value can either be:</p> <ul> <li>round_robin: to use the default round robin loadbalancer</li> <li>ewma: to use the Peak EWMA method for routing (implementation)</li> </ul> <p>The default is <code>round_robin</code>.</p> <ul> <li>To load balance using consistent hashing of IP or other variables, consider the <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> annotation.</li> <li>To load balance using session cookies, consider the <code>nginx.ingress.kubernetes.io/affinity</code> annotation.</li> </ul> <p>References: https://nginx.org/en/docs/http/load_balancing.html</p>"},{"location":"user-guide/nginx-configuration/configmap/#variables-hash-bucket-size","title":"variables-hash-bucket-size","text":"<p>Sets the bucket size for the variables hash table.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#variables-hash-max-size","title":"variables-hash-max-size","text":"<p>Sets the maximum size of the variables hash table.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-connections","title":"upstream-keepalive-connections","text":"<p>Activates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed. default: 320</p> <p>References: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-time","title":"upstream-keepalive-time","text":"<p>Sets the maximum time during which requests can be processed through one keepalive connection.  default: \"1h\"</p> <p>References: http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-timeout","title":"upstream-keepalive-timeout","text":"<p>Sets a timeout during which an idle keepalive connection to an upstream server will stay open.  default: 60</p> <p>References: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#upstream-keepalive-requests","title":"upstream-keepalive-requests","text":"<p>Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of requests is made, the connection is closed. default: 10000</p> <p>References: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-conn-zone-variable","title":"limit-conn-zone-variable","text":"<p>Sets parameters for a shared memory zone that will keep states for various keys of limit_conn_zone. The default of \"$binary_remote_addr\" variable\u2019s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-timeout","title":"proxy-stream-timeout","text":"<p>Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-next-upstream","title":"proxy-stream-next-upstream","text":"<p>When a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-next-upstream-timeout","title":"proxy-stream-next-upstream-timeout","text":"<p>Limits the time allowed to pass a connection to the next server. The 0 value turns off this limitation.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-next-upstream-tries","title":"proxy-stream-next-upstream-tries","text":"<p>Limits the number of possible tries a request should be passed to the next server. The 0 value turns off this limitation.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_tries</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-stream-responses","title":"proxy-stream-responses","text":"<p>Sets the number of datagrams expected from the proxied server in response to the client request if the UDP protocol is used.</p> <p>References: https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses</p>"},{"location":"user-guide/nginx-configuration/configmap/#bind-address","title":"bind-address","text":"<p>Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.</p>"},{"location":"user-guide/nginx-configuration/configmap/#use-forwarded-headers","title":"use-forwarded-headers","text":"<p>If true, NGINX passes the incoming <code>X-Forwarded-*</code> headers to upstreams. Use this option when NGINX is behind another L7 proxy / load balancer that is setting these headers.</p> <p>If false, NGINX ignores incoming <code>X-Forwarded-*</code> headers, filling them with the request information it sees. Use this option if NGINX is exposed directly to the internet, or it's behind a L3/packet-based load balancer that doesn't alter the source IP in the packets.</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-real-ip","title":"enable-real-ip","text":"<p><code>enable-real-ip</code> enables the configuration of https://nginx.org/en/docs/http/ngx_http_realip_module.html. Specific attributes of the module can be configured further by using <code>forwarded-for-header</code> and <code>proxy-real-ip-cidr</code> settings.</p>"},{"location":"user-guide/nginx-configuration/configmap/#forwarded-for-header","title":"forwarded-for-header","text":"<p>Sets the header field for identifying the originating IP address of a client. default: X-Forwarded-For</p>"},{"location":"user-guide/nginx-configuration/configmap/#compute-full-forwarded-for","title":"compute-full-forwarded-for","text":"<p>Append the remote address to the X-Forwarded-For header instead of replacing it. When this option is enabled, the upstream application is responsible for extracting the client IP based on its own list of trusted proxies.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-add-original-uri-header","title":"proxy-add-original-uri-header","text":"<p>Adds an X-Original-Uri header with the original request URI to the backend request</p>"},{"location":"user-guide/nginx-configuration/configmap/#generate-request-id","title":"generate-request-id","text":"<p>Ensures that X-Request-ID is defaulted to a random value, if no X-Request-ID is present in the request</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-collector-host","title":"jaeger-collector-host","text":"<p>Specifies the host to use when uploading traces. It must be a valid URL.</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-collector-port","title":"jaeger-collector-port","text":"<p>Specifies the port to use when uploading traces. default: 6831</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-endpoint","title":"jaeger-endpoint","text":"<p>Specifies the endpoint to use when uploading traces to a collector. This takes priority over <code>jaeger-collector-host</code> if both are specified.</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-service-name","title":"jaeger-service-name","text":"<p>Specifies the service name to use for any traces created. default: nginx</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-propagation-format","title":"jaeger-propagation-format","text":"<p>Specifies the traceparent/tracestate propagation format. default: jaeger</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-type","title":"jaeger-sampler-type","text":"<p>Specifies the sampler to be used when sampling traces. The available samplers are: const, probabilistic, ratelimiting, remote. default: const</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-param","title":"jaeger-sampler-param","text":"<p>Specifies the argument to be passed to the sampler constructor. Must be a number. For const this should be 0 to never sample and 1 to always sample. default: 1</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-host","title":"jaeger-sampler-host","text":"<p>Specifies the custom remote sampler host to be passed to the sampler constructor. Must be a valid URL. Leave blank to use default value (localhost). default: http://127.0.0.1</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-sampler-port","title":"jaeger-sampler-port","text":"<p>Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. default: 5778</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-trace-context-header-name","title":"jaeger-trace-context-header-name","text":"<p>Specifies the header name used for passing trace context. default: uber-trace-id</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-debug-header","title":"jaeger-debug-header","text":"<p>Specifies the header name used for force sampling. default: jaeger-debug-id</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-baggage-header","title":"jaeger-baggage-header","text":"<p>Specifies the header name used to submit baggage if there is no root span. default: jaeger-baggage</p>"},{"location":"user-guide/nginx-configuration/configmap/#jaeger-tracer-baggage-header-prefix","title":"jaeger-tracer-baggage-header-prefix","text":"<p>Specifies the header prefix used to propagate baggage. default: uberctx-</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-collector-host","title":"datadog-collector-host","text":"<p>Specifies the datadog agent host to use when uploading traces. It must be a valid URL.</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-collector-port","title":"datadog-collector-port","text":"<p>Specifies the port to use when uploading traces. default: 8126</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-service-name","title":"datadog-service-name","text":"<p>Specifies the service name to use for any traces created. default: nginx</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-environment","title":"datadog-environment","text":"<p>Specifies the environment this trace belongs to. default: prod</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-operation-name-override","title":"datadog-operation-name-override","text":"<p>Overrides the operation name to use for any traces crated. default: nginx.handle</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-priority-sampling","title":"datadog-priority-sampling","text":"<p>Specifies to use client-side sampling. If true disables client-side sampling (thus ignoring <code>sample_rate</code>) and enables distributed priority sampling, where traces are sampled based on a combination of user-assigned priorities and configuration from the agent. default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#datadog-sample-rate","title":"datadog-sample-rate","text":"<p>Specifies sample rate for any traces created. This is effective only when <code>datadog-priority-sampling</code> is <code>false</code> default: 1.0</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-opentelemetry","title":"enable-opentelemetry","text":"<p>Enables the nginx OpenTelemetry extension. default: is disabled</p> <p>References: https://github.com/open-telemetry/opentelemetry-cpp-contrib</p>"},{"location":"user-guide/nginx-configuration/configmap/#opentelemetry-operation-name","title":"opentelemetry-operation-name","text":"<p>Specifies a custom name for the server span. default: is empty</p> <p>For example, set to \"HTTP $request_method $uri\".</p>"},{"location":"user-guide/nginx-configuration/configmap/#otlp-collector-host","title":"otlp-collector-host","text":"<p>Specifies the host to use when uploading traces. It must be a valid URL.</p>"},{"location":"user-guide/nginx-configuration/configmap/#otlp-collector-port","title":"otlp-collector-port","text":"<p>Specifies the port to use when uploading traces. default: 4317</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-service-name","title":"otel-service-name","text":"<p>Specifies the service name to use for any traces created. default: nginx</p>"},{"location":"user-guide/nginx-configuration/configmap/#opentelemetry-trust-incoming-span-true","title":"opentelemetry-trust-incoming-span: \"true\"","text":"<p>Enables or disables using spans from incoming requests as parent for created ones. default: true</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-sampler-parent-based","title":"otel-sampler-parent-based","text":"<p>Uses sampler implementation which by default will take a sample if parent Activity is sampled. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-sampler-ratio","title":"otel-sampler-ratio","text":"<p>Specifies sample rate for any traces created. default: 0.01</p>"},{"location":"user-guide/nginx-configuration/configmap/#otel-sampler","title":"otel-sampler","text":"<p>Specifies the sampler to be used when sampling traces. The available samplers are: AlwaysOff, AlwaysOn, TraceIdRatioBased, remote. default: AlwaysOff</p>"},{"location":"user-guide/nginx-configuration/configmap/#main-snippet","title":"main-snippet","text":"<p>Adds custom configuration to the main section of the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#http-snippet","title":"http-snippet","text":"<p>Adds custom configuration to the http section of the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#server-snippet","title":"server-snippet","text":"<p>Adds custom configuration to all the servers in the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#stream-snippet","title":"stream-snippet","text":"<p>Adds custom configuration to the stream section of the nginx configuration.</p>"},{"location":"user-guide/nginx-configuration/configmap/#location-snippet","title":"location-snippet","text":"<p>Adds custom configuration to all the locations in the nginx configuration.</p> <p>You can not use this to add new locations that proxy to the Kubernetes pods, as the snippet does not have access to the Go template functions. If you want to add custom locations you will have to provide your own nginx.tmpl.</p>"},{"location":"user-guide/nginx-configuration/configmap/#custom-http-errors","title":"custom-http-errors","text":"<p>Enables which HTTP codes should be passed for processing with the error_page directive</p> <p>Setting at least one code also enables proxy_intercept_errors which are required to process error_page.</p> <p>Example usage: <code>custom-http-errors: 404,415</code></p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-body-size","title":"proxy-body-size","text":"<p>Sets the maximum allowed size of the client request body. See NGINX client_max_body_size.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-connect-timeout","title":"proxy-connect-timeout","text":"<p>Sets the timeout for establishing a connection with a proxied server. It should be noted that this timeout cannot usually exceed 75 seconds.</p> <p>It will also set the grpc_connect_timeout for gRPC connections.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-read-timeout","title":"proxy-read-timeout","text":"<p>Sets the timeout in seconds for reading a response from the proxied server. The timeout is set only between two successive read operations, not for the transmission of the whole response.</p> <p>It will also set the grpc_read_timeout for gRPC connections.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-send-timeout","title":"proxy-send-timeout","text":"<p>Sets the timeout in seconds for transmitting a request to the proxied server. The timeout is set only between two successive write operations, not for the transmission of the whole request.</p> <p>It will also set the grpc_send_timeout for gRPC connections.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-buffers-number","title":"proxy-buffers-number","text":"<p>Sets the number of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-buffer-size","title":"proxy-buffer-size","text":"<p>Sets the size of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-cookie-path","title":"proxy-cookie-path","text":"<p>Sets a text that should be changed in the path attribute of the \u201cSet-Cookie\u201d header fields of a proxied server response.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-cookie-domain","title":"proxy-cookie-domain","text":"<p>Sets a text that should be changed in the domain attribute of the \u201cSet-Cookie\u201d header fields of a proxied server response.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-next-upstream","title":"proxy-next-upstream","text":"<p>Specifies in which cases a request should be passed to the next server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-next-upstream-timeout","title":"proxy-next-upstream-timeout","text":"<p>Limits the time in seconds during which a request can be passed to the next server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-next-upstream-tries","title":"proxy-next-upstream-tries","text":"<p>Limit the number of possible tries a request should be passed to the next server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-redirect-from","title":"proxy-redirect-from","text":"<p>Sets the original text that should be changed in the \"Location\" and \"Refresh\" header fields of a proxied server response. default: off</p> <p>References: https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-request-buffering","title":"proxy-request-buffering","text":"<p>Enables or disables buffering of a client request body.</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-redirect","title":"ssl-redirect","text":"<p>Sets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule). default: \"true\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#force-ssl-redirect","title":"force-ssl-redirect","text":"<p>Sets the global value of redirects (308) to HTTPS if the server has a default TLS certificate (defined in extra-args). default: \"false\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#denylist-source-range","title":"denylist-source-range","text":"<p>Sets the default denylisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See ngx_http_access_module.</p>"},{"location":"user-guide/nginx-configuration/configmap/#whitelist-source-range","title":"whitelist-source-range","text":"<p>Sets the default whitelisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See ngx_http_access_module.</p>"},{"location":"user-guide/nginx-configuration/configmap/#skip-access-log-urls","title":"skip-access-log-urls","text":"<p>Sets a list of URLs that should not appear in the NGINX access log. This is useful with urls like <code>/health</code> or <code>health-check</code> that make \"complex\" reading the logs. default: is empty</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-rate","title":"limit-rate","text":"<p>Limits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-rate-after","title":"limit-rate-after","text":"<p>Sets the initial amount after which the further transmission of a response to a client will be rate limited.</p>"},{"location":"user-guide/nginx-configuration/configmap/#lua-shared-dicts","title":"lua-shared-dicts","text":"<p>Customize default Lua shared dictionaries or define more. You can use the following syntax to do so:</p> <pre><code>lua-shared-dicts: \"&lt;my dict name&gt;: &lt;my dict size&gt;, [&lt;my dict name&gt;: &lt;my dict size&gt;], ...\"\n</code></pre> <p>For example following will set default <code>certificate_data</code> dictionary to <code>100M</code> and will introduce a new dictionary called <code>my_custom_plugin</code>:</p> <pre><code>lua-shared-dicts: \"certificate_data: 100, my_custom_plugin: 5\"\n</code></pre> <p>You can optionally set a size unit to allow for kilobyte-granularity. Allowed units are 'm' or 'k' (case-insensitive), and it defaults to MB if no unit is provided. Here is a similar example, but the <code>my_custom_plugin</code> dict is only 512KB.</p> <pre><code>lua-shared-dicts: \"certificate_data: 100, my_custom_plugin: 512k\"\n</code></pre> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after</p>"},{"location":"user-guide/nginx-configuration/configmap/#http-redirect-code","title":"http-redirect-code","text":"<p>Sets the HTTP status code to be used in redirects. Supported codes are 301,302,307 and 308 default: 308</p> <p>Why the default code is 308?</p> <p>RFC 7238 was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if we send a redirect in methods like POST.</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-buffering","title":"proxy-buffering","text":"<p>Enables or disables buffering of responses from the proxied server.</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-req-status-code","title":"limit-req-status-code","text":"<p>Sets the status code to return in response to rejected requests. default: 503</p>"},{"location":"user-guide/nginx-configuration/configmap/#limit-conn-status-code","title":"limit-conn-status-code","text":"<p>Sets the status code to return in response to rejected connections. default: 503</p>"},{"location":"user-guide/nginx-configuration/configmap/#enable-syslog","title":"enable-syslog","text":"<p>Enable syslog feature for access log and error log. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#syslog-host","title":"syslog-host","text":"<p>Sets the address of syslog server. The address can be specified as a domain name or IP address.</p>"},{"location":"user-guide/nginx-configuration/configmap/#syslog-port","title":"syslog-port","text":"<p>Sets the port of syslog server. default: 514</p>"},{"location":"user-guide/nginx-configuration/configmap/#no-tls-redirect-locations","title":"no-tls-redirect-locations","text":"<p>A comma-separated list of locations on which http requests will never get redirected to their https counterpart. default: \"/.well-known/acme-challenge\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-allowed-response-headers","title":"global-allowed-response-headers","text":"<p>A comma-separated list of allowed response headers inside the custom headers annotations</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-url","title":"global-auth-url","text":"<p>A url to an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-url</code>. Locations that should not get authenticated can be listed using <code>no-auth-locations</code> See no-auth-locations. In addition, each service can be excluded from authentication via annotation <code>enable-global-auth</code> set to \"false\". default: \"\"</p> <p>References: https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#external-authentication</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-method","title":"global-auth-method","text":"<p>A HTTP method to use for an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-method</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-signin","title":"global-auth-signin","text":"<p>Sets the location of the error page for an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-signin</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-signin-redirect-param","title":"global-auth-signin-redirect-param","text":"<p>Sets the query parameter in the error page signin URL which contains the original URL of the request that failed authentication. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-signin-redirect-param</code>. default: \"rd\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-response-headers","title":"global-auth-response-headers","text":"<p>Sets the headers to pass to backend once authentication request completes. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-response-headers</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-request-redirect","title":"global-auth-request-redirect","text":"<p>Sets the X-Auth-Request-Redirect header value. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-request-redirect</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-snippet","title":"global-auth-snippet","text":"<p>Sets a custom snippet to use with external authentication. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-snippet</code>. default: \"\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-cache-key","title":"global-auth-cache-key","text":"<p>Enables caching for global auth requests. Specify a lookup key for auth responses, e.g. <code>$remote_user$http_authorization</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-cache-duration","title":"global-auth-cache-duration","text":"<p>Set a caching time for auth responses based on their response codes, e.g. <code>200 202 30m</code>. See proxy_cache_valid for details. You may specify multiple, comma-separated values: <code>200 202 10m, 401 5m</code>. defaults to <code>200 202 401 5m</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-auth-always-set-cookie","title":"global-auth-always-set-cookie","text":"<p>Always set a cookie returned by auth request. By default, the cookie will be set only if an upstream reports with the code 200, 201, 204, 206, 301, 302, 303, 304, 307, or 308. default: false</p>"},{"location":"user-guide/nginx-configuration/configmap/#no-auth-locations","title":"no-auth-locations","text":"<p>A comma-separated list of locations that should not get authenticated. default: \"/.well-known/acme-challenge\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#block-cidrs","title":"block-cidrs","text":"<p>A comma-separated list of IP addresses (or subnets), request from which have to be blocked globally.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_access_module.html#deny</p>"},{"location":"user-guide/nginx-configuration/configmap/#block-user-agents","title":"block-user-agents","text":"<p>A comma-separated list of User-Agent, request from which have to be blocked globally. It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code>map</code> Nginx directive documentation.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#map</p>"},{"location":"user-guide/nginx-configuration/configmap/#block-referers","title":"block-referers","text":"<p>A comma-separated list of Referers, request from which have to be blocked globally. It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code>map</code> Nginx directive documentation.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_map_module.html#map</p>"},{"location":"user-guide/nginx-configuration/configmap/#proxy-ssl-location-only","title":"proxy-ssl-location-only","text":"<p>Set if proxy-ssl parameters should be applied only on locations and not on servers. default: is disabled</p>"},{"location":"user-guide/nginx-configuration/configmap/#default-type","title":"default-type","text":"<p>Sets the default MIME type of a response. default: text/html</p> <p>References: https://nginx.org/en/docs/http/ngx_http_core_module.html#default_type</p>"},{"location":"user-guide/nginx-configuration/configmap/#global-rate-limit","title":"global-rate-limit","text":"<ul> <li><code>global-rate-limit-status-code</code>: configure HTTP status code to return when rejecting requests. Defaults to 429.</li> </ul> <p>Configure <code>memcached</code> client for Global Rate Limiting.</p> <ul> <li><code>global-rate-limit-memcached-host</code>: IP/FQDN of memcached server to use. Required to enable Global Rate Limiting.</li> <li><code>global-rate-limit-memcached-port</code>: port of memcached server to use. Defaults default memcached port of <code>11211</code>.</li> <li><code>global-rate-limit-memcached-connect-timeout</code>: configure timeout for connect, send and receive operations. Unit is millisecond. Defaults to 50ms.</li> <li><code>global-rate-limit-memcached-max-idle-timeout</code>: configure timeout for cleaning idle connections. Unit is millisecond. Defaults to 50ms.</li> <li><code>global-rate-limit-memcached-pool-size</code>: configure number of max connections to keep alive. Make sure your <code>memcached</code> server can handle <code>global-rate-limit-memcached-pool-size * worker-processes * &lt;number of ingress-nginx replicas&gt;</code> simultaneous connections.</li> </ul> <p>These settings get used by lua-resty-global-throttle that ingress-nginx includes. Refer to the link to learn more about <code>lua-resty-global-throttle</code>.</p>"},{"location":"user-guide/nginx-configuration/configmap/#service-upstream","title":"service-upstream","text":"<p>Set if the service's Cluster IP and port should be used instead of a list of all endpoints. This can be overwritten by an annotation on an Ingress rule. default: \"false\"</p>"},{"location":"user-guide/nginx-configuration/configmap/#ssl-reject-handshake","title":"ssl-reject-handshake","text":"<p>Set to reject SSL handshake to an unknown virtualhost. This parameter helps to mitigate the fingerprinting using default certificate of ingress. default: \"false\"</p> <p>References: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_reject_handshake</p>"},{"location":"user-guide/nginx-configuration/configmap/#debug-connections","title":"debug-connections","text":"<p>Enables debugging log for selected client connections. default: \"\"</p> <p>References: http://nginx.org/en/docs/ngx_core_module.html#debug_connection</p>"},{"location":"user-guide/nginx-configuration/configmap/#strict-validate-path-type","title":"strict-validate-path-type","text":"<p>Ingress objects contains a field called pathType that defines the proxy behavior. It can be <code>Exact</code>, <code>Prefix</code> and <code>ImplementationSpecific</code>.</p> <p>When pathType is configured as <code>Exact</code> or <code>Prefix</code>, there should be a more strict validation, allowing only paths starting with \"/\" and containing only alphanumeric characters and \"-\", \"_\" and additional \"/\".</p> <p>When this option is enabled, the validation will happen on the Admission Webhook, making any Ingress not using pathType <code>ImplementationSpecific</code> and containing invalid characters to be denied.</p> <p>This means that Ingress objects that rely on paths containing regex characters should use <code>ImplementationSpecific</code> pathType.</p> <p>The cluster admin should establish validation rules using mechanisms like Open Policy Agent to  validate that only authorized users can use <code>ImplementationSpecific</code> pathType and that only the authorized characters can be used.</p>"},{"location":"user-guide/nginx-configuration/configmap/#grpc-buffer-size-kb","title":"grpc-buffer-size-kb","text":"<p>Sets the configuration for the GRPC Buffer Size parameter. If not set it will use the default from NGINX.</p> <p>References: https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size</p>"},{"location":"user-guide/nginx-configuration/custom-template/","title":"Custom NGINX template","text":"<p>The NGINX template is located in the file <code>/etc/nginx/template/nginx.tmpl</code>.</p> <p>Using a Volume it is possible to use a custom template. This includes using a Configmap as source of the template</p> <pre><code>        volumeMounts:\n          - mountPath: /etc/nginx/template\n            name: nginx-template-volume\n            readOnly: true\n      volumes:\n        - name: nginx-template-volume\n          configMap:\n            name: nginx-template\n            items:\n            - key: nginx.tmpl\n              path: nginx.tmpl\n</code></pre> <p>Please note the template is tied to the Go code. Do not change names in the variable <code>$cfg</code>.</p> <p>For more information about the template syntax please check the Go template package. In addition to the built-in functions provided by the Go package the following functions are also available:</p> <ul> <li>empty: returns true if the specified parameter (string) is empty</li> <li>contains: strings.Contains</li> <li>hasPrefix: strings.HasPrefix</li> <li>hasSuffix: strings.HasSuffix</li> <li>toUpper: strings.ToUpper</li> <li>toLower: strings.ToLower</li> <li>split: strings.Split</li> <li>quote: wraps a string in double quotes</li> <li>buildLocation: helps to build the NGINX Location section in each server</li> <li>buildProxyPass: builds the reverse proxy configuration</li> <li>buildRateLimit: helps to build a limit zone inside a location if contains a rate limit annotation</li> </ul> <p>TODO:</p> <ul> <li>buildAuthLocation:</li> <li>buildAuthResponseHeaders:</li> <li>buildResolvers:</li> <li>buildDenyVariable:</li> <li>buildUpstreamName:</li> <li>buildForwardedFor:</li> <li>buildAuthSignURL:</li> <li>buildNextUpstream:</li> <li>filterRateLimits:</li> <li>formatIP:</li> <li>getenv:</li> <li>getIngressInformation:</li> <li>serverConfig:</li> <li>isLocationAllowed:</li> <li>isValidClientBodyBufferSize:</li> </ul>"},{"location":"user-guide/nginx-configuration/log-format/","title":"Log format","text":"<p>The default configuration uses a custom logging format to add additional information about upstreams, response time and status.</p> <pre><code>log_format upstreaminfo\n    '$remote_addr - $remote_user [$time_local] \"$request\" '\n    '$status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" '\n    '$request_length $request_time [$proxy_upstream_name] [$proxy_alternative_upstream_name] $upstream_addr '\n    '$upstream_response_length $upstream_response_time $upstream_status $req_id';\n</code></pre> Placeholder Description <code>$proxy_protocol_addr</code> remote address if proxy protocol is enabled <code>$remote_addr</code> the source IP address of the client <code>$remote_user</code> user name supplied with the Basic authentication <code>$time_local</code> local time in the Common Log Format <code>$request</code> full original request line <code>$status</code> response status <code>$body_bytes_sent</code> number of bytes sent to a client, not counting the response header <code>$http_referer</code> value of the Referer header <code>$http_user_agent</code> value of User-Agent header <code>$request_length</code> request length (including request line, header, and request body) <code>$request_time</code> time elapsed since the first bytes were read from the client <code>$proxy_upstream_name</code> name of the upstream. The format is <code>upstream-&lt;namespace&gt;-&lt;service name&gt;-&lt;service port&gt;</code> <code>$proxy_alternative_upstream_name</code> name of the alternative upstream. The format is <code>upstream-&lt;namespace&gt;-&lt;service name&gt;-&lt;service port&gt;</code> <code>$upstream_addr</code> the IP address and port (or the path to the domain socket) of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas. <code>$upstream_response_length</code> the length of the response obtained from the upstream server <code>$upstream_response_time</code> time spent on receiving the response from the upstream server as seconds with millisecond resolution <code>$upstream_status</code> status code of the response obtained from the upstream server <code>$req_id</code> value of the <code>X-Request-ID</code> HTTP header. If the header is not set, a randomly generated ID. <p>Additional available variables:</p> Placeholder Description <code>$namespace</code> namespace of the ingress <code>$ingress_name</code> name of the ingress <code>$service_name</code> name of the service <code>$service_port</code> port of the service <p>Sources:</p> <ul> <li>Upstream variables</li> <li>Embedded variables</li> </ul>"},{"location":"user-guide/third-party-addons/modsecurity/","title":"ModSecurity Web Application Firewall","text":"<p>ModSecurity is an open source, cross platform web application firewall (WAF) engine for Apache, IIS and Nginx that is developed by Trustwave's SpiderLabs. It has a robust event-based programming language which provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring, logging and real-time analysis - https://www.modsecurity.org</p> <p>The ModSecurity-nginx connector is the connection point between NGINX and libmodsecurity (ModSecurity v3).</p> <p>The default ModSecurity configuration file is located in <code>/etc/nginx/modsecurity/modsecurity.conf</code>. This is the only file located in this directory and contains the default recommended configuration. Using a volume we can replace this file with the desired configuration. To enable the ModSecurity feature we need to specify <code>enable-modsecurity: \"true\"</code> in the configuration configmap.</p> <p>Note: the default configuration use detection only, because that minimizes the chances of post-installation disruption. Due to the value of the setting SecAuditLogType=Concurrent the ModSecurity log is stored in multiple files inside the directory <code>/var/log/audit</code>. The default <code>Serial</code> value in SecAuditLogType can impact performance.</p> <p>The OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. The CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts. The directory <code>/etc/nginx/owasp-modsecurity-crs</code> contains the OWASP ModSecurity Core Rule Set repository. Using <code>enable-owasp-modsecurity-crs: \"true\"</code> we enable the use of the rules.</p>"},{"location":"user-guide/third-party-addons/opentelemetry/","title":"OpenTelemetry","text":"<p>Enables requests served by NGINX for distributed telemetry via The OpenTelemetry Project.</p> <p>Using the third party module opentelemetry-cpp-contrib/nginx the Ingress-Nginx Controller can configure NGINX to enable OpenTelemetry instrumentation. By default this feature is disabled.</p> <p>Check out this demo showcasing OpenTelemetry in Ingress NGINX. The video provides an overview and practical demonstration of how OpenTelemetry can be utilized in Ingress NGINX for observability and monitoring purposes.</p> <p> </p> <p>Demo: OpenTelemetry in Ingress NGINX.</p>"},{"location":"user-guide/third-party-addons/opentelemetry/#usage","title":"Usage","text":"<p>To enable the instrumentation we must enable OpenTelemetry in the configuration ConfigMap: <pre><code>data:\n  enable-opentelemetry: \"true\"\n</code></pre></p> <p>To enable or disable instrumentation for a single Ingress, use the <code>enable-opentelemetry</code> annotation: <pre><code>kind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/enable-opentelemetry: \"true\"\n</code></pre></p> <p>We must also set the host to use when uploading traces:</p> <p><pre><code>otlp-collector-host: \"otel-coll-collector.otel.svc\"\n</code></pre> NOTE: While the option is called <code>otlp-collector-host</code>, you will need to point this to any backend that receives otlp-grpc.</p> <p>Next you will need to deploy a distributed telemetry system which uses OpenTelemetry. opentelemetry-collector, Jaeger Tempo, and zipkin have been tested.</p> <p>Other optional configuration options: <pre><code># specifies the name to use for the server span\nopentelemetry-operation-name\n\n# sets whether or not to trust incoming telemetry spans\nopentelemetry-trust-incoming-span\n\n# specifies the port to use when uploading traces, Default: 4317\notlp-collector-port\n\n# specifies the service name to use for any traces created, Default: nginx\notel-service-name\n\n# The maximum queue size. After the size is reached data are dropped.\notel-max-queuesize\n\n# The delay interval in milliseconds between two consecutive exports.\notel-schedule-delay-millis\n\n# How long the export can run before it is cancelled.\notel-schedule-delay-millis\n\n# The maximum batch size of every export. It must be smaller or equal to maxQueueSize.\notel-max-export-batch-size\n\n# specifies sample rate for any traces created, Default: 0.01\notel-sampler-ratio\n\n# specifies the sampler to be used when sampling traces.\n# The available samplers are: AlwaysOn,  AlwaysOff, TraceIdRatioBased, Default: AlwaysOff\notel-sampler\n\n# Uses sampler implementation which by default will take a sample if parent Activity is sampled, Default: false\notel-sampler-parent-based\n</code></pre></p> <p>Note that you can also set whether to trust incoming spans (global default is true) per-location using annotations like the following: <pre><code>kind: Ingress\nmetadata:\n  annotations:\n    nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span: \"true\"\n</code></pre></p>"},{"location":"user-guide/third-party-addons/opentelemetry/#examples","title":"Examples","text":"<p>The following examples show how to deploy and test different distributed telemetry systems. These example can be performed using Docker Desktop.</p> <p>In the esigo/nginx-example GitHub repository is an example of a simple hello service:</p> <pre><code>graph TB\n    subgraph Browser\n    start[\"http://esigo.dev/hello/nginx\"]\n    end\n\n    subgraph app\n        sa[service-a]\n        sb[service-b]\n        sa --&gt; |name: nginx| sb\n        sb --&gt; |hello nginx!| sa\n    end\n\n    subgraph otel\n        otc[\"Otel Collector\"] \n    end\n\n    subgraph observability\n        tempo[\"Tempo\"]\n        grafana[\"Grafana\"]\n        backend[\"Jaeger\"]\n        zipkin[\"Zipkin\"]\n    end\n\n    subgraph ingress-nginx\n        ngx[nginx]\n    end\n\n    subgraph ngx[nginx]\n        ng[nginx]\n        om[OpenTelemetry module]\n    end\n\n    subgraph Node\n        app\n        otel\n        observability\n        ingress-nginx\n        om --&gt; |otlp-gRPC| otc --&gt; |jaeger| backend\n        otc --&gt; |zipkin| zipkin\n        otc --&gt; |otlp-gRPC| tempo --&gt; grafana\n        sa --&gt; |otlp-gRPC| otc\n        sb --&gt; |otlp-gRPC| otc\n        start --&gt; ng --&gt; sa\n    end</code></pre> <p>To install the example and collectors run:</p> <ol> <li> <p>Enable Ingress addon with:</p> <pre><code>  opentelemetry:\n    enabled: true\n    image: registry.k8s.io/ingress-nginx/opentelemetry:v20230527@sha256:fd7ec835f31b7b37187238eb4fdad4438806e69f413a203796263131f4f02ed0\n    containerSecurityContext:\n    allowPrivilegeEscalation: false\n</code></pre> </li> <li> <p>Enable OpenTelemetry and set the otlp-collector-host:</p> <pre><code>$ echo '\n  apiVersion: v1\n  kind: ConfigMap\n  data:\n    enable-opentelemetry: \"true\"\n    opentelemetry-config: \"/etc/nginx/opentelemetry.toml\"\n    opentelemetry-operation-name: \"HTTP $request_method $service_name $uri\"\n    opentelemetry-trust-incoming-span: \"true\"\n    otlp-collector-host: \"otel-coll-collector.otel.svc\"\n    otlp-collector-port: \"4317\"\n    otel-max-queuesize: \"2048\"\n    otel-schedule-delay-millis: \"5000\"\n    otel-max-export-batch-size: \"512\"\n    otel-service-name: \"nginx-proxy\" # Opentelemetry resource name\n    otel-sampler: \"AlwaysOn\" # Also: AlwaysOff, TraceIdRatioBased\n    otel-sampler-ratio: \"1.0\"\n    otel-sampler-parent-based: \"false\"\n  metadata:\n    name: ingress-nginx-controller\n    namespace: ingress-nginx\n  ' | kubectl replace -f -\n</code></pre> </li> <li> <p>Deploy otel-collector, grafana and Jaeger backend:</p> <pre><code># add helm charts needed for grafana and OpenTelemetry collector\nhelm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts\nhelm repo add grafana https://grafana.github.io/helm-charts\nhelm repo update\n# deply cert-manager needed for OpenTelemetry collector operator\nkubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.9.1/cert-manager.yaml\n# create observability namespace\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/namespace.yaml\n# install OpenTelemetry collector operator\nhelm upgrade --install otel-collector-operator -n otel --create-namespace open-telemetry/opentelemetry-operator\n# deploy OpenTelemetry collector\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/collector.yaml\n# deploy Jaeger all-in-one\nkubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.37.0/jaeger-operator.yaml -n observability\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/jaeger.yaml -n observability\n# deploy zipkin\nkubectl apply -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/zipkin.yaml -n observability\n# deploy tempo and grafana\nhelm upgrade --install tempo grafana/tempo --create-namespace -n observability\nhelm upgrade -f https://raw.githubusercontent.com/esigo/nginx-example/main/observability/grafana/grafana-values.yaml --install grafana grafana/grafana --create-namespace -n observability\n</code></pre> </li> <li> <p>Build and deploy demo app:</p> <pre><code># build images\nmake images\n\n# deploy demo app:\nmake deploy-app\n</code></pre> </li> <li> <p>Make a few requests to the Service:</p> <pre><code>kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8090:80\ncurl http://esigo.dev:8090/hello/nginx\n\n\nStatusCode        : 200\nStatusDescription : OK\nContent           : {\"v\":\"hello nginx!\"}\n\nRawContent        : HTTP/1.1 200 OK\n                    Connection: keep-alive\n                    Content-Length: 21\n                    Content-Type: text/plain; charset=utf-8\n                    Date: Mon, 10 Oct 2022 17:43:33 GMT\n\n                    {\"v\":\"hello nginx!\"}\n\nForms             : {}\nHeaders           : {[Connection, keep-alive], [Content-Length, 21], [Content-Type, text/plain; charset=utf-8], [Date,\n                    Mon, 10 Oct 2022 17:43:33 GMT]}\nImages            : {}\nInputFields       : {}\nLinks             : {}\nParsedHtml        : System.__ComObject\nRawContentLength  : 21\n</code></pre> </li> <li> <p>View the Grafana UI:</p> <p><pre><code>kubectl port-forward --namespace=observability service/grafana 3000:80\n</code></pre> In the Grafana interface we can see the details: </p> </li> <li> <p>View the Jaeger UI:</p> <p><pre><code>kubectl port-forward --namespace=observability service/jaeger-all-in-one-query 16686:16686\n</code></pre> In the Jaeger interface we can see the details: </p> </li> <li> <p>View the Zipkin UI:</p> <p><pre><code>kubectl port-forward --namespace=observability service/zipkin 9411:9411\n</code></pre> In the Zipkin interface we can see the details: </p> </li> </ol>"},{"location":"user-guide/third-party-addons/opentelemetry/#migration-from-opentracing-jaeger-zipkin-and-datadog","title":"Migration from OpenTracing, Jaeger, Zipkin and Datadog","text":"<p>If you are migrating from OpenTracing, Jaeger, Zipkin, or Datadog to OpenTelemetry, you may need to update various annotations and configurations. Here are the mappings for common annotations and configurations:</p>"},{"location":"user-guide/third-party-addons/opentelemetry/#annotations","title":"Annotations","text":"Legacy OpenTelemetry <code>nginx.ingress.kubernetes.io/enable-opentracing</code> <code>nginx.ingress.kubernetes.io/enable-opentelemetry</code> <code>nginx.ingress.kubernetes.io/opentracing-trust-incoming-span</code> <code>nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span</code>"},{"location":"user-guide/third-party-addons/opentelemetry/#configs","title":"Configs","text":"Legacy OpenTelemetry <code>opentracing-operation-name</code> <code>opentelemetry-operation-name</code> <code>opentracing-location-operation-name</code> <code>opentelemetry-operation-name</code> <code>opentracing-trust-incoming-span</code> <code>opentelemetry-trust-incoming-span</code> <code>zipkin-collector-port</code> <code>otlp-collector-port</code> <code>zipkin-service-name</code> <code>otel-service-name</code> <code>zipkin-sample-rate</code> <code>otel-sampler-ratio</code> <code>jaeger-collector-port</code> <code>otlp-collector-port</code> <code>jaeger-endpoint</code> <code>otlp-collector-port</code>, <code>otlp-collector-host</code> <code>jaeger-service-name</code> <code>otel-service-name</code> <code>jaeger-propagation-format</code> <code>N/A</code> <code>jaeger-sampler-type</code> <code>otel-sampler</code> <code>jaeger-sampler-param</code> <code>otel-sampler</code> <code>jaeger-sampler-host</code> <code>N/A</code> <code>jaeger-sampler-port</code> <code>N/A</code> <code>jaeger-trace-context-header-name</code> <code>N/A</code> <code>jaeger-debug-header</code> <code>N/A</code> <code>jaeger-baggage-header</code> <code>N/A</code> <code>jaeger-tracer-baggage-header-prefix</code> <code>N/A</code> <code>datadog-collector-port</code> <code>otlp-collector-port</code> <code>datadog-service-name</code> <code>otel-service-name</code> <code>datadog-environment</code> <code>N/A</code> <code>datadog-operation-name-override</code> <code>N/A</code> <code>datadog-priority-sampling</code> <code>otel-sampler</code> <code>datadog-sample-rate</code> <code>otel-sampler-ratio</code>"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index 9ab955eb7..6efae5a9e 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,322 +2,322 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/e2e-tests/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/faq/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/how-it-works/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/kubectl-plugin/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/lua_tests/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/troubleshooting/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/deploy/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/deploy/baremetal/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/deploy/hardening-guide/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/deploy/rbac/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/deploy/upgrade/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/developer-guide/code-overview/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/developer-guide/getting-started/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/enhancements/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/enhancements/20190724-only-dynamic-ssl/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/enhancements/20190815-zone-aware-routing/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/enhancements/20231001-split-containers/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/enhancements/YYYYMMDD-kep-template/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/PREREQUISITES/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/affinity/cookie/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/auth/basic/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/auth/client-certs/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/auth/external-auth/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/canary/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/configuration-snippets/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/custom-configuration/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/custom-errors/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/custom-headers/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/external-auth-headers/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/jwt/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/ssl-dh-param/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/customization/sysctl/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/docker-registry/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/grpc/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/multi-tls/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/openpolicyagent/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/psp/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/rewrite/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/static-ip/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/examples/tls-termination/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/basic-usage/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/cli-arguments/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/custom-errors/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/default-backend/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/external-articles/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/fcgi-services/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/ingress-path-matching/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/monitoring/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/multiple-ingress/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/retaining-client-ipaddress/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/tls/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/custom-template/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/log-format/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/third-party-addons/modsecurity/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://kubernetes.github.io/ingress-nginx/user-guide/third-party-addons/opentelemetry/</loc>
-         <lastmod>2024-05-15</lastmod>
+         <lastmod>2024-05-26</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index bab7b8576..dc99d090e 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/user-guide/nginx-configuration/annotations/index.html b/user-guide/nginx-configuration/annotations/index.html
index 5d9fc9fe8..9c59b6b13 100644
--- a/user-guide/nginx-configuration/annotations/index.html
+++ b/user-guide/nginx-configuration/annotations/index.html
@@ -29,7 +29,7 @@
 </code></pre></div> <p>Additionally it is possible to set:</p> <ul> <li><code>nginx.ingress.kubernetes.io/auth-keepalive</code>: <code>&lt;Connections&gt;</code> to specify the maximum number of keepalive connections to <code>auth-url</code>. Only takes effect when no variables are used in the host part of the URL. Defaults to <code>0</code> (keepalive disabled).</li> </ul> <blockquote> <p>Note: does not work with HTTP/2 listener because of a limitation in Lua <a href=https://github.com/openresty/lua-nginx-module#spdy-mode-not-fully-supported>subrequests</a>. <a href=../configmap/#use-http2>UseHTTP2</a> configuration should be disabled!</p> </blockquote> <ul> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-share-vars</code>: Whether to share Nginx variables among the current request and the auth request. Example use case is to track requests: when set to "true" X-Request-ID HTTP header will be the same for the backend and the auth request. Defaults to "false".</li> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-requests</code>: <code>&lt;Requests&gt;</code> to specify the maximum number of requests that can be served through one keepalive connection. Defaults to <code>1000</code> and only applied if <code>auth-keepalive</code> is set to higher than <code>0</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-keepalive-timeout</code>: <code>&lt;Timeout&gt;</code> to specify a duration in seconds which an idle keepalive connection to an upstream server will stay open. Defaults to <code>60</code> and only applied if <code>auth-keepalive</code> is set to higher than <code>0</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-method</code>: <code>&lt;Method&gt;</code> to specify the HTTP method to use.</li> <li><code>nginx.ingress.kubernetes.io/auth-signin</code>: <code>&lt;SignIn_URL&gt;</code> to specify the location of the error page.</li> <li><code>nginx.ingress.kubernetes.io/auth-signin-redirect-param</code>: <code>&lt;SignIn_URL&gt;</code> to specify the URL parameter in the error page which should contain the original URL for a failed signin request.</li> <li><code>nginx.ingress.kubernetes.io/auth-response-headers</code>: <code>&lt;Response_Header_1, ..., Response_Header_n&gt;</code> to specify headers to pass to backend once authentication request completes.</li> <li><code>nginx.ingress.kubernetes.io/auth-proxy-set-headers</code>: <code>&lt;ConfigMap&gt;</code> the name of a ConfigMap that specifies headers to pass to the authentication service</li> <li><code>nginx.ingress.kubernetes.io/auth-request-redirect</code>: <code>&lt;Request_Redirect_URL&gt;</code> to specify the X-Auth-Request-Redirect header value.</li> <li><code>nginx.ingress.kubernetes.io/auth-cache-key</code>: <code>&lt;Cache_Key&gt;</code> this enables caching for auth requests. specify a lookup key for auth responses. e.g. <code>$remote_user$http_authorization</code>. Each server and location has it's own keyspace. Hence a cached response is only valid on a per-server and per-location basis.</li> <li><code>nginx.ingress.kubernetes.io/auth-cache-duration</code>: <code>&lt;Cache_duration&gt;</code> to specify a caching time for auth responses based on their response codes, e.g. <code>200 202 30m</code>. See <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid>proxy_cache_valid</a> for details. You may specify multiple, comma-separated values: <code>200 202 10m, 401 5m</code>. defaults to <code>200 202 401 5m</code>.</li> <li><code>nginx.ingress.kubernetes.io/auth-always-set-cookie</code>: <code>&lt;Boolean_Flag&gt;</code> to set a cookie returned by auth request. By default, the cookie will be set only if an upstream reports with the code 200, 201, 204, 206, 301, 302, 303, 304, 307, or 308.</li> <li><code>nginx.ingress.kubernetes.io/auth-snippet</code>: <code>&lt;Auth_Snippet&gt;</code> to specify a custom snippet to use with external authentication, e.g.</li> </ul> <div class=highlight><pre><span></span><code><span class=nt>nginx.ingress.kubernetes.io/auth-url</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">http://foo.com/external-auth</span>
 <span class=nt>nginx.ingress.kubernetes.io/auth-snippet</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">|</span>
 <span class=w>    </span><span class=no>proxy_set_header Foo-Header 42;</span>
-</code></pre></div> <blockquote> <p>Note: <code>nginx.ingress.kubernetes.io/auth-snippet</code> is an optional annotation. However, it may only be used in conjunction with <code>nginx.ingress.kubernetes.io/auth-url</code> and will be ignored if <code>nginx.ingress.kubernetes.io/auth-url</code> is not set</p> </blockquote> <div class="admonition example"> <p class=admonition-title>Example</p> <p>Please check the <a href=../../../examples/auth/external-auth/ >external-auth</a> example.</p> </div> <h4 id=global-external-authentication>Global External Authentication<a class=headerlink href=#global-external-authentication title="Permanent link"> ¶</a></h4> <p>By default the controller redirects all requests to an existing service that provides authentication if <code>global-auth-url</code> is set in the NGINX ConfigMap. If you want to disable this behavior for that ingress, you can use <code>enable-global-auth: "false"</code> in the NGINX ConfigMap. <code>nginx.ingress.kubernetes.io/enable-global-auth</code>: indicates if GlobalExternalAuth configuration should be applied or not to this Ingress rule. Default values is set to <code>"true"</code>.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>For more information please see <a href=../configmap/#global-auth-url>global-auth-url</a>.</p> </div> <h3 id=rate-limiting>Rate Limiting<a class=headerlink href=#rate-limiting title="Permanent link"> ¶</a></h3> <p>These annotations define limits on connections and transmission rates. These can be used to mitigate <a href=https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus>DDoS Attacks</a>.</p> <ul> <li><code>nginx.ingress.kubernetes.io/limit-connections</code>: number of concurrent connections allowed from a single IP address. A 503 error is returned when exceeding this limit.</li> <li><code>nginx.ingress.kubernetes.io/limit-rps</code>: number of requests accepted from a given IP each second. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit, <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code>limit-req-status-code</a> <strong><em>default:</em></strong> 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rpm</code>: number of requests accepted from a given IP each minute. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit, <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code>limit-req-status-code</a> <strong><em>default:</em></strong> 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-burst-multiplier</code>: multiplier of the limit rate for burst size. The default burst multiplier is 5, this annotation override the default multiplier. When clients exceed this limit, <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code>limit-req-status-code</a> <strong><em>default:</em></strong> 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate-after</code>: initial number of kilobytes after which the further transmission of a response to a given connection will be rate limited. This feature must be used with <a href=#proxy-buffering>proxy-buffering</a> enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate</code>: number of kilobytes per second allowed to send to a given connection. The zero value disables rate limiting. This feature must be used with <a href=#proxy-buffering>proxy-buffering</a> enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-whitelist</code>: client IP source ranges to be excluded from rate-limiting. The value is a comma separated list of CIDRs.</li> </ul> <p>If you specify multiple annotations in a single Ingress rule, limits are applied in the order <code>limit-connections</code>, <code>limit-rpm</code>, <code>limit-rps</code>.</p> <p>To configure settings globally for all Ingress rules, the <code>limit-rate-after</code> and <code>limit-rate</code> values may be set in the <a href=../configmap/#limit-rate>NGINX ConfigMap</a>. The value set in an Ingress annotation will override the global setting.</p> <p>The client IP address will be set based on the use of <a href=../configmap/#use-proxy-protocol>PROXY protocol</a> or from the <code>X-Forwarded-For</code> header value when <a href=../configmap/#use-forwarded-headers>use-forwarded-headers</a> is enabled.</p> <h3 id=global-rate-limiting>Global Rate Limiting<a class=headerlink href=#global-rate-limiting title="Permanent link"> ¶</a></h3> <p><strong>Note:</strong> Be careful when configuring both (Local) Rate Limiting and Global Rate Limiting at the same time. They are two completely different rate limiting implementations. Whichever limit exceeds first will reject the requests. It might be a good idea to configure both of them to ease load on Global Rate Limiting backend in cases of spike in traffic.</p> <p>The stock NGINX rate limiting does not share its counters among different NGINX instances. Given that most ingress-nginx deployments are elastic and number of replicas can change any day it is impossible to configure a proper rate limit using stock NGINX functionalities. Global Rate Limiting overcome this by using <a href=https://github.com/ElvinEfendi/lua-resty-global-throttle>lua-resty-global-throttle</a>. <code>lua-resty-global-throttle</code> shares its counters via a central store such as <code>memcached</code>. The obvious shortcoming of this is users have to deploy and operate a <code>memcached</code> instance in order to benefit from this functionality. Configure the <code>memcached</code> using <a href=../configmap/#global-rate-limit>these configmap settings</a>.</p> <p><strong>Here are a few remarks for ingress-nginx integration of <code>lua-resty-global-throttle</code>:</strong></p> <ol> <li>We minimize <code>memcached</code> access by caching exceeding limit decisions. The expiry of cache entry is the desired delay <code>lua-resty-global-throttle</code> calculates for us. The Lua Shared Dictionary used for that is <code>global_throttle_cache</code>. Currently its size defaults to 10M. Customize it as per your needs using <a href=../configmap/#lua-shared-dicts>lua-shared-dicts</a>. When we fail to cache the exceeding limit decision then we log an NGINX error. You can monitor for that error to decide if you need to bump the cache size. Without cache the cost of processing a request is two memcached commands: <code>GET</code>, and <code>INCR</code>. With the cache it is only <code>INCR</code>.</li> <li>Log NGINX variable <code>$global_rate_limit_exceeding</code>'s value to have some visibility into what portion of requests are rejected (value <code>y</code>), whether they are rejected using cached decision (value <code>c</code>), or if they are not rejected (default value <code>n</code>). You can use <a href=../configmap/#log-format-upstream>log-format-upstream</a> to include that in access logs.</li> <li>In case of an error it will log the error message and <strong>fail open</strong>.</li> <li> <p>The annotations below creates Global Rate Limiting instance per ingress. That means if there are multiple paths configured under the same ingress, the Global Rate Limiting will count requests to all the paths under the same counter. Extract a path out into its own ingress if you need to isolate a certain path.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/global-rate-limit</code>: Configures maximum allowed number of requests per window. Required.</p> </li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-window</code>: Configures a time window (i.e <code>1m</code>) that the limit is applied. Required.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-key</code>: Configures a key for counting the samples. Defaults to <code>$remote_addr</code>. You can also combine multiple NGINX variables here, like <code>${remote_addr}-${http_x_api_client}</code> which would mean the limit will be applied to requests coming from the same API client (indicated by <code>X-API-Client</code> HTTP request header) with the same source IP address.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs</code>: comma separated list of IPs and CIDRs to match client IP against. When there's a match request is not considered for rate limiting.</li> </ol> <h3 id=permanent-redirect>Permanent Redirect<a class=headerlink href=#permanent-redirect title="Permanent link"> ¶</a></h3> <p>This annotation allows to return a permanent redirect (Return Code 301) instead of sending data to the upstream. For example <code>nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com</code> would redirect everything to Google.</p> <h3 id=permanent-redirect-code>Permanent Redirect Code<a class=headerlink href=#permanent-redirect-code title="Permanent link"> ¶</a></h3> <p>This annotation allows you to modify the status code used for permanent redirects. For example <code>nginx.ingress.kubernetes.io/permanent-redirect-code: '308'</code> would return your permanent-redirect with a 308.</p> <h3 id=temporal-redirect>Temporal Redirect<a class=headerlink href=#temporal-redirect title="Permanent link"> ¶</a></h3> <p>This annotation allows you to return a temporal redirect (Return Code 302) instead of sending data to the upstream. For example <code>nginx.ingress.kubernetes.io/temporal-redirect: https://www.google.com</code> would redirect everything to Google with a Return Code of 302 (Moved Temporarily)</p> <h3 id=ssl-passthrough>SSL Passthrough<a class=headerlink href=#ssl-passthrough title="Permanent link"> ¶</a></h3> <p>The annotation <code>nginx.ingress.kubernetes.io/ssl-passthrough</code> instructs the controller to send TLS connections directly to the backend instead of letting NGINX decrypt the communication. See also <a href=../../tls/#ssl-passthrough>TLS/HTTPS</a> in the User guide.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>SSL Passthrough is <strong>disabled by default</strong> and requires starting the controller with the <a href=../../cli-arguments/ ><code>--enable-ssl-passthrough</code></a> flag.</p> </div> <div class="admonition attention"> <p class=admonition-title>Attention</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=service-upstream>Service Upstream<a class=headerlink href=#service-upstream title="Permanent link"> ¶</a></h3> <p>By default the Ingress-Nginx Controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.</p> <p>The <code>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> <p>This can be desirable for things like zero-downtime deployments . See issue <a href=https://github.com/kubernetes/ingress-nginx/issues/257>#257</a>.</p> <h4 id=known-issues>Known Issues<a class=headerlink href=#known-issues title="Permanent link"> ¶</a></h4> <p>If the <code>service-upstream</code> annotation is specified the following things should be taken into consideration:</p> <ul> <li>Sticky Sessions will not work as only round-robin load balancing is supported.</li> <li>The <code>proxy_next_upstream</code> directive will not have any effect meaning on error the request will not be dispatched to another upstream.</li> </ul> <h3 id=server-side-https-enforcement-through-redirect>Server-side HTTPS enforcement through redirect<a class=headerlink href=#server-side-https-enforcement-through-redirect title="Permanent link"> ¶</a></h3> <p>By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress. If you want to disable this behavior globally, you can use <code>ssl-redirect: "false"</code> in the NGINX <a href=../configmap/#ssl-redirect>ConfigMap</a>.</p> <p>To configure this feature for specific ingress resources, you can use the <code>nginx.ingress.kubernetes.io/ssl-redirect: "false"</code> annotation in the particular resource.</p> <p>When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is no TLS certificate available. This can be achieved by using the <code>nginx.ingress.kubernetes.io/force-ssl-redirect: "true"</code> annotation in the particular resource.</p> <p>To preserve the trailing slash in the URI with <code>ssl-redirect</code>, set <code>nginx.ingress.kubernetes.io/preserve-trailing-slash: "true"</code> annotation for that particular resource.</p> <h3 id=redirect-fromto-www>Redirect from/to www<a class=headerlink href=#redirect-fromto-www title="Permanent link"> ¶</a></h3> <p>In some scenarios is required to redirect from <code>www.domain.com</code> to <code>domain.com</code> or vice versa. To enable this feature use the annotation <code>nginx.ingress.kubernetes.io/from-to-www-redirect: "true"</code></p> <div class="admonition attention"> <p class=admonition-title>Attention</p> <p>If at some point a new Ingress is created with a host equal to one of the options (like <code>domain.com</code>) the annotation will be omitted.</p> </div> <div class="admonition attention"> <p class=admonition-title>Attention</p> <p>For HTTPS to HTTPS redirects is mandatory the SSL Certificate defined in the Secret, located in the TLS section of Ingress, contains both FQDN in the common name of the certificate.</p> </div> <h3 id=denylist-source-range>Denylist source range<a class=headerlink href=#denylist-source-range title="Permanent link"> ¶</a></h3> <p>You can specify blocked client IP source ranges through the <code>nginx.ingress.kubernetes.io/denylist-source-range</code> annotation. The value is a comma separated list of <a href=https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>CIDRs</a>, e.g. <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>denylist-source-range</code> value may be set in the <a href=../configmap/#denylist-source-range>NGINX ConfigMap</a>.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p> </div> <h3 id=whitelist-source-range>Whitelist source range<a class=headerlink href=#whitelist-source-range title="Permanent link"> ¶</a></h3> <p>You can specify allowed client IP source ranges through the <code>nginx.ingress.kubernetes.io/whitelist-source-range</code> annotation. The value is a comma separated list of <a href=https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>CIDRs</a>, e.g. <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>whitelist-source-range</code> value may be set in the <a href=../configmap/#whitelist-source-range>NGINX ConfigMap</a>.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p> </div> <h3 id=custom-timeouts>Custom timeouts<a class=headerlink href=#custom-timeouts title="Permanent link"> ¶</a></h3> <p>Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers. In some scenarios is required to have different values. To allow this we provide annotations that allows this customization:</p> <ul> <li><code>nginx.ingress.kubernetes.io/proxy-connect-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-send-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-read-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-tries</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-request-buffering</code></li> </ul> <p>Note: All timeout values are unitless and in seconds e.g. <code>nginx.ingress.kubernetes.io/proxy-read-timeout: "120"</code> sets a valid 120 seconds proxy read timeout.</p> <h3 id=proxy-redirect>Proxy redirect<a class=headerlink href=#proxy-redirect title="Permanent link"> ¶</a></h3> <p>The annotations <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> and <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code> will set the first and second parameters of NGINX's proxy_redirect directive respectively. It is possible to set the text that should be changed in the <code>Location</code> and <code>Refresh</code> header fields of a <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect>proxied server response</a></p> <p>Setting "off" or "default" in the annotation <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> disables <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code>, otherwise, both annotations must be used in unison. Note that each annotation must be a string without spaces.</p> <p>By default the value of each annotation is "off".</p> <h3 id=custom-max-body-size>Custom max body size<a class=headerlink href=#custom-max-body-size title="Permanent link"> ¶</a></h3> <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=https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size><code>client_max_body_size</code></a>.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-body-size</code> value may be set in the <a href=../configmap/#proxy-body-size>NGINX ConfigMap</a>. To use custom values in an Ingress rule define these annotation:</p> <div class=highlight><pre><span></span><code><span class=nt>nginx.ingress.kubernetes.io/proxy-body-size</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">8m</span>
+</code></pre></div> <blockquote> <p>Note: <code>nginx.ingress.kubernetes.io/auth-snippet</code> is an optional annotation. However, it may only be used in conjunction with <code>nginx.ingress.kubernetes.io/auth-url</code> and will be ignored if <code>nginx.ingress.kubernetes.io/auth-url</code> is not set</p> </blockquote> <div class="admonition example"> <p class=admonition-title>Example</p> <p>Please check the <a href=../../../examples/auth/external-auth/ >external-auth</a> example.</p> </div> <h4 id=global-external-authentication>Global External Authentication<a class=headerlink href=#global-external-authentication title="Permanent link"> ¶</a></h4> <p>By default the controller redirects all requests to an existing service that provides authentication if <code>global-auth-url</code> is set in the NGINX ConfigMap. If you want to disable this behavior for that ingress, you can use <code>enable-global-auth: "false"</code> in the NGINX ConfigMap. <code>nginx.ingress.kubernetes.io/enable-global-auth</code>: indicates if GlobalExternalAuth configuration should be applied or not to this Ingress rule. Default values is set to <code>"true"</code>.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>For more information please see <a href=../configmap/#global-auth-url>global-auth-url</a>.</p> </div> <h3 id=rate-limiting>Rate Limiting<a class=headerlink href=#rate-limiting title="Permanent link"> ¶</a></h3> <p>These annotations define limits on connections and transmission rates. These can be used to mitigate <a href=https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus>DDoS Attacks</a>.</p> <ul> <li><code>nginx.ingress.kubernetes.io/limit-connections</code>: number of concurrent connections allowed from a single IP address. A 503 error is returned when exceeding this limit.</li> <li><code>nginx.ingress.kubernetes.io/limit-rps</code>: number of requests accepted from a given IP each second. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit, <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code>limit-req-status-code</a> <strong><em>default:</em></strong> 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rpm</code>: number of requests accepted from a given IP each minute. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit, <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code>limit-req-status-code</a> <strong><em>default:</em></strong> 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-burst-multiplier</code>: multiplier of the limit rate for burst size. The default burst multiplier is 5, this annotation override the default multiplier. When clients exceed this limit, <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#limit-req-status-code>limit-req-status-code</a> <strong><em>default:</em></strong> 503 is returned.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate-after</code>: initial number of kilobytes after which the further transmission of a response to a given connection will be rate limited. This feature must be used with <a href=#proxy-buffering>proxy-buffering</a> enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-rate</code>: number of kilobytes per second allowed to send to a given connection. The zero value disables rate limiting. This feature must be used with <a href=#proxy-buffering>proxy-buffering</a> enabled.</li> <li><code>nginx.ingress.kubernetes.io/limit-whitelist</code>: client IP source ranges to be excluded from rate-limiting. The value is a comma separated list of CIDRs.</li> </ul> <p>If you specify multiple annotations in a single Ingress rule, limits are applied in the order <code>limit-connections</code>, <code>limit-rpm</code>, <code>limit-rps</code>.</p> <p>To configure settings globally for all Ingress rules, the <code>limit-rate-after</code> and <code>limit-rate</code> values may be set in the <a href=../configmap/#limit-rate>NGINX ConfigMap</a>. The value set in an Ingress annotation will override the global setting.</p> <p>The client IP address will be set based on the use of <a href=../configmap/#use-proxy-protocol>PROXY protocol</a> or from the <code>X-Forwarded-For</code> header value when <a href=../configmap/#use-forwarded-headers>use-forwarded-headers</a> is enabled.</p> <h3 id=global-rate-limiting>Global Rate Limiting<a class=headerlink href=#global-rate-limiting title="Permanent link"> ¶</a></h3> <p><strong>Note:</strong> Be careful when configuring both (Local) Rate Limiting and Global Rate Limiting at the same time. They are two completely different rate limiting implementations. Whichever limit exceeds first will reject the requests. It might be a good idea to configure both of them to ease load on Global Rate Limiting backend in cases of spike in traffic.</p> <p>The stock NGINX rate limiting does not share its counters among different NGINX instances. Given that most ingress-nginx deployments are elastic and number of replicas can change any day it is impossible to configure a proper rate limit using stock NGINX functionalities. Global Rate Limiting overcome this by using <a href=https://github.com/ElvinEfendi/lua-resty-global-throttle>lua-resty-global-throttle</a>. <code>lua-resty-global-throttle</code> shares its counters via a central store such as <code>memcached</code>. The obvious shortcoming of this is users have to deploy and operate a <code>memcached</code> instance in order to benefit from this functionality. Configure the <code>memcached</code> using <a href=../configmap/#global-rate-limit>these configmap settings</a>.</p> <p><strong>Here are a few remarks for ingress-nginx integration of <code>lua-resty-global-throttle</code>:</strong></p> <ol> <li>We minimize <code>memcached</code> access by caching exceeding limit decisions. The expiry of cache entry is the desired delay <code>lua-resty-global-throttle</code> calculates for us. The Lua Shared Dictionary used for that is <code>global_throttle_cache</code>. Currently its size defaults to 10M. Customize it as per your needs using <a href=../configmap/#lua-shared-dicts>lua-shared-dicts</a>. When we fail to cache the exceeding limit decision then we log an NGINX error. You can monitor for that error to decide if you need to bump the cache size. Without cache the cost of processing a request is two memcached commands: <code>GET</code>, and <code>INCR</code>. With the cache it is only <code>INCR</code>.</li> <li>Log NGINX variable <code>$global_rate_limit_exceeding</code>'s value to have some visibility into what portion of requests are rejected (value <code>y</code>), whether they are rejected using cached decision (value <code>c</code>), or if they are not rejected (default value <code>n</code>). You can use <a href=../configmap/#log-format-upstream>log-format-upstream</a> to include that in access logs.</li> <li>In case of an error it will log the error message and <strong>fail open</strong>.</li> <li> <p>The annotations below creates Global Rate Limiting instance per ingress. That means if there are multiple paths configured under the same ingress, the Global Rate Limiting will count requests to all the paths under the same counter. Extract a path out into its own ingress if you need to isolate a certain path.</p> </li> <li> <p><code>nginx.ingress.kubernetes.io/global-rate-limit</code>: Configures maximum allowed number of requests per window. Required.</p> </li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-window</code>: Configures a time window (i.e <code>1m</code>) that the limit is applied. Required.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-key</code>: Configures a key for counting the samples. Defaults to <code>$remote_addr</code>. You can also combine multiple NGINX variables here, like <code>${remote_addr}-${http_x_api_client}</code> which would mean the limit will be applied to requests coming from the same API client (indicated by <code>X-API-Client</code> HTTP request header) with the same source IP address.</li> <li><code>nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs</code>: comma separated list of IPs and CIDRs to match client IP against. When there's a match request is not considered for rate limiting.</li> </ol> <h3 id=permanent-redirect>Permanent Redirect<a class=headerlink href=#permanent-redirect title="Permanent link"> ¶</a></h3> <p>This annotation allows to return a permanent redirect (Return Code 301) instead of sending data to the upstream. For example <code>nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com</code> would redirect everything to Google.</p> <h3 id=permanent-redirect-code>Permanent Redirect Code<a class=headerlink href=#permanent-redirect-code title="Permanent link"> ¶</a></h3> <p>This annotation allows you to modify the status code used for permanent redirects. For example <code>nginx.ingress.kubernetes.io/permanent-redirect-code: '308'</code> would return your permanent-redirect with a 308.</p> <h3 id=temporal-redirect>Temporal Redirect<a class=headerlink href=#temporal-redirect title="Permanent link"> ¶</a></h3> <p>This annotation allows you to return a temporal redirect (Return Code 302) instead of sending data to the upstream. For example <code>nginx.ingress.kubernetes.io/temporal-redirect: https://www.google.com</code> would redirect everything to Google with a Return Code of 302 (Moved Temporarily)</p> <h3 id=ssl-passthrough>SSL Passthrough<a class=headerlink href=#ssl-passthrough title="Permanent link"> ¶</a></h3> <p>The annotation <code>nginx.ingress.kubernetes.io/ssl-passthrough</code> instructs the controller to send TLS connections directly to the backend instead of letting NGINX decrypt the communication. See also <a href=../../tls/#ssl-passthrough>TLS/HTTPS</a> in the User guide.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>SSL Passthrough is <strong>disabled by default</strong> and requires starting the controller with the <a href=../../cli-arguments/ ><code>--enable-ssl-passthrough</code></a> flag.</p> </div> <div class="admonition attention"> <p class=admonition-title>Attention</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=service-upstream>Service Upstream<a class=headerlink href=#service-upstream title="Permanent link"> ¶</a></h3> <p>By default the Ingress-Nginx Controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.</p> <p>The <code>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> <p>This can be desirable for things like zero-downtime deployments . See issue <a href=https://github.com/kubernetes/ingress-nginx/issues/257>#257</a>.</p> <h4 id=known-issues>Known Issues<a class=headerlink href=#known-issues title="Permanent link"> ¶</a></h4> <p>If the <code>service-upstream</code> annotation is specified the following things should be taken into consideration:</p> <ul> <li>Sticky Sessions will not work as only round-robin load balancing is supported.</li> <li>The <code>proxy_next_upstream</code> directive will not have any effect meaning on error the request will not be dispatched to another upstream.</li> </ul> <h3 id=server-side-https-enforcement-through-redirect>Server-side HTTPS enforcement through redirect<a class=headerlink href=#server-side-https-enforcement-through-redirect title="Permanent link"> ¶</a></h3> <p>By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress. If you want to disable this behavior globally, you can use <code>ssl-redirect: "false"</code> in the NGINX <a href=../configmap/#ssl-redirect>ConfigMap</a>.</p> <p>To configure this feature for specific ingress resources, you can use the <code>nginx.ingress.kubernetes.io/ssl-redirect: "false"</code> annotation in the particular resource.</p> <p>When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is no TLS certificate available. This can be achieved by using the <code>nginx.ingress.kubernetes.io/force-ssl-redirect: "true"</code> annotation in the particular resource.</p> <p>To preserve the trailing slash in the URI with <code>ssl-redirect</code>, set <code>nginx.ingress.kubernetes.io/preserve-trailing-slash: "true"</code> annotation for that particular resource.</p> <h3 id=redirect-fromto-www>Redirect from/to www<a class=headerlink href=#redirect-fromto-www title="Permanent link"> ¶</a></h3> <p>In some scenarios is required to redirect from <code>www.domain.com</code> to <code>domain.com</code> or vice versa. To enable this feature use the annotation <code>nginx.ingress.kubernetes.io/from-to-www-redirect: "true"</code></p> <div class="admonition attention"> <p class=admonition-title>Attention</p> <p>If at some point a new Ingress is created with a host equal to one of the options (like <code>domain.com</code>) the annotation will be omitted.</p> </div> <div class="admonition attention"> <p class=admonition-title>Attention</p> <p>For HTTPS to HTTPS redirects is mandatory the SSL Certificate defined in the Secret, located in the TLS section of Ingress, contains both FQDN in the common name of the certificate.</p> </div> <h3 id=denylist-source-range>Denylist source range<a class=headerlink href=#denylist-source-range title="Permanent link"> ¶</a></h3> <p>You can specify blocked client IP source ranges through the <code>nginx.ingress.kubernetes.io/denylist-source-range</code> annotation. The value is a comma separated list of <a href=https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>CIDRs</a>, e.g. <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>denylist-source-range</code> value may be set in the <a href=../configmap/#denylist-source-range>NGINX ConfigMap</a>.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p> </div> <h3 id=whitelist-source-range>Whitelist source range<a class=headerlink href=#whitelist-source-range title="Permanent link"> ¶</a></h3> <p>You can specify allowed client IP source ranges through the <code>nginx.ingress.kubernetes.io/whitelist-source-range</code> annotation. The value is a comma separated list of <a href=https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>CIDRs</a>, e.g. <code>10.0.0.0/24,172.10.0.1</code>.</p> <p>To configure this setting globally for all Ingress rules, the <code>whitelist-source-range</code> value may be set in the <a href=../configmap/#whitelist-source-range>NGINX ConfigMap</a>.</p> <div class="admonition note"> <p class=admonition-title>Note</p> <p>Adding an annotation to an Ingress rule overrides any global restriction.</p> </div> <h3 id=custom-timeouts>Custom timeouts<a class=headerlink href=#custom-timeouts title="Permanent link"> ¶</a></h3> <p>Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers. In some scenarios is required to have different values. To allow this we provide annotations that allows this customization:</p> <ul> <li><code>nginx.ingress.kubernetes.io/proxy-connect-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-send-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-read-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-timeout</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-next-upstream-tries</code></li> <li><code>nginx.ingress.kubernetes.io/proxy-request-buffering</code></li> </ul> <p>If you indicate <a href=#backend-protocol>Backend Protocol</a> as <code>GRPC</code> or <code>GRPCS</code>, the following grpc values will be set and inherited from proxy timeouts:</p> <ul> <li><a href=https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout><code>grpc_connect_timeout=5s</code></a>, from <code>nginx.ingress.kubernetes.io/proxy-connect-timeout</code></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout><code>grpc_send_timeout=60s</code></a>, from <code>nginx.ingress.kubernetes.io/proxy-send-timeout</code></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout><code>grpc_read_timeout=60s</code></a>, from <code>nginx.ingress.kubernetes.io/proxy-read-timeout</code></li> </ul> <p>Note: All timeout values are unitless and in seconds e.g. <code>nginx.ingress.kubernetes.io/proxy-read-timeout: "120"</code> sets a valid 120 seconds proxy read timeout.</p> <h3 id=proxy-redirect>Proxy redirect<a class=headerlink href=#proxy-redirect title="Permanent link"> ¶</a></h3> <p>The annotations <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> and <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code> will set the first and second parameters of NGINX's proxy_redirect directive respectively. It is possible to set the text that should be changed in the <code>Location</code> and <code>Refresh</code> header fields of a <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect>proxied server response</a></p> <p>Setting "off" or "default" in the annotation <code>nginx.ingress.kubernetes.io/proxy-redirect-from</code> disables <code>nginx.ingress.kubernetes.io/proxy-redirect-to</code>, otherwise, both annotations must be used in unison. Note that each annotation must be a string without spaces.</p> <p>By default the value of each annotation is "off".</p> <h3 id=custom-max-body-size>Custom max body size<a class=headerlink href=#custom-max-body-size title="Permanent link"> ¶</a></h3> <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=https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size><code>client_max_body_size</code></a>.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-body-size</code> value may be set in the <a href=../configmap/#proxy-body-size>NGINX ConfigMap</a>. To use custom values in an Ingress rule define these annotation:</p> <div class=highlight><pre><span></span><code><span class=nt>nginx.ingress.kubernetes.io/proxy-body-size</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">8m</span>
 </code></pre></div> <h3 id=proxy-cookie-domain>Proxy cookie domain<a class=headerlink href=#proxy-cookie-domain title="Permanent link"> ¶</a></h3> <p>Sets a text that <a href=https://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> <p>To configure this setting globally for all Ingress rules, the <code>proxy-cookie-domain</code> value may be set in the <a href=../configmap/#proxy-cookie-domain>NGINX ConfigMap</a>.</p> <h3 id=proxy-cookie-path>Proxy cookie path<a class=headerlink href=#proxy-cookie-path title="Permanent link"> ¶</a></h3> <p>Sets a text that <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_path>should be changed in the path attribute</a> of the "Set-Cookie" header fields of a proxied server response.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-cookie-path</code> value may be set in the <a href=../configmap/#proxy-cookie-path>NGINX ConfigMap</a>.</p> <h3 id=proxy-buffering>Proxy buffering<a class=headerlink href=#proxy-buffering title="Permanent link"> ¶</a></h3> <p>Enable or disable proxy buffering <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering><code>proxy_buffering</code></a>. By default proxy buffering is disabled in the NGINX config.</p> <p>To configure this setting globally for all Ingress rules, the <code>proxy-buffering</code> value may be set in the <a href=../configmap/#proxy-buffering>NGINX ConfigMap</a>. To use custom values in an Ingress rule define these annotation:</p> <div class=highlight><pre><span></span><code><span class=nt>nginx.ingress.kubernetes.io/proxy-buffering</span><span class=p>:</span><span class=w> </span><span class=s>&quot;on&quot;</span>
 </code></pre></div> <h3 id=proxy-buffers-number>Proxy buffers Number<a class=headerlink href=#proxy-buffers-number title="Permanent link"> ¶</a></h3> <p>Sets the number of the buffers in <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers><code>proxy_buffers</code></a> used for reading the first part of the response received from the proxied server. By default proxy buffers number is set as 4</p> <p>To configure this setting globally, set <code>proxy-buffers-number</code> in <a href=../configmap/#proxy-buffers-number>NGINX ConfigMap</a>. To use custom values in an Ingress rule, define this annotation: <div class=highlight><pre><span></span><code><span class=nt>nginx.ingress.kubernetes.io/proxy-buffers-number</span><span class=p>:</span><span class=w> </span><span class=s>&quot;4&quot;</span>
 </code></pre></div></p> <h3 id=proxy-buffer-size>Proxy buffer size<a class=headerlink href=#proxy-buffer-size title="Permanent link"> ¶</a></h3> <p>Sets the size of the buffer <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size><code>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>proxy-buffer-size</code> in <a href=../configmap/#proxy-buffer-size>NGINX ConfigMap</a>. To use custom values in an Ingress rule, define this annotation: <div class=highlight><pre><span></span><code><span class=nt>nginx.ingress.kubernetes.io/proxy-buffer-size</span><span class=p>:</span><span class=w> </span><span class=s>&quot;8k&quot;</span>
diff --git a/user-guide/nginx-configuration/configmap/index.html b/user-guide/nginx-configuration/configmap/index.html
index ab6c2b416..15ae9367a 100644
--- a/user-guide/nginx-configuration/configmap/index.html
+++ b/user-guide/nginx-configuration/configmap/index.html
@@ -12,7 +12,7 @@
 <span class=w>  </span><span class=nt>&quot;remote_user&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$remote_user&quot;</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;bytes_sent&quot;</span><span class=p>:</span><span class=w> </span><span class=err>$by</span><span class=kc>tes</span><span class=err>_se</span><span class=kc>nt</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;request_time&quot;</span><span class=p>:</span><span class=w> </span><span class=err>$reques</span><span class=kc>t</span><span class=err>_</span><span class=kc>t</span><span class=err>ime</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;status&quot;</span><span class=p>:</span><span class=w> </span><span class=err>$s</span><span class=kc>tatus</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;vhost&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$host&quot;</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;request_proto&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$server_protocol&quot;</span><span class=p>,</span>
 <span class=w>  </span><span class=nt>&quot;path&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$uri&quot;</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;request_query&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$args&quot;</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;request_length&quot;</span><span class=p>:</span><span class=w> </span><span class=err>$reques</span><span class=kc>t</span><span class=err>_le</span><span class=kc>n</span><span class=err>g</span><span class=kc>t</span><span class=err>h</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;duration&quot;</span><span class=p>:</span><span class=w> </span><span class=err>$reques</span><span class=kc>t</span><span class=err>_</span><span class=kc>t</span><span class=err>ime</span><span class=p>,</span><span class=nt>&quot;method&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$request_method&quot;</span><span class=p>,</span><span class=w> </span><span class=nt>&quot;http_referrer&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$http_referer&quot;</span><span class=p>,</span>
 <span class=w>  </span><span class=nt>&quot;http_user_agent&quot;</span><span class=p>:</span><span class=w> </span><span class=s2>&quot;$http_user_agent&quot;</span><span class=w> </span><span class=p>}</span><span class=err>&#39;</span>
-</code></pre></div> <p>Please check the <a href=../log-format/ >log-format</a> for definition of each field.</p> <h2 id=log-format-stream>log-format-stream<a class=headerlink href=#log-format-stream title="Permanent link"> ¶</a></h2> <p>Sets the nginx <a href=https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format>stream format</a>.</p> <h2 id=enable-multi-accept>enable-multi-accept<a class=headerlink href=#enable-multi-accept title="Permanent link"> ¶</a></h2> <p>If disabled, a worker process will accept one new connection at a time. Otherwise, a worker process will accept all new connections at a time. <em><strong>default:</strong></em> true</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/ngx_core_module.html#multi_accept>https://nginx.org/en/docs/ngx_core_module.html#multi_accept</a></p> <h2 id=max-worker-connections>max-worker-connections<a class=headerlink href=#max-worker-connections title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_connections>maximum number of simultaneous connections</a> that can be opened by each worker process. 0 will use the value of <a href=#max-worker-open-files>max-worker-open-files</a>. <em><strong>default:</strong></em> 16384</p> <div class="admonition tip"> <p class=admonition-title>Tip</p> <p>Using 0 in scenarios of high load improves performance at the cost of increasing RAM utilization (even on idle).</p> </div> <h2 id=max-worker-open-files>max-worker-open-files<a class=headerlink href=#max-worker-open-files title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile>maximum number of files</a> that can be opened by each worker process. The default of 0 means "max open files (system's limit) - 1024". <em><strong>default:</strong></em> 0</p> <h2 id=map-hash-bucket-size>map-hash-bucket-size<a class=headerlink href=#map-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the bucket size for the <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_bucket_size>map variables hash tables</a>. The details of setting up hash tables are provided in a separate <a href=https://nginx.org/en/docs/hash.html>document</a>.</p> <h2 id=proxy-real-ip-cidr>proxy-real-ip-cidr<a class=headerlink href=#proxy-real-ip-cidr title="Permanent link"> ¶</a></h2> <p>If <code>use-forwarded-headers</code> or <code>use-proxy-protocol</code> is enabled, <code>proxy-real-ip-cidr</code> defines the default IP/network address of your external load balancer. Can be a comma-separated list of CIDR blocks. <em><strong>default:</strong></em> "0.0.0.0/0"</p> <h2 id=proxy-set-headers>proxy-set-headers<a class=headerlink href=#proxy-set-headers title="Permanent link"> ¶</a></h2> <p>Sets custom headers from named configmap before sending traffic to backends. The value format is namespace/name. See <a href=https://kubernetes.github.io/ingress-nginx/examples/customization/custom-headers/ >example</a></p> <h2 id=server-name-hash-max-size>server-name-hash-max-size<a class=headerlink href=#server-name-hash-max-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum size of the <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size>server names hash tables</a> used in server names,map directive’s values, MIME types, names of request header strings, etc.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></p> <h2 id=server-name-hash-bucket-size>server-name-hash-bucket-size<a class=headerlink href=#server-name-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the bucket for the server names hash tables.</p> <p><em>References:</em></p> <ul> <li><a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size>https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size</a></li> </ul> <h2 id=proxy-headers-hash-max-size>proxy-headers-hash-max-size<a class=headerlink href=#proxy-headers-hash-max-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum size of the proxy headers hash tables.</p> <p><em>References:</em></p> <ul> <li><a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size</a></li> </ul> <h2 id=reuse-port>reuse-port<a class=headerlink href=#reuse-port title="Permanent link"> ¶</a></h2> <p>Instructs NGINX to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes <em><strong>default:</strong></em> true</p> <h2 id=proxy-headers-hash-bucket-size>proxy-headers-hash-bucket-size<a class=headerlink href=#proxy-headers-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the bucket for the proxy headers hash tables.</p> <p><em>References:</em></p> <ul> <li><a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size</a></li> </ul> <h2 id=plugins>plugins<a class=headerlink href=#plugins title="Permanent link"> ¶</a></h2> <p>Activates plugins installed in <code>/etc/nginx/lua/plugins</code>. Refer to <a href=https://github.com/kubernetes/ingress-nginx/blob/main/rootfs/etc/nginx/lua/plugins/README.md>ingress-nginx plugins README</a> for more information on how to write and install a plugin.</p> <h2 id=server-tokens>server-tokens<a class=headerlink href=#server-tokens title="Permanent link"> ¶</a></h2> <p>Send NGINX Server header in responses and display NGINX version in error pages. <em><strong>default:</strong></em> is disabled</p> <h2 id=ssl-ciphers>ssl-ciphers<a class=headerlink href=#ssl-ciphers title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers>ciphers</a> list to enable. The ciphers are specified in the format understood by the OpenSSL library.</p> <p>The default cipher list is: <code>ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384</code>.</p> <p>The ordering of a ciphersuite is very important because it decides which algorithms are going to be selected in priority. The recommendation above prioritizes algorithms that provide perfect <a href=https://wiki.mozilla.org/Security/Server_Side_TLS#Forward_Secrecy>forward secrecy</a>.</p> <p>DHE-based cyphers will not be available until DH parameter is configured <a href=https://github.com/kubernetes/ingress-nginx/tree/main/docs/examples/customization/ssl-dh-param>Custom DH parameters for perfect forward secrecy</a></p> <p>Please check the <a href=https://mozilla.github.io/server-side-tls/ssl-config-generator/ >Mozilla SSL Configuration Generator</a>.</p> <p><strong>Note:</strong> ssl_prefer_server_ciphers directive will be enabled by default for http context.</p> <h2 id=ssl-ecdh-curve>ssl-ecdh-curve<a class=headerlink href=#ssl-ecdh-curve title="Permanent link"> ¶</a></h2> <p>Specifies a curve for ECDHE ciphers.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve</a></p> <h2 id=ssl-dh-param>ssl-dh-param<a class=headerlink href=#ssl-dh-param title="Permanent link"> ¶</a></h2> <p>Sets the name of the secret that contains Diffie-Hellman key to help with "Perfect Forward Secrecy".</p> <p><em>References:</em></p> <ul> <li><a href=https://wiki.openssl.org/index.php/Diffie-Hellman_parameters>https://wiki.openssl.org/index.php/Diffie-Hellman_parameters</a></li> <li><a href=https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam>https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam</a></li> </ul> <h2 id=ssl-protocols>ssl-protocols<a class=headerlink href=#ssl-protocols title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols>SSL protocols</a> to use. The default is: <code>TLSv1.2 TLSv1.3</code>.</p> <p>Please check the result of the configuration using <code>https://ssllabs.com/ssltest/analyze.html</code> or <code>https://testssl.sh</code>.</p> <h2 id=ssl-early-data>ssl-early-data<a class=headerlink href=#ssl-early-data title="Permanent link"> ¶</a></h2> <p>Enables or disables TLS 1.3 <a href=https://tools.ietf.org/html/rfc8446#section-2.3>early data</a>, also known as Zero Round Trip Time Resumption (0-RTT).</p> <p>This requires <code>ssl-protocols</code> to have <code>TLSv1.3</code> enabled. Enable this with caution, because requests sent within early data are subject to <a href=https://tools.ietf.org/html/rfc8470>replay attacks</a>.</p> <p><a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data>ssl_early_data</a>. The default is: <code>false</code>.</p> <h2 id=ssl-session-cache>ssl-session-cache<a class=headerlink href=#ssl-session-cache title="Permanent link"> ¶</a></h2> <p>Enables or disables the use of shared <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache>SSL cache</a> among worker processes.</p> <h2 id=ssl-session-cache-size>ssl-session-cache-size<a class=headerlink href=#ssl-session-cache-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache>SSL shared session cache</a> between all worker processes.</p> <h2 id=ssl-session-tickets>ssl-session-tickets<a class=headerlink href=#ssl-session-tickets title="Permanent link"> ¶</a></h2> <p>Enables or disables session resumption through <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets>TLS session tickets</a>.</p> <h2 id=ssl-session-ticket-key>ssl-session-ticket-key<a class=headerlink href=#ssl-session-ticket-key title="Permanent link"> ¶</a></h2> <p>Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string. To create a ticket: <code>openssl rand 80 | openssl enc -A -base64</code></p> <p><a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets>TLS session ticket-key</a>, by default, a randomly generated key is used.</p> <h2 id=ssl-session-timeout>ssl-session-timeout<a class=headerlink href=#ssl-session-timeout title="Permanent link"> ¶</a></h2> <p>Sets the time during which a client may <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout>reuse the session</a> parameters stored in a cache.</p> <h2 id=ssl-buffer-size>ssl-buffer-size<a class=headerlink href=#ssl-buffer-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size>SSL buffer</a> used for sending data. The default of 4k helps NGINX to improve TLS Time To First Byte (TTTFB).</p> <p><em>References:</em> <a href=https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/ >https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/</a></p> <h2 id=use-proxy-protocol>use-proxy-protocol<a class=headerlink href=#use-proxy-protocol title="Permanent link"> ¶</a></h2> <p>Enables or disables the <a href=https://www.nginx.com/resources/admin-guide/proxy-protocol/ >PROXY protocol</a> to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).</p> <h2 id=proxy-protocol-header-timeout>proxy-protocol-header-timeout<a class=headerlink href=#proxy-protocol-header-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout value for receiving the proxy-protocol headers. The default of 5 seconds prevents the TLS passthrough handler from waiting indefinitely on a dropped connection. <em><strong>default:</strong></em> 5s</p> <h2 id=enable-aio-write>enable-aio-write<a class=headerlink href=#enable-aio-write title="Permanent link"> ¶</a></h2> <p>Enables or disables the directive <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#aio_write>aio_write</a> that writes files asynchronously. <em><strong>default:</strong></em> true</p> <h2 id=use-gzip>use-gzip<a class=headerlink href=#use-gzip title="Permanent link"> ¶</a></h2> <p>Enables or disables compression of HTTP responses using the <a href=https://nginx.org/en/docs/http/ngx_http_gzip_module.html>"gzip" module</a>. MIME types to compress are controlled by <a href=#gzip-types>gzip-types</a>. <em><strong>default:</strong></em> false</p> <h2 id=use-geoip>use-geoip<a class=headerlink href=#use-geoip title="Permanent link"> ¶</a></h2> <p>Enables or disables <a href=https://nginx.org/en/docs/http/ngx_http_geoip_module.html>"geoip" module</a> that creates variables with values depending on the client IP address, using the precompiled MaxMind databases. <em><strong>default:</strong></em> true</p> <blockquote> <p><strong>Note:</strong> MaxMind legacy databases are discontinued and will not receive updates after 2019-01-02, cf. <a href=https://support.maxmind.com/geolite-legacy-discontinuation-notice/ >discontinuation notice</a>. Consider <a href=#use-geoip2>use-geoip2</a> below.</p> </blockquote> <h2 id=use-geoip2>use-geoip2<a class=headerlink href=#use-geoip2 title="Permanent link"> ¶</a></h2> <p>Enables the <a href=https://github.com/leev/ngx_http_geoip2_module>geoip2 module</a> for NGINX. Since <code>0.27.0</code> and due to a <a href=https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases>change in the MaxMind databases</a> a license is required to have access to the databases. For this reason, it is required to define a new flag <code>--maxmind-license-key</code> in the ingress controller deployment to download the databases needed during the initialization of the ingress controller. Alternatively, it is possible to use a volume to mount the files <code>/etc/ingress-controller/geoip/GeoLite2-City.mmdb</code> and <code>/etc/ingress-controller/geoip/GeoLite2-ASN.mmdb</code>, avoiding the overhead of the download.</p> <div class="admonition important"> <p class=admonition-title>Important</p> <p>If the feature is enabled but the files are missing, GeoIP2 will not be enabled.</p> </div> <p><em><strong>default:</strong></em> false</p> <h2 id=geoip2-autoreload-in-minutes>geoip2-autoreload-in-minutes<a class=headerlink href=#geoip2-autoreload-in-minutes title="Permanent link"> ¶</a></h2> <p>Enables the <a href=https://github.com/leev/ngx_http_geoip2_module>geoip2 module</a> autoreload in MaxMind databases setting the interval in minutes.</p> <p><em><strong>default:</strong></em> 0</p> <h2 id=enable-brotli>enable-brotli<a class=headerlink href=#enable-brotli title="Permanent link"> ¶</a></h2> <p>Enables or disables compression of HTTP responses using the <a href=https://github.com/google/ngx_brotli>"brotli" module</a>. The default mime type list to compress is: <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>. <em><strong>default:</strong></em> false</p> <blockquote> <p><strong>Note:</strong> Brotli does not works in Safari &lt; 11. For more information see <a href="https://caniuse.com/#feat=brotli">https://caniuse.com/#feat=brotli</a></p> </blockquote> <h2 id=brotli-level>brotli-level<a class=headerlink href=#brotli-level title="Permanent link"> ¶</a></h2> <p>Sets the Brotli Compression Level that will be used. <em><strong>default:</strong></em> 4</p> <h2 id=brotli-min-length>brotli-min-length<a class=headerlink href=#brotli-min-length title="Permanent link"> ¶</a></h2> <p>Minimum length of responses, in bytes, that will be eligible for brotli compression. <em><strong>default:</strong></em> 20</p> <h2 id=brotli-types>brotli-types<a class=headerlink href=#brotli-types title="Permanent link"> ¶</a></h2> <p>Sets the MIME Types that will be compressed on-the-fly by brotli. <em><strong>default:</strong></em> <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code></p> <h2 id=use-http2>use-http2<a class=headerlink href=#use-http2 title="Permanent link"> ¶</a></h2> <p>Enables or disables <a href=https://nginx.org/en/docs/http/ngx_http_v2_module.html>HTTP/2</a> support in secure connections.</p> <h2 id=gzip-disable>gzip-disable<a class=headerlink href=#gzip-disable title="Permanent link"> ¶</a></h2> <p>Disables <a href=http://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_disable>gzipping</a> of responses for requests with "User-Agent" header fields matching any of the specified regular expressions.</p> <h2 id=gzip-level>gzip-level<a class=headerlink href=#gzip-level title="Permanent link"> ¶</a></h2> <p>Sets the gzip Compression Level that will be used. <em><strong>default:</strong></em> 1</p> <h2 id=gzip-min-length>gzip-min-length<a class=headerlink href=#gzip-min-length title="Permanent link"> ¶</a></h2> <p>Minimum length of responses to be returned to the client before it is eligible for gzip compression, in bytes. <em><strong>default:</strong></em> 256</p> <h2 id=gzip-types>gzip-types<a class=headerlink href=#gzip-types title="Permanent link"> ¶</a></h2> <p>Sets the MIME types in addition to "text/html" to compress. The special value "*" matches any MIME type. Responses with the "text/html" type are always compressed if <a href=#use-gzip><code>use-gzip</code></a> is enabled. <em><strong>default:</strong></em> <code>application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>.</p> <h2 id=worker-processes>worker-processes<a class=headerlink href=#worker-processes title="Permanent link"> ¶</a></h2> <p>Sets the number of <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_processes>worker processes</a>. The default of "auto" means number of available CPU cores.</p> <h2 id=worker-cpu-affinity>worker-cpu-affinity<a class=headerlink href=#worker-cpu-affinity title="Permanent link"> ¶</a></h2> <p>Binds worker processes to the sets of CPUs. <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity>worker_cpu_affinity</a>. By default worker processes are not bound to any specific CPUs. The value can be:</p> <ul> <li>"": empty string indicate no affinity is applied.</li> <li>cpumask: e.g. <code>0001 0010 0100 1000</code> to bind processes to specific cpus.</li> <li>auto: binding worker processes automatically to available CPUs.</li> </ul> <h2 id=worker-shutdown-timeout>worker-shutdown-timeout<a class=headerlink href=#worker-shutdown-timeout title="Permanent link"> ¶</a></h2> <p>Sets a timeout for Nginx to <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout>wait for worker to gracefully shutdown</a>. <em><strong>default:</strong></em> "240s"</p> <h2 id=load-balance>load-balance<a class=headerlink href=#load-balance title="Permanent link"> ¶</a></h2> <p>Sets the algorithm to use for load balancing. The value can either be:</p> <ul> <li>round_robin: to use the default round robin loadbalancer</li> <li>ewma: to use the Peak EWMA method for routing (<a href=https://github.com/kubernetes/ingress-nginx/blob/main/rootfs/etc/nginx/lua/balancer/ewma.lua>implementation</a>)</li> </ul> <p>The default is <code>round_robin</code>.</p> <ul> <li>To load balance using consistent hashing of IP or other variables, consider the <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> annotation.</li> <li>To load balance using session cookies, consider the <code>nginx.ingress.kubernetes.io/affinity</code> annotation.</li> </ul> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/load_balancing.html>https://nginx.org/en/docs/http/load_balancing.html</a></p> <h2 id=variables-hash-bucket-size>variables-hash-bucket-size<a class=headerlink href=#variables-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the bucket size for the variables hash table.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size>https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size</a></p> <h2 id=variables-hash-max-size>variables-hash-max-size<a class=headerlink href=#variables-hash-max-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum size of the variables hash table.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size>https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size</a></p> <h2 id=upstream-keepalive-connections>upstream-keepalive-connections<a class=headerlink href=#upstream-keepalive-connections title="Permanent link"> ¶</a></h2> <p>Activates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed. <em><strong>default:</strong></em> 320</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive>https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive</a></p> <h2 id=upstream-keepalive-time>upstream-keepalive-time<a class=headerlink href=#upstream-keepalive-time title="Permanent link"> ¶</a></h2> <p>Sets the maximum time during which requests can be processed through one keepalive connection. <em><strong>default:</strong></em> "1h"</p> <p><em>References:</em> <a href=http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time>http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time</a></p> <h2 id=upstream-keepalive-timeout>upstream-keepalive-timeout<a class=headerlink href=#upstream-keepalive-timeout title="Permanent link"> ¶</a></h2> <p>Sets a timeout during which an idle keepalive connection to an upstream server will stay open. <em><strong>default:</strong></em> 60</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout>https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout</a></p> <h2 id=upstream-keepalive-requests>upstream-keepalive-requests<a class=headerlink href=#upstream-keepalive-requests title="Permanent link"> ¶</a></h2> <p>Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of requests is made, the connection is closed. <em><strong>default:</strong></em> 10000</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests>https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests</a></p> <h2 id=limit-conn-zone-variable>limit-conn-zone-variable<a class=headerlink href=#limit-conn-zone-variable title="Permanent link"> ¶</a></h2> <p>Sets parameters for a shared memory zone that will keep states for various keys of <a href=https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone>limit_conn_zone</a>. The default of "$binary_remote_addr" variable’s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.</p> <h2 id=proxy-stream-timeout>proxy-stream-timeout<a class=headerlink href=#proxy-stream-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout</a></p> <h2 id=proxy-stream-next-upstream>proxy-stream-next-upstream<a class=headerlink href=#proxy-stream-next-upstream title="Permanent link"> ¶</a></h2> <p>When a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream</a></p> <h2 id=proxy-stream-next-upstream-timeout>proxy-stream-next-upstream-timeout<a class=headerlink href=#proxy-stream-next-upstream-timeout title="Permanent link"> ¶</a></h2> <p>Limits the time allowed to pass a connection to the next server. The 0 value turns off this limitation.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout</a></p> <h2 id=proxy-stream-next-upstream-tries>proxy-stream-next-upstream-tries<a class=headerlink href=#proxy-stream-next-upstream-tries title="Permanent link"> ¶</a></h2> <p>Limits the number of possible tries a request should be passed to the next server. The 0 value turns off this limitation.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_tries</a></p> <h2 id=proxy-stream-responses>proxy-stream-responses<a class=headerlink href=#proxy-stream-responses title="Permanent link"> ¶</a></h2> <p>Sets the number of datagrams expected from the proxied server in response to the client request if the UDP protocol is used.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses</a></p> <h2 id=bind-address>bind-address<a class=headerlink href=#bind-address title="Permanent link"> ¶</a></h2> <p>Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.</p> <h2 id=use-forwarded-headers>use-forwarded-headers<a class=headerlink href=#use-forwarded-headers title="Permanent link"> ¶</a></h2> <p>If true, NGINX passes the incoming <code>X-Forwarded-*</code> headers to upstreams. Use this option when NGINX is behind another L7 proxy / load balancer that is setting these headers.</p> <p>If false, NGINX ignores incoming <code>X-Forwarded-*</code> headers, filling them with the request information it sees. Use this option if NGINX is exposed directly to the internet, or it's behind a L3/packet-based load balancer that doesn't alter the source IP in the packets.</p> <h2 id=enable-real-ip>enable-real-ip<a class=headerlink href=#enable-real-ip title="Permanent link"> ¶</a></h2> <p><code>enable-real-ip</code> enables the configuration of <a href=https://nginx.org/en/docs/http/ngx_http_realip_module.html>https://nginx.org/en/docs/http/ngx_http_realip_module.html</a>. Specific attributes of the module can be configured further by using <code>forwarded-for-header</code> and <code>proxy-real-ip-cidr</code> settings.</p> <h2 id=forwarded-for-header>forwarded-for-header<a class=headerlink href=#forwarded-for-header title="Permanent link"> ¶</a></h2> <p>Sets the header field for identifying the originating IP address of a client. <em><strong>default:</strong></em> X-Forwarded-For</p> <h2 id=compute-full-forwarded-for>compute-full-forwarded-for<a class=headerlink href=#compute-full-forwarded-for title="Permanent link"> ¶</a></h2> <p>Append the remote address to the X-Forwarded-For header instead of replacing it. When this option is enabled, the upstream application is responsible for extracting the client IP based on its own list of trusted proxies.</p> <h2 id=proxy-add-original-uri-header>proxy-add-original-uri-header<a class=headerlink href=#proxy-add-original-uri-header title="Permanent link"> ¶</a></h2> <p>Adds an X-Original-Uri header with the original request URI to the backend request</p> <h2 id=generate-request-id>generate-request-id<a class=headerlink href=#generate-request-id title="Permanent link"> ¶</a></h2> <p>Ensures that X-Request-ID is defaulted to a random value, if no X-Request-ID is present in the request</p> <h2 id=jaeger-collector-host>jaeger-collector-host<a class=headerlink href=#jaeger-collector-host title="Permanent link"> ¶</a></h2> <p>Specifies the host to use when uploading traces. It must be a valid URL.</p> <h2 id=jaeger-collector-port>jaeger-collector-port<a class=headerlink href=#jaeger-collector-port title="Permanent link"> ¶</a></h2> <p>Specifies the port to use when uploading traces. <em><strong>default:</strong></em> 6831</p> <h2 id=jaeger-endpoint>jaeger-endpoint<a class=headerlink href=#jaeger-endpoint title="Permanent link"> ¶</a></h2> <p>Specifies the endpoint to use when uploading traces to a collector. This takes priority over <code>jaeger-collector-host</code> if both are specified.</p> <h2 id=jaeger-service-name>jaeger-service-name<a class=headerlink href=#jaeger-service-name title="Permanent link"> ¶</a></h2> <p>Specifies the service name to use for any traces created. <em><strong>default:</strong></em> nginx</p> <h2 id=jaeger-propagation-format>jaeger-propagation-format<a class=headerlink href=#jaeger-propagation-format title="Permanent link"> ¶</a></h2> <p>Specifies the traceparent/tracestate propagation format. <em><strong>default:</strong></em> jaeger</p> <h2 id=jaeger-sampler-type>jaeger-sampler-type<a class=headerlink href=#jaeger-sampler-type title="Permanent link"> ¶</a></h2> <p>Specifies the sampler to be used when sampling traces. The available samplers are: const, probabilistic, ratelimiting, remote. <em><strong>default:</strong></em> const</p> <h2 id=jaeger-sampler-param>jaeger-sampler-param<a class=headerlink href=#jaeger-sampler-param title="Permanent link"> ¶</a></h2> <p>Specifies the argument to be passed to the sampler constructor. Must be a number. For const this should be 0 to never sample and 1 to always sample. <em><strong>default:</strong></em> 1</p> <h2 id=jaeger-sampler-host>jaeger-sampler-host<a class=headerlink href=#jaeger-sampler-host title="Permanent link"> ¶</a></h2> <p>Specifies the custom remote sampler host to be passed to the sampler constructor. Must be a valid URL. Leave blank to use default value (localhost). <em><strong>default:</strong></em> http://127.0.0.1</p> <h2 id=jaeger-sampler-port>jaeger-sampler-port<a class=headerlink href=#jaeger-sampler-port title="Permanent link"> ¶</a></h2> <p>Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. <em><strong>default:</strong></em> 5778</p> <h2 id=jaeger-trace-context-header-name>jaeger-trace-context-header-name<a class=headerlink href=#jaeger-trace-context-header-name title="Permanent link"> ¶</a></h2> <p>Specifies the header name used for passing trace context. <em><strong>default:</strong></em> uber-trace-id</p> <h2 id=jaeger-debug-header>jaeger-debug-header<a class=headerlink href=#jaeger-debug-header title="Permanent link"> ¶</a></h2> <p>Specifies the header name used for force sampling. <em><strong>default:</strong></em> jaeger-debug-id</p> <h2 id=jaeger-baggage-header>jaeger-baggage-header<a class=headerlink href=#jaeger-baggage-header title="Permanent link"> ¶</a></h2> <p>Specifies the header name used to submit baggage if there is no root span. <em><strong>default:</strong></em> jaeger-baggage</p> <h2 id=jaeger-tracer-baggage-header-prefix>jaeger-tracer-baggage-header-prefix<a class=headerlink href=#jaeger-tracer-baggage-header-prefix title="Permanent link"> ¶</a></h2> <p>Specifies the header prefix used to propagate baggage. <em><strong>default:</strong></em> uberctx-</p> <h2 id=datadog-collector-host>datadog-collector-host<a class=headerlink href=#datadog-collector-host title="Permanent link"> ¶</a></h2> <p>Specifies the datadog agent host to use when uploading traces. It must be a valid URL.</p> <h2 id=datadog-collector-port>datadog-collector-port<a class=headerlink href=#datadog-collector-port title="Permanent link"> ¶</a></h2> <p>Specifies the port to use when uploading traces. <em><strong>default:</strong></em> 8126</p> <h2 id=datadog-service-name>datadog-service-name<a class=headerlink href=#datadog-service-name title="Permanent link"> ¶</a></h2> <p>Specifies the service name to use for any traces created. <em><strong>default:</strong></em> nginx</p> <h2 id=datadog-environment>datadog-environment<a class=headerlink href=#datadog-environment title="Permanent link"> ¶</a></h2> <p>Specifies the environment this trace belongs to. <em><strong>default:</strong></em> prod</p> <h2 id=datadog-operation-name-override>datadog-operation-name-override<a class=headerlink href=#datadog-operation-name-override title="Permanent link"> ¶</a></h2> <p>Overrides the operation name to use for any traces crated. <em><strong>default:</strong></em> nginx.handle</p> <h2 id=datadog-priority-sampling>datadog-priority-sampling<a class=headerlink href=#datadog-priority-sampling title="Permanent link"> ¶</a></h2> <p>Specifies to use client-side sampling. If true disables client-side sampling (thus ignoring <code>sample_rate</code>) and enables distributed priority sampling, where traces are sampled based on a combination of user-assigned priorities and configuration from the agent. <em><strong>default:</strong></em> true</p> <h2 id=datadog-sample-rate>datadog-sample-rate<a class=headerlink href=#datadog-sample-rate title="Permanent link"> ¶</a></h2> <p>Specifies sample rate for any traces created. This is effective only when <code>datadog-priority-sampling</code> is <code>false</code> <em><strong>default:</strong></em> 1.0</p> <h2 id=enable-opentelemetry>enable-opentelemetry<a class=headerlink href=#enable-opentelemetry title="Permanent link"> ¶</a></h2> <p>Enables the nginx OpenTelemetry extension. <em><strong>default:</strong></em> is disabled</p> <p><em>References:</em> <a href=https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/nginx>https://github.com/open-telemetry/opentelemetry-cpp-contrib</a></p> <h2 id=opentelemetry-operation-name>opentelemetry-operation-name<a class=headerlink href=#opentelemetry-operation-name title="Permanent link"> ¶</a></h2> <p>Specifies a custom name for the server span. <em><strong>default:</strong></em> is empty</p> <p>For example, set to "HTTP $request_method $uri".</p> <h2 id=otlp-collector-host>otlp-collector-host<a class=headerlink href=#otlp-collector-host title="Permanent link"> ¶</a></h2> <p>Specifies the host to use when uploading traces. It must be a valid URL.</p> <h2 id=otlp-collector-port>otlp-collector-port<a class=headerlink href=#otlp-collector-port title="Permanent link"> ¶</a></h2> <p>Specifies the port to use when uploading traces. <em><strong>default:</strong></em> 4317</p> <h2 id=otel-service-name>otel-service-name<a class=headerlink href=#otel-service-name title="Permanent link"> ¶</a></h2> <p>Specifies the service name to use for any traces created. <em><strong>default:</strong></em> nginx</p> <h2 id=opentelemetry-trust-incoming-span-true>opentelemetry-trust-incoming-span: "true"<a class=headerlink href=#opentelemetry-trust-incoming-span-true title="Permanent link"> ¶</a></h2> <p>Enables or disables using spans from incoming requests as parent for created ones. <em><strong>default:</strong></em> true</p> <h2 id=otel-sampler-parent-based>otel-sampler-parent-based<a class=headerlink href=#otel-sampler-parent-based title="Permanent link"> ¶</a></h2> <p>Uses sampler implementation which by default will take a sample if parent Activity is sampled. <em><strong>default:</strong></em> false</p> <h2 id=otel-sampler-ratio>otel-sampler-ratio<a class=headerlink href=#otel-sampler-ratio title="Permanent link"> ¶</a></h2> <p>Specifies sample rate for any traces created. <em><strong>default:</strong></em> 0.01</p> <h2 id=otel-sampler>otel-sampler<a class=headerlink href=#otel-sampler title="Permanent link"> ¶</a></h2> <p>Specifies the sampler to be used when sampling traces. The available samplers are: AlwaysOff, AlwaysOn, TraceIdRatioBased, remote. <em><strong>default:</strong></em> AlwaysOff</p> <h2 id=main-snippet>main-snippet<a class=headerlink href=#main-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to the main section of the nginx configuration.</p> <h2 id=http-snippet>http-snippet<a class=headerlink href=#http-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to the http section of the nginx configuration.</p> <h2 id=server-snippet>server-snippet<a class=headerlink href=#server-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to all the servers in the nginx configuration.</p> <h2 id=stream-snippet>stream-snippet<a class=headerlink href=#stream-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to the stream section of the nginx configuration.</p> <h2 id=location-snippet>location-snippet<a class=headerlink href=#location-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to all the locations in the nginx configuration.</p> <p>You can not use this to add new locations that proxy to the Kubernetes pods, as the snippet does not have access to the Go template functions. If you want to add custom locations you will have to <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/custom-template/ >provide your own nginx.tmpl</a>.</p> <h2 id=custom-http-errors>custom-http-errors<a class=headerlink href=#custom-http-errors title="Permanent link"> ¶</a></h2> <p>Enables which HTTP codes should be passed for processing with the <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page>error_page directive</a></p> <p>Setting at least one code also enables <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_intercept_errors>proxy_intercept_errors</a> which are required to process error_page.</p> <p>Example usage: <code>custom-http-errors: 404,415</code></p> <h2 id=proxy-body-size>proxy-body-size<a class=headerlink href=#proxy-body-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum allowed size of the client request body. See NGINX <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>client_max_body_size</a>.</p> <h2 id=proxy-connect-timeout>proxy-connect-timeout<a class=headerlink href=#proxy-connect-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout>establishing a connection with a proxied server</a>. It should be noted that this timeout cannot usually exceed 75 seconds.</p> <h2 id=proxy-read-timeout>proxy-read-timeout<a class=headerlink href=#proxy-read-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout in seconds for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout>reading a response from the proxied server</a>. The timeout is set only between two successive read operations, not for the transmission of the whole response.</p> <h2 id=proxy-send-timeout>proxy-send-timeout<a class=headerlink href=#proxy-send-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout in seconds for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout>transmitting a request to the proxied server</a>. The timeout is set only between two successive write operations, not for the transmission of the whole request.</p> <h2 id=proxy-buffers-number>proxy-buffers-number<a class=headerlink href=#proxy-buffers-number title="Permanent link"> ¶</a></h2> <p>Sets the number of the buffer used for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers>reading the first part of the response</a> received from the proxied server. This part usually contains a small response header.</p> <h2 id=proxy-buffer-size>proxy-buffer-size<a class=headerlink href=#proxy-buffer-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the buffer used for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size>reading the first part of the response</a> received from the proxied server. This part usually contains a small response header.</p> <h2 id=proxy-cookie-path>proxy-cookie-path<a class=headerlink href=#proxy-cookie-path title="Permanent link"> ¶</a></h2> <p>Sets a text that <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_path>should be changed in the path attribute</a> of the “Set-Cookie” header fields of a proxied server response.</p> <h2 id=proxy-cookie-domain>proxy-cookie-domain<a class=headerlink href=#proxy-cookie-domain title="Permanent link"> ¶</a></h2> <p>Sets a text that <a href=https://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> <h2 id=proxy-next-upstream>proxy-next-upstream<a class=headerlink href=#proxy-next-upstream title="Permanent link"> ¶</a></h2> <p>Specifies in <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream>which cases</a> a request should be passed to the next server.</p> <h2 id=proxy-next-upstream-timeout>proxy-next-upstream-timeout<a class=headerlink href=#proxy-next-upstream-timeout title="Permanent link"> ¶</a></h2> <p><a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_timeout>Limits the time</a> in seconds during which a request can be passed to the next server.</p> <h2 id=proxy-next-upstream-tries>proxy-next-upstream-tries<a class=headerlink href=#proxy-next-upstream-tries title="Permanent link"> ¶</a></h2> <p>Limit the number of <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_tries>possible tries</a> a request should be passed to the next server.</p> <h2 id=proxy-redirect-from>proxy-redirect-from<a class=headerlink href=#proxy-redirect-from title="Permanent link"> ¶</a></h2> <p>Sets the original text that should be changed in the "Location" and "Refresh" header fields of a proxied server response. <em><strong>default:</strong></em> off</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect</a></p> <h2 id=proxy-request-buffering>proxy-request-buffering<a class=headerlink href=#proxy-request-buffering title="Permanent link"> ¶</a></h2> <p>Enables or disables <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering>buffering of a client request body</a>.</p> <h2 id=ssl-redirect>ssl-redirect<a class=headerlink href=#ssl-redirect title="Permanent link"> ¶</a></h2> <p>Sets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule). <em><strong>default:</strong></em> "true"</p> <h2 id=force-ssl-redirect>force-ssl-redirect<a class=headerlink href=#force-ssl-redirect title="Permanent link"> ¶</a></h2> <p>Sets the global value of redirects (308) to HTTPS if the server has a default TLS certificate (defined in extra-args). <em><strong>default:</strong></em> "false"</p> <h2 id=denylist-source-range>denylist-source-range<a class=headerlink href=#denylist-source-range title="Permanent link"> ¶</a></h2> <p>Sets the default denylisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See <a href=https://nginx.org/en/docs/http/ngx_http_access_module.html>ngx_http_access_module</a>.</p> <h2 id=whitelist-source-range>whitelist-source-range<a class=headerlink href=#whitelist-source-range title="Permanent link"> ¶</a></h2> <p>Sets the default whitelisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See <a href=https://nginx.org/en/docs/http/ngx_http_access_module.html>ngx_http_access_module</a>.</p> <h2 id=skip-access-log-urls>skip-access-log-urls<a class=headerlink href=#skip-access-log-urls title="Permanent link"> ¶</a></h2> <p>Sets a list of URLs that should not appear in the NGINX access log. This is useful with urls like <code>/health</code> or <code>health-check</code> that make "complex" reading the logs. <em><strong>default:</strong></em> is empty</p> <h2 id=limit-rate>limit-rate<a class=headerlink href=#limit-rate title="Permanent link"> ¶</a></h2> <p>Limits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate>https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate</a></p> <h2 id=limit-rate-after>limit-rate-after<a class=headerlink href=#limit-rate-after title="Permanent link"> ¶</a></h2> <p>Sets the initial amount after which the further transmission of a response to a client will be rate limited.</p> <h2 id=lua-shared-dicts>lua-shared-dicts<a class=headerlink href=#lua-shared-dicts title="Permanent link"> ¶</a></h2> <p>Customize default Lua shared dictionaries or define more. You can use the following syntax to do so:</p> <div class=highlight><pre><span></span><code>lua-shared-dicts: &quot;&lt;my dict name&gt;: &lt;my dict size&gt;, [&lt;my dict name&gt;: &lt;my dict size&gt;], ...&quot;
+</code></pre></div> <p>Please check the <a href=../log-format/ >log-format</a> for definition of each field.</p> <h2 id=log-format-stream>log-format-stream<a class=headerlink href=#log-format-stream title="Permanent link"> ¶</a></h2> <p>Sets the nginx <a href=https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format>stream format</a>.</p> <h2 id=enable-multi-accept>enable-multi-accept<a class=headerlink href=#enable-multi-accept title="Permanent link"> ¶</a></h2> <p>If disabled, a worker process will accept one new connection at a time. Otherwise, a worker process will accept all new connections at a time. <em><strong>default:</strong></em> true</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/ngx_core_module.html#multi_accept>https://nginx.org/en/docs/ngx_core_module.html#multi_accept</a></p> <h2 id=max-worker-connections>max-worker-connections<a class=headerlink href=#max-worker-connections title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_connections>maximum number of simultaneous connections</a> that can be opened by each worker process. 0 will use the value of <a href=#max-worker-open-files>max-worker-open-files</a>. <em><strong>default:</strong></em> 16384</p> <div class="admonition tip"> <p class=admonition-title>Tip</p> <p>Using 0 in scenarios of high load improves performance at the cost of increasing RAM utilization (even on idle).</p> </div> <h2 id=max-worker-open-files>max-worker-open-files<a class=headerlink href=#max-worker-open-files title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile>maximum number of files</a> that can be opened by each worker process. The default of 0 means "max open files (system's limit) - 1024". <em><strong>default:</strong></em> 0</p> <h2 id=map-hash-bucket-size>map-hash-bucket-size<a class=headerlink href=#map-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the bucket size for the <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_bucket_size>map variables hash tables</a>. The details of setting up hash tables are provided in a separate <a href=https://nginx.org/en/docs/hash.html>document</a>.</p> <h2 id=proxy-real-ip-cidr>proxy-real-ip-cidr<a class=headerlink href=#proxy-real-ip-cidr title="Permanent link"> ¶</a></h2> <p>If <code>use-forwarded-headers</code> or <code>use-proxy-protocol</code> is enabled, <code>proxy-real-ip-cidr</code> defines the default IP/network address of your external load balancer. Can be a comma-separated list of CIDR blocks. <em><strong>default:</strong></em> "0.0.0.0/0"</p> <h2 id=proxy-set-headers>proxy-set-headers<a class=headerlink href=#proxy-set-headers title="Permanent link"> ¶</a></h2> <p>Sets custom headers from named configmap before sending traffic to backends. The value format is namespace/name. See <a href=https://kubernetes.github.io/ingress-nginx/examples/customization/custom-headers/ >example</a></p> <h2 id=server-name-hash-max-size>server-name-hash-max-size<a class=headerlink href=#server-name-hash-max-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum size of the <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size>server names hash tables</a> used in server names,map directive’s values, MIME types, names of request header strings, etc.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></p> <h2 id=server-name-hash-bucket-size>server-name-hash-bucket-size<a class=headerlink href=#server-name-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the bucket for the server names hash tables.</p> <p><em>References:</em></p> <ul> <li><a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size>https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size</a></li> </ul> <h2 id=proxy-headers-hash-max-size>proxy-headers-hash-max-size<a class=headerlink href=#proxy-headers-hash-max-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum size of the proxy headers hash tables.</p> <p><em>References:</em></p> <ul> <li><a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size</a></li> </ul> <h2 id=reuse-port>reuse-port<a class=headerlink href=#reuse-port title="Permanent link"> ¶</a></h2> <p>Instructs NGINX to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes <em><strong>default:</strong></em> true</p> <h2 id=proxy-headers-hash-bucket-size>proxy-headers-hash-bucket-size<a class=headerlink href=#proxy-headers-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the bucket for the proxy headers hash tables.</p> <p><em>References:</em></p> <ul> <li><a href=https://nginx.org/en/docs/hash.html>https://nginx.org/en/docs/hash.html</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size</a></li> </ul> <h2 id=plugins>plugins<a class=headerlink href=#plugins title="Permanent link"> ¶</a></h2> <p>Activates plugins installed in <code>/etc/nginx/lua/plugins</code>. Refer to <a href=https://github.com/kubernetes/ingress-nginx/blob/main/rootfs/etc/nginx/lua/plugins/README.md>ingress-nginx plugins README</a> for more information on how to write and install a plugin.</p> <h2 id=server-tokens>server-tokens<a class=headerlink href=#server-tokens title="Permanent link"> ¶</a></h2> <p>Send NGINX Server header in responses and display NGINX version in error pages. <em><strong>default:</strong></em> is disabled</p> <h2 id=ssl-ciphers>ssl-ciphers<a class=headerlink href=#ssl-ciphers title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers>ciphers</a> list to enable. The ciphers are specified in the format understood by the OpenSSL library.</p> <p>The default cipher list is: <code>ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384</code>.</p> <p>The ordering of a ciphersuite is very important because it decides which algorithms are going to be selected in priority. The recommendation above prioritizes algorithms that provide perfect <a href=https://wiki.mozilla.org/Security/Server_Side_TLS#Forward_Secrecy>forward secrecy</a>.</p> <p>DHE-based cyphers will not be available until DH parameter is configured <a href=https://github.com/kubernetes/ingress-nginx/tree/main/docs/examples/customization/ssl-dh-param>Custom DH parameters for perfect forward secrecy</a></p> <p>Please check the <a href=https://mozilla.github.io/server-side-tls/ssl-config-generator/ >Mozilla SSL Configuration Generator</a>.</p> <p><strong>Note:</strong> ssl_prefer_server_ciphers directive will be enabled by default for http context.</p> <h2 id=ssl-ecdh-curve>ssl-ecdh-curve<a class=headerlink href=#ssl-ecdh-curve title="Permanent link"> ¶</a></h2> <p>Specifies a curve for ECDHE ciphers.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve</a></p> <h2 id=ssl-dh-param>ssl-dh-param<a class=headerlink href=#ssl-dh-param title="Permanent link"> ¶</a></h2> <p>Sets the name of the secret that contains Diffie-Hellman key to help with "Perfect Forward Secrecy".</p> <p><em>References:</em></p> <ul> <li><a href=https://wiki.openssl.org/index.php/Diffie-Hellman_parameters>https://wiki.openssl.org/index.php/Diffie-Hellman_parameters</a></li> <li><a href=https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam>https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam</a></li> <li><a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam</a></li> </ul> <h2 id=ssl-protocols>ssl-protocols<a class=headerlink href=#ssl-protocols title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols>SSL protocols</a> to use. The default is: <code>TLSv1.2 TLSv1.3</code>.</p> <p>Please check the result of the configuration using <code>https://ssllabs.com/ssltest/analyze.html</code> or <code>https://testssl.sh</code>.</p> <h2 id=ssl-early-data>ssl-early-data<a class=headerlink href=#ssl-early-data title="Permanent link"> ¶</a></h2> <p>Enables or disables TLS 1.3 <a href=https://tools.ietf.org/html/rfc8446#section-2.3>early data</a>, also known as Zero Round Trip Time Resumption (0-RTT).</p> <p>This requires <code>ssl-protocols</code> to have <code>TLSv1.3</code> enabled. Enable this with caution, because requests sent within early data are subject to <a href=https://tools.ietf.org/html/rfc8470>replay attacks</a>.</p> <p><a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data>ssl_early_data</a>. The default is: <code>false</code>.</p> <h2 id=ssl-session-cache>ssl-session-cache<a class=headerlink href=#ssl-session-cache title="Permanent link"> ¶</a></h2> <p>Enables or disables the use of shared <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache>SSL cache</a> among worker processes.</p> <h2 id=ssl-session-cache-size>ssl-session-cache-size<a class=headerlink href=#ssl-session-cache-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache>SSL shared session cache</a> between all worker processes.</p> <h2 id=ssl-session-tickets>ssl-session-tickets<a class=headerlink href=#ssl-session-tickets title="Permanent link"> ¶</a></h2> <p>Enables or disables session resumption through <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets>TLS session tickets</a>.</p> <h2 id=ssl-session-ticket-key>ssl-session-ticket-key<a class=headerlink href=#ssl-session-ticket-key title="Permanent link"> ¶</a></h2> <p>Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string. To create a ticket: <code>openssl rand 80 | openssl enc -A -base64</code></p> <p><a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets>TLS session ticket-key</a>, by default, a randomly generated key is used.</p> <h2 id=ssl-session-timeout>ssl-session-timeout<a class=headerlink href=#ssl-session-timeout title="Permanent link"> ¶</a></h2> <p>Sets the time during which a client may <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout>reuse the session</a> parameters stored in a cache.</p> <h2 id=ssl-buffer-size>ssl-buffer-size<a class=headerlink href=#ssl-buffer-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size>SSL buffer</a> used for sending data. The default of 4k helps NGINX to improve TLS Time To First Byte (TTTFB).</p> <p><em>References:</em> <a href=https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/ >https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/</a></p> <h2 id=use-proxy-protocol>use-proxy-protocol<a class=headerlink href=#use-proxy-protocol title="Permanent link"> ¶</a></h2> <p>Enables or disables the <a href=https://www.nginx.com/resources/admin-guide/proxy-protocol/ >PROXY protocol</a> to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).</p> <h2 id=proxy-protocol-header-timeout>proxy-protocol-header-timeout<a class=headerlink href=#proxy-protocol-header-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout value for receiving the proxy-protocol headers. The default of 5 seconds prevents the TLS passthrough handler from waiting indefinitely on a dropped connection. <em><strong>default:</strong></em> 5s</p> <h2 id=enable-aio-write>enable-aio-write<a class=headerlink href=#enable-aio-write title="Permanent link"> ¶</a></h2> <p>Enables or disables the directive <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#aio_write>aio_write</a> that writes files asynchronously. <em><strong>default:</strong></em> true</p> <h2 id=use-gzip>use-gzip<a class=headerlink href=#use-gzip title="Permanent link"> ¶</a></h2> <p>Enables or disables compression of HTTP responses using the <a href=https://nginx.org/en/docs/http/ngx_http_gzip_module.html>"gzip" module</a>. MIME types to compress are controlled by <a href=#gzip-types>gzip-types</a>. <em><strong>default:</strong></em> false</p> <h2 id=use-geoip>use-geoip<a class=headerlink href=#use-geoip title="Permanent link"> ¶</a></h2> <p>Enables or disables <a href=https://nginx.org/en/docs/http/ngx_http_geoip_module.html>"geoip" module</a> that creates variables with values depending on the client IP address, using the precompiled MaxMind databases. <em><strong>default:</strong></em> true</p> <blockquote> <p><strong>Note:</strong> MaxMind legacy databases are discontinued and will not receive updates after 2019-01-02, cf. <a href=https://support.maxmind.com/geolite-legacy-discontinuation-notice/ >discontinuation notice</a>. Consider <a href=#use-geoip2>use-geoip2</a> below.</p> </blockquote> <h2 id=use-geoip2>use-geoip2<a class=headerlink href=#use-geoip2 title="Permanent link"> ¶</a></h2> <p>Enables the <a href=https://github.com/leev/ngx_http_geoip2_module>geoip2 module</a> for NGINX. Since <code>0.27.0</code> and due to a <a href=https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases>change in the MaxMind databases</a> a license is required to have access to the databases. For this reason, it is required to define a new flag <code>--maxmind-license-key</code> in the ingress controller deployment to download the databases needed during the initialization of the ingress controller. Alternatively, it is possible to use a volume to mount the files <code>/etc/ingress-controller/geoip/GeoLite2-City.mmdb</code> and <code>/etc/ingress-controller/geoip/GeoLite2-ASN.mmdb</code>, avoiding the overhead of the download.</p> <div class="admonition important"> <p class=admonition-title>Important</p> <p>If the feature is enabled but the files are missing, GeoIP2 will not be enabled.</p> </div> <p><em><strong>default:</strong></em> false</p> <h2 id=geoip2-autoreload-in-minutes>geoip2-autoreload-in-minutes<a class=headerlink href=#geoip2-autoreload-in-minutes title="Permanent link"> ¶</a></h2> <p>Enables the <a href=https://github.com/leev/ngx_http_geoip2_module>geoip2 module</a> autoreload in MaxMind databases setting the interval in minutes.</p> <p><em><strong>default:</strong></em> 0</p> <h2 id=enable-brotli>enable-brotli<a class=headerlink href=#enable-brotli title="Permanent link"> ¶</a></h2> <p>Enables or disables compression of HTTP responses using the <a href=https://github.com/google/ngx_brotli>"brotli" module</a>. The default mime type list to compress is: <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>. <em><strong>default:</strong></em> false</p> <blockquote> <p><strong>Note:</strong> Brotli does not works in Safari &lt; 11. For more information see <a href="https://caniuse.com/#feat=brotli">https://caniuse.com/#feat=brotli</a></p> </blockquote> <h2 id=brotli-level>brotli-level<a class=headerlink href=#brotli-level title="Permanent link"> ¶</a></h2> <p>Sets the Brotli Compression Level that will be used. <em><strong>default:</strong></em> 4</p> <h2 id=brotli-min-length>brotli-min-length<a class=headerlink href=#brotli-min-length title="Permanent link"> ¶</a></h2> <p>Minimum length of responses, in bytes, that will be eligible for brotli compression. <em><strong>default:</strong></em> 20</p> <h2 id=brotli-types>brotli-types<a class=headerlink href=#brotli-types title="Permanent link"> ¶</a></h2> <p>Sets the MIME Types that will be compressed on-the-fly by brotli. <em><strong>default:</strong></em> <code>application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code></p> <h2 id=use-http2>use-http2<a class=headerlink href=#use-http2 title="Permanent link"> ¶</a></h2> <p>Enables or disables <a href=https://nginx.org/en/docs/http/ngx_http_v2_module.html>HTTP/2</a> support in secure connections.</p> <h2 id=gzip-disable>gzip-disable<a class=headerlink href=#gzip-disable title="Permanent link"> ¶</a></h2> <p>Disables <a href=http://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_disable>gzipping</a> of responses for requests with "User-Agent" header fields matching any of the specified regular expressions.</p> <h2 id=gzip-level>gzip-level<a class=headerlink href=#gzip-level title="Permanent link"> ¶</a></h2> <p>Sets the gzip Compression Level that will be used. <em><strong>default:</strong></em> 1</p> <h2 id=gzip-min-length>gzip-min-length<a class=headerlink href=#gzip-min-length title="Permanent link"> ¶</a></h2> <p>Minimum length of responses to be returned to the client before it is eligible for gzip compression, in bytes. <em><strong>default:</strong></em> 256</p> <h2 id=gzip-types>gzip-types<a class=headerlink href=#gzip-types title="Permanent link"> ¶</a></h2> <p>Sets the MIME types in addition to "text/html" to compress. The special value "*" matches any MIME type. Responses with the "text/html" type are always compressed if <a href=#use-gzip><code>use-gzip</code></a> is enabled. <em><strong>default:</strong></em> <code>application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component</code>.</p> <h2 id=worker-processes>worker-processes<a class=headerlink href=#worker-processes title="Permanent link"> ¶</a></h2> <p>Sets the number of <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_processes>worker processes</a>. The default of "auto" means number of available CPU cores.</p> <h2 id=worker-cpu-affinity>worker-cpu-affinity<a class=headerlink href=#worker-cpu-affinity title="Permanent link"> ¶</a></h2> <p>Binds worker processes to the sets of CPUs. <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity>worker_cpu_affinity</a>. By default worker processes are not bound to any specific CPUs. The value can be:</p> <ul> <li>"": empty string indicate no affinity is applied.</li> <li>cpumask: e.g. <code>0001 0010 0100 1000</code> to bind processes to specific cpus.</li> <li>auto: binding worker processes automatically to available CPUs.</li> </ul> <h2 id=worker-shutdown-timeout>worker-shutdown-timeout<a class=headerlink href=#worker-shutdown-timeout title="Permanent link"> ¶</a></h2> <p>Sets a timeout for Nginx to <a href=https://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout>wait for worker to gracefully shutdown</a>. <em><strong>default:</strong></em> "240s"</p> <h2 id=load-balance>load-balance<a class=headerlink href=#load-balance title="Permanent link"> ¶</a></h2> <p>Sets the algorithm to use for load balancing. The value can either be:</p> <ul> <li>round_robin: to use the default round robin loadbalancer</li> <li>ewma: to use the Peak EWMA method for routing (<a href=https://github.com/kubernetes/ingress-nginx/blob/main/rootfs/etc/nginx/lua/balancer/ewma.lua>implementation</a>)</li> </ul> <p>The default is <code>round_robin</code>.</p> <ul> <li>To load balance using consistent hashing of IP or other variables, consider the <code>nginx.ingress.kubernetes.io/upstream-hash-by</code> annotation.</li> <li>To load balance using session cookies, consider the <code>nginx.ingress.kubernetes.io/affinity</code> annotation.</li> </ul> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/load_balancing.html>https://nginx.org/en/docs/http/load_balancing.html</a></p> <h2 id=variables-hash-bucket-size>variables-hash-bucket-size<a class=headerlink href=#variables-hash-bucket-size title="Permanent link"> ¶</a></h2> <p>Sets the bucket size for the variables hash table.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size>https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size</a></p> <h2 id=variables-hash-max-size>variables-hash-max-size<a class=headerlink href=#variables-hash-max-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum size of the variables hash table.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size>https://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size</a></p> <h2 id=upstream-keepalive-connections>upstream-keepalive-connections<a class=headerlink href=#upstream-keepalive-connections title="Permanent link"> ¶</a></h2> <p>Activates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed. <em><strong>default:</strong></em> 320</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive>https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive</a></p> <h2 id=upstream-keepalive-time>upstream-keepalive-time<a class=headerlink href=#upstream-keepalive-time title="Permanent link"> ¶</a></h2> <p>Sets the maximum time during which requests can be processed through one keepalive connection. <em><strong>default:</strong></em> "1h"</p> <p><em>References:</em> <a href=http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time>http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time</a></p> <h2 id=upstream-keepalive-timeout>upstream-keepalive-timeout<a class=headerlink href=#upstream-keepalive-timeout title="Permanent link"> ¶</a></h2> <p>Sets a timeout during which an idle keepalive connection to an upstream server will stay open. <em><strong>default:</strong></em> 60</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout>https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout</a></p> <h2 id=upstream-keepalive-requests>upstream-keepalive-requests<a class=headerlink href=#upstream-keepalive-requests title="Permanent link"> ¶</a></h2> <p>Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of requests is made, the connection is closed. <em><strong>default:</strong></em> 10000</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests>https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests</a></p> <h2 id=limit-conn-zone-variable>limit-conn-zone-variable<a class=headerlink href=#limit-conn-zone-variable title="Permanent link"> ¶</a></h2> <p>Sets parameters for a shared memory zone that will keep states for various keys of <a href=https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone>limit_conn_zone</a>. The default of "$binary_remote_addr" variable’s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.</p> <h2 id=proxy-stream-timeout>proxy-stream-timeout<a class=headerlink href=#proxy-stream-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout</a></p> <h2 id=proxy-stream-next-upstream>proxy-stream-next-upstream<a class=headerlink href=#proxy-stream-next-upstream title="Permanent link"> ¶</a></h2> <p>When a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream</a></p> <h2 id=proxy-stream-next-upstream-timeout>proxy-stream-next-upstream-timeout<a class=headerlink href=#proxy-stream-next-upstream-timeout title="Permanent link"> ¶</a></h2> <p>Limits the time allowed to pass a connection to the next server. The 0 value turns off this limitation.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout</a></p> <h2 id=proxy-stream-next-upstream-tries>proxy-stream-next-upstream-tries<a class=headerlink href=#proxy-stream-next-upstream-tries title="Permanent link"> ¶</a></h2> <p>Limits the number of possible tries a request should be passed to the next server. The 0 value turns off this limitation.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_tries</a></p> <h2 id=proxy-stream-responses>proxy-stream-responses<a class=headerlink href=#proxy-stream-responses title="Permanent link"> ¶</a></h2> <p>Sets the number of datagrams expected from the proxied server in response to the client request if the UDP protocol is used.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses>https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses</a></p> <h2 id=bind-address>bind-address<a class=headerlink href=#bind-address title="Permanent link"> ¶</a></h2> <p>Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.</p> <h2 id=use-forwarded-headers>use-forwarded-headers<a class=headerlink href=#use-forwarded-headers title="Permanent link"> ¶</a></h2> <p>If true, NGINX passes the incoming <code>X-Forwarded-*</code> headers to upstreams. Use this option when NGINX is behind another L7 proxy / load balancer that is setting these headers.</p> <p>If false, NGINX ignores incoming <code>X-Forwarded-*</code> headers, filling them with the request information it sees. Use this option if NGINX is exposed directly to the internet, or it's behind a L3/packet-based load balancer that doesn't alter the source IP in the packets.</p> <h2 id=enable-real-ip>enable-real-ip<a class=headerlink href=#enable-real-ip title="Permanent link"> ¶</a></h2> <p><code>enable-real-ip</code> enables the configuration of <a href=https://nginx.org/en/docs/http/ngx_http_realip_module.html>https://nginx.org/en/docs/http/ngx_http_realip_module.html</a>. Specific attributes of the module can be configured further by using <code>forwarded-for-header</code> and <code>proxy-real-ip-cidr</code> settings.</p> <h2 id=forwarded-for-header>forwarded-for-header<a class=headerlink href=#forwarded-for-header title="Permanent link"> ¶</a></h2> <p>Sets the header field for identifying the originating IP address of a client. <em><strong>default:</strong></em> X-Forwarded-For</p> <h2 id=compute-full-forwarded-for>compute-full-forwarded-for<a class=headerlink href=#compute-full-forwarded-for title="Permanent link"> ¶</a></h2> <p>Append the remote address to the X-Forwarded-For header instead of replacing it. When this option is enabled, the upstream application is responsible for extracting the client IP based on its own list of trusted proxies.</p> <h2 id=proxy-add-original-uri-header>proxy-add-original-uri-header<a class=headerlink href=#proxy-add-original-uri-header title="Permanent link"> ¶</a></h2> <p>Adds an X-Original-Uri header with the original request URI to the backend request</p> <h2 id=generate-request-id>generate-request-id<a class=headerlink href=#generate-request-id title="Permanent link"> ¶</a></h2> <p>Ensures that X-Request-ID is defaulted to a random value, if no X-Request-ID is present in the request</p> <h2 id=jaeger-collector-host>jaeger-collector-host<a class=headerlink href=#jaeger-collector-host title="Permanent link"> ¶</a></h2> <p>Specifies the host to use when uploading traces. It must be a valid URL.</p> <h2 id=jaeger-collector-port>jaeger-collector-port<a class=headerlink href=#jaeger-collector-port title="Permanent link"> ¶</a></h2> <p>Specifies the port to use when uploading traces. <em><strong>default:</strong></em> 6831</p> <h2 id=jaeger-endpoint>jaeger-endpoint<a class=headerlink href=#jaeger-endpoint title="Permanent link"> ¶</a></h2> <p>Specifies the endpoint to use when uploading traces to a collector. This takes priority over <code>jaeger-collector-host</code> if both are specified.</p> <h2 id=jaeger-service-name>jaeger-service-name<a class=headerlink href=#jaeger-service-name title="Permanent link"> ¶</a></h2> <p>Specifies the service name to use for any traces created. <em><strong>default:</strong></em> nginx</p> <h2 id=jaeger-propagation-format>jaeger-propagation-format<a class=headerlink href=#jaeger-propagation-format title="Permanent link"> ¶</a></h2> <p>Specifies the traceparent/tracestate propagation format. <em><strong>default:</strong></em> jaeger</p> <h2 id=jaeger-sampler-type>jaeger-sampler-type<a class=headerlink href=#jaeger-sampler-type title="Permanent link"> ¶</a></h2> <p>Specifies the sampler to be used when sampling traces. The available samplers are: const, probabilistic, ratelimiting, remote. <em><strong>default:</strong></em> const</p> <h2 id=jaeger-sampler-param>jaeger-sampler-param<a class=headerlink href=#jaeger-sampler-param title="Permanent link"> ¶</a></h2> <p>Specifies the argument to be passed to the sampler constructor. Must be a number. For const this should be 0 to never sample and 1 to always sample. <em><strong>default:</strong></em> 1</p> <h2 id=jaeger-sampler-host>jaeger-sampler-host<a class=headerlink href=#jaeger-sampler-host title="Permanent link"> ¶</a></h2> <p>Specifies the custom remote sampler host to be passed to the sampler constructor. Must be a valid URL. Leave blank to use default value (localhost). <em><strong>default:</strong></em> http://127.0.0.1</p> <h2 id=jaeger-sampler-port>jaeger-sampler-port<a class=headerlink href=#jaeger-sampler-port title="Permanent link"> ¶</a></h2> <p>Specifies the custom remote sampler port to be passed to the sampler constructor. Must be a number. <em><strong>default:</strong></em> 5778</p> <h2 id=jaeger-trace-context-header-name>jaeger-trace-context-header-name<a class=headerlink href=#jaeger-trace-context-header-name title="Permanent link"> ¶</a></h2> <p>Specifies the header name used for passing trace context. <em><strong>default:</strong></em> uber-trace-id</p> <h2 id=jaeger-debug-header>jaeger-debug-header<a class=headerlink href=#jaeger-debug-header title="Permanent link"> ¶</a></h2> <p>Specifies the header name used for force sampling. <em><strong>default:</strong></em> jaeger-debug-id</p> <h2 id=jaeger-baggage-header>jaeger-baggage-header<a class=headerlink href=#jaeger-baggage-header title="Permanent link"> ¶</a></h2> <p>Specifies the header name used to submit baggage if there is no root span. <em><strong>default:</strong></em> jaeger-baggage</p> <h2 id=jaeger-tracer-baggage-header-prefix>jaeger-tracer-baggage-header-prefix<a class=headerlink href=#jaeger-tracer-baggage-header-prefix title="Permanent link"> ¶</a></h2> <p>Specifies the header prefix used to propagate baggage. <em><strong>default:</strong></em> uberctx-</p> <h2 id=datadog-collector-host>datadog-collector-host<a class=headerlink href=#datadog-collector-host title="Permanent link"> ¶</a></h2> <p>Specifies the datadog agent host to use when uploading traces. It must be a valid URL.</p> <h2 id=datadog-collector-port>datadog-collector-port<a class=headerlink href=#datadog-collector-port title="Permanent link"> ¶</a></h2> <p>Specifies the port to use when uploading traces. <em><strong>default:</strong></em> 8126</p> <h2 id=datadog-service-name>datadog-service-name<a class=headerlink href=#datadog-service-name title="Permanent link"> ¶</a></h2> <p>Specifies the service name to use for any traces created. <em><strong>default:</strong></em> nginx</p> <h2 id=datadog-environment>datadog-environment<a class=headerlink href=#datadog-environment title="Permanent link"> ¶</a></h2> <p>Specifies the environment this trace belongs to. <em><strong>default:</strong></em> prod</p> <h2 id=datadog-operation-name-override>datadog-operation-name-override<a class=headerlink href=#datadog-operation-name-override title="Permanent link"> ¶</a></h2> <p>Overrides the operation name to use for any traces crated. <em><strong>default:</strong></em> nginx.handle</p> <h2 id=datadog-priority-sampling>datadog-priority-sampling<a class=headerlink href=#datadog-priority-sampling title="Permanent link"> ¶</a></h2> <p>Specifies to use client-side sampling. If true disables client-side sampling (thus ignoring <code>sample_rate</code>) and enables distributed priority sampling, where traces are sampled based on a combination of user-assigned priorities and configuration from the agent. <em><strong>default:</strong></em> true</p> <h2 id=datadog-sample-rate>datadog-sample-rate<a class=headerlink href=#datadog-sample-rate title="Permanent link"> ¶</a></h2> <p>Specifies sample rate for any traces created. This is effective only when <code>datadog-priority-sampling</code> is <code>false</code> <em><strong>default:</strong></em> 1.0</p> <h2 id=enable-opentelemetry>enable-opentelemetry<a class=headerlink href=#enable-opentelemetry title="Permanent link"> ¶</a></h2> <p>Enables the nginx OpenTelemetry extension. <em><strong>default:</strong></em> is disabled</p> <p><em>References:</em> <a href=https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/nginx>https://github.com/open-telemetry/opentelemetry-cpp-contrib</a></p> <h2 id=opentelemetry-operation-name>opentelemetry-operation-name<a class=headerlink href=#opentelemetry-operation-name title="Permanent link"> ¶</a></h2> <p>Specifies a custom name for the server span. <em><strong>default:</strong></em> is empty</p> <p>For example, set to "HTTP $request_method $uri".</p> <h2 id=otlp-collector-host>otlp-collector-host<a class=headerlink href=#otlp-collector-host title="Permanent link"> ¶</a></h2> <p>Specifies the host to use when uploading traces. It must be a valid URL.</p> <h2 id=otlp-collector-port>otlp-collector-port<a class=headerlink href=#otlp-collector-port title="Permanent link"> ¶</a></h2> <p>Specifies the port to use when uploading traces. <em><strong>default:</strong></em> 4317</p> <h2 id=otel-service-name>otel-service-name<a class=headerlink href=#otel-service-name title="Permanent link"> ¶</a></h2> <p>Specifies the service name to use for any traces created. <em><strong>default:</strong></em> nginx</p> <h2 id=opentelemetry-trust-incoming-span-true>opentelemetry-trust-incoming-span: "true"<a class=headerlink href=#opentelemetry-trust-incoming-span-true title="Permanent link"> ¶</a></h2> <p>Enables or disables using spans from incoming requests as parent for created ones. <em><strong>default:</strong></em> true</p> <h2 id=otel-sampler-parent-based>otel-sampler-parent-based<a class=headerlink href=#otel-sampler-parent-based title="Permanent link"> ¶</a></h2> <p>Uses sampler implementation which by default will take a sample if parent Activity is sampled. <em><strong>default:</strong></em> false</p> <h2 id=otel-sampler-ratio>otel-sampler-ratio<a class=headerlink href=#otel-sampler-ratio title="Permanent link"> ¶</a></h2> <p>Specifies sample rate for any traces created. <em><strong>default:</strong></em> 0.01</p> <h2 id=otel-sampler>otel-sampler<a class=headerlink href=#otel-sampler title="Permanent link"> ¶</a></h2> <p>Specifies the sampler to be used when sampling traces. The available samplers are: AlwaysOff, AlwaysOn, TraceIdRatioBased, remote. <em><strong>default:</strong></em> AlwaysOff</p> <h2 id=main-snippet>main-snippet<a class=headerlink href=#main-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to the main section of the nginx configuration.</p> <h2 id=http-snippet>http-snippet<a class=headerlink href=#http-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to the http section of the nginx configuration.</p> <h2 id=server-snippet>server-snippet<a class=headerlink href=#server-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to all the servers in the nginx configuration.</p> <h2 id=stream-snippet>stream-snippet<a class=headerlink href=#stream-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to the stream section of the nginx configuration.</p> <h2 id=location-snippet>location-snippet<a class=headerlink href=#location-snippet title="Permanent link"> ¶</a></h2> <p>Adds custom configuration to all the locations in the nginx configuration.</p> <p>You can not use this to add new locations that proxy to the Kubernetes pods, as the snippet does not have access to the Go template functions. If you want to add custom locations you will have to <a href=https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/custom-template/ >provide your own nginx.tmpl</a>.</p> <h2 id=custom-http-errors>custom-http-errors<a class=headerlink href=#custom-http-errors title="Permanent link"> ¶</a></h2> <p>Enables which HTTP codes should be passed for processing with the <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page>error_page directive</a></p> <p>Setting at least one code also enables <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_intercept_errors>proxy_intercept_errors</a> which are required to process error_page.</p> <p>Example usage: <code>custom-http-errors: 404,415</code></p> <h2 id=proxy-body-size>proxy-body-size<a class=headerlink href=#proxy-body-size title="Permanent link"> ¶</a></h2> <p>Sets the maximum allowed size of the client request body. See NGINX <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>client_max_body_size</a>.</p> <h2 id=proxy-connect-timeout>proxy-connect-timeout<a class=headerlink href=#proxy-connect-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout>establishing a connection with a proxied server</a>. It should be noted that this timeout cannot usually exceed 75 seconds.</p> <p>It will also set the <a href=https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout>grpc_connect_timeout</a> for gRPC connections.</p> <h2 id=proxy-read-timeout>proxy-read-timeout<a class=headerlink href=#proxy-read-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout in seconds for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout>reading a response from the proxied server</a>. The timeout is set only between two successive read operations, not for the transmission of the whole response.</p> <p>It will also set the <a href=https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout>grpc_read_timeout</a> for gRPC connections.</p> <h2 id=proxy-send-timeout>proxy-send-timeout<a class=headerlink href=#proxy-send-timeout title="Permanent link"> ¶</a></h2> <p>Sets the timeout in seconds for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout>transmitting a request to the proxied server</a>. The timeout is set only between two successive write operations, not for the transmission of the whole request.</p> <p>It will also set the <a href=https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout>grpc_send_timeout</a> for gRPC connections.</p> <h2 id=proxy-buffers-number>proxy-buffers-number<a class=headerlink href=#proxy-buffers-number title="Permanent link"> ¶</a></h2> <p>Sets the number of the buffer used for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers>reading the first part of the response</a> received from the proxied server. This part usually contains a small response header.</p> <h2 id=proxy-buffer-size>proxy-buffer-size<a class=headerlink href=#proxy-buffer-size title="Permanent link"> ¶</a></h2> <p>Sets the size of the buffer used for <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size>reading the first part of the response</a> received from the proxied server. This part usually contains a small response header.</p> <h2 id=proxy-cookie-path>proxy-cookie-path<a class=headerlink href=#proxy-cookie-path title="Permanent link"> ¶</a></h2> <p>Sets a text that <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_path>should be changed in the path attribute</a> of the “Set-Cookie” header fields of a proxied server response.</p> <h2 id=proxy-cookie-domain>proxy-cookie-domain<a class=headerlink href=#proxy-cookie-domain title="Permanent link"> ¶</a></h2> <p>Sets a text that <a href=https://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> <h2 id=proxy-next-upstream>proxy-next-upstream<a class=headerlink href=#proxy-next-upstream title="Permanent link"> ¶</a></h2> <p>Specifies in <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream>which cases</a> a request should be passed to the next server.</p> <h2 id=proxy-next-upstream-timeout>proxy-next-upstream-timeout<a class=headerlink href=#proxy-next-upstream-timeout title="Permanent link"> ¶</a></h2> <p><a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_timeout>Limits the time</a> in seconds during which a request can be passed to the next server.</p> <h2 id=proxy-next-upstream-tries>proxy-next-upstream-tries<a class=headerlink href=#proxy-next-upstream-tries title="Permanent link"> ¶</a></h2> <p>Limit the number of <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_tries>possible tries</a> a request should be passed to the next server.</p> <h2 id=proxy-redirect-from>proxy-redirect-from<a class=headerlink href=#proxy-redirect-from title="Permanent link"> ¶</a></h2> <p>Sets the original text that should be changed in the "Location" and "Refresh" header fields of a proxied server response. <em><strong>default:</strong></em> off</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect>https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect</a></p> <h2 id=proxy-request-buffering>proxy-request-buffering<a class=headerlink href=#proxy-request-buffering title="Permanent link"> ¶</a></h2> <p>Enables or disables <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering>buffering of a client request body</a>.</p> <h2 id=ssl-redirect>ssl-redirect<a class=headerlink href=#ssl-redirect title="Permanent link"> ¶</a></h2> <p>Sets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule). <em><strong>default:</strong></em> "true"</p> <h2 id=force-ssl-redirect>force-ssl-redirect<a class=headerlink href=#force-ssl-redirect title="Permanent link"> ¶</a></h2> <p>Sets the global value of redirects (308) to HTTPS if the server has a default TLS certificate (defined in extra-args). <em><strong>default:</strong></em> "false"</p> <h2 id=denylist-source-range>denylist-source-range<a class=headerlink href=#denylist-source-range title="Permanent link"> ¶</a></h2> <p>Sets the default denylisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See <a href=https://nginx.org/en/docs/http/ngx_http_access_module.html>ngx_http_access_module</a>.</p> <h2 id=whitelist-source-range>whitelist-source-range<a class=headerlink href=#whitelist-source-range title="Permanent link"> ¶</a></h2> <p>Sets the default whitelisted IPs for each <code>server</code> block. This can be overwritten by an annotation on an Ingress rule. See <a href=https://nginx.org/en/docs/http/ngx_http_access_module.html>ngx_http_access_module</a>.</p> <h2 id=skip-access-log-urls>skip-access-log-urls<a class=headerlink href=#skip-access-log-urls title="Permanent link"> ¶</a></h2> <p>Sets a list of URLs that should not appear in the NGINX access log. This is useful with urls like <code>/health</code> or <code>health-check</code> that make "complex" reading the logs. <em><strong>default:</strong></em> is empty</p> <h2 id=limit-rate>limit-rate<a class=headerlink href=#limit-rate title="Permanent link"> ¶</a></h2> <p>Limits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate>https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate</a></p> <h2 id=limit-rate-after>limit-rate-after<a class=headerlink href=#limit-rate-after title="Permanent link"> ¶</a></h2> <p>Sets the initial amount after which the further transmission of a response to a client will be rate limited.</p> <h2 id=lua-shared-dicts>lua-shared-dicts<a class=headerlink href=#lua-shared-dicts title="Permanent link"> ¶</a></h2> <p>Customize default Lua shared dictionaries or define more. You can use the following syntax to do so:</p> <div class=highlight><pre><span></span><code>lua-shared-dicts: &quot;&lt;my dict name&gt;: &lt;my dict size&gt;, [&lt;my dict name&gt;: &lt;my dict size&gt;], ...&quot;
 </code></pre></div> <p>For example following will set default <code>certificate_data</code> dictionary to <code>100M</code> and will introduce a new dictionary called <code>my_custom_plugin</code>:</p> <div class=highlight><pre><span></span><code>lua-shared-dicts: &quot;certificate_data: 100, my_custom_plugin: 5&quot;
 </code></pre></div> <p>You can optionally set a size unit to allow for kilobyte-granularity. Allowed units are 'm' or 'k' (case-insensitive), and it defaults to MB if no unit is provided. Here is a similar example, but the <code>my_custom_plugin</code> dict is only 512KB.</p> <div class=highlight><pre><span></span><code>lua-shared-dicts: &quot;certificate_data: 100, my_custom_plugin: 512k&quot;
 </code></pre></div> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after>https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after</a></p> <h2 id=http-redirect-code>http-redirect-code<a class=headerlink href=#http-redirect-code title="Permanent link"> ¶</a></h2> <p>Sets the HTTP status code to be used in redirects. Supported codes are <a href=https://developer.mozilla.org/docs/Web/HTTP/Status/301>301</a>,<a href=https://developer.mozilla.org/docs/Web/HTTP/Status/302>302</a>,<a href=https://developer.mozilla.org/docs/Web/HTTP/Status/307>307</a> and <a href=https://developer.mozilla.org/docs/Web/HTTP/Status/308>308</a> <em><strong>default:</strong></em> 308</p> <blockquote> <p><strong>Why the default code is 308?</strong></p> <p><a href=https://tools.ietf.org/html/rfc7238>RFC 7238</a> was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if we send a redirect in methods like POST.</p> </blockquote> <h2 id=proxy-buffering>proxy-buffering<a class=headerlink href=#proxy-buffering title="Permanent link"> ¶</a></h2> <p>Enables or disables <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering>buffering of responses from the proxied server</a>.</p> <h2 id=limit-req-status-code>limit-req-status-code<a class=headerlink href=#limit-req-status-code title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_status>status code to return in response to rejected requests</a>. <em><strong>default:</strong></em> 503</p> <h2 id=limit-conn-status-code>limit-conn-status-code<a class=headerlink href=#limit-conn-status-code title="Permanent link"> ¶</a></h2> <p>Sets the <a href=https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_status>status code to return in response to rejected connections</a>. <em><strong>default:</strong></em> 503</p> <h2 id=enable-syslog>enable-syslog<a class=headerlink href=#enable-syslog title="Permanent link"> ¶</a></h2> <p>Enable <a href=https://nginx.org/en/docs/syslog.html>syslog</a> feature for access log and error log. <em><strong>default:</strong></em> false</p> <h2 id=syslog-host>syslog-host<a class=headerlink href=#syslog-host title="Permanent link"> ¶</a></h2> <p>Sets the address of syslog server. The address can be specified as a domain name or IP address.</p> <h2 id=syslog-port>syslog-port<a class=headerlink href=#syslog-port title="Permanent link"> ¶</a></h2> <p>Sets the port of syslog server. <em><strong>default:</strong></em> 514</p> <h2 id=no-tls-redirect-locations>no-tls-redirect-locations<a class=headerlink href=#no-tls-redirect-locations title="Permanent link"> ¶</a></h2> <p>A comma-separated list of locations on which http requests will never get redirected to their https counterpart. <em><strong>default:</strong></em> "/.well-known/acme-challenge"</p> <h2 id=global-allowed-response-headers>global-allowed-response-headers<a class=headerlink href=#global-allowed-response-headers title="Permanent link"> ¶</a></h2> <p>A comma-separated list of allowed response headers inside the <a href=https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#custom-headers>custom headers annotations</a></p> <h2 id=global-auth-url>global-auth-url<a class=headerlink href=#global-auth-url title="Permanent link"> ¶</a></h2> <p>A url to an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-url</code>. Locations that should not get authenticated can be listed using <code>no-auth-locations</code> See <a href=#no-auth-locations>no-auth-locations</a>. In addition, each service can be excluded from authentication via annotation <code>enable-global-auth</code> set to "false". <em><strong>default:</strong></em> ""</p> <p><em>References:</em> <a href=https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#external-authentication>https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#external-authentication</a></p> <h2 id=global-auth-method>global-auth-method<a class=headerlink href=#global-auth-method title="Permanent link"> ¶</a></h2> <p>A HTTP method to use for an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-method</code>. <em><strong>default:</strong></em> ""</p> <h2 id=global-auth-signin>global-auth-signin<a class=headerlink href=#global-auth-signin title="Permanent link"> ¶</a></h2> <p>Sets the location of the error page for an existing service that provides authentication for all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-signin</code>. <em><strong>default:</strong></em> ""</p> <h2 id=global-auth-signin-redirect-param>global-auth-signin-redirect-param<a class=headerlink href=#global-auth-signin-redirect-param title="Permanent link"> ¶</a></h2> <p>Sets the query parameter in the error page signin URL which contains the original URL of the request that failed authentication. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-signin-redirect-param</code>. <em><strong>default:</strong></em> "rd"</p> <h2 id=global-auth-response-headers>global-auth-response-headers<a class=headerlink href=#global-auth-response-headers title="Permanent link"> ¶</a></h2> <p>Sets the headers to pass to backend once authentication request completes. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-response-headers</code>. <em><strong>default:</strong></em> ""</p> <h2 id=global-auth-request-redirect>global-auth-request-redirect<a class=headerlink href=#global-auth-request-redirect title="Permanent link"> ¶</a></h2> <p>Sets the X-Auth-Request-Redirect header value. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-request-redirect</code>. <em><strong>default:</strong></em> ""</p> <h2 id=global-auth-snippet>global-auth-snippet<a class=headerlink href=#global-auth-snippet title="Permanent link"> ¶</a></h2> <p>Sets a custom snippet to use with external authentication. Applied to all the locations. Similar to the Ingress rule annotation <code>nginx.ingress.kubernetes.io/auth-snippet</code>. <em><strong>default:</strong></em> ""</p> <h2 id=global-auth-cache-key>global-auth-cache-key<a class=headerlink href=#global-auth-cache-key title="Permanent link"> ¶</a></h2> <p>Enables caching for global auth requests. Specify a lookup key for auth responses, e.g. <code>$remote_user$http_authorization</code>.</p> <h2 id=global-auth-cache-duration>global-auth-cache-duration<a class=headerlink href=#global-auth-cache-duration title="Permanent link"> ¶</a></h2> <p>Set a caching time for auth responses based on their response codes, e.g. <code>200 202 30m</code>. See <a href=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid>proxy_cache_valid</a> for details. You may specify multiple, comma-separated values: <code>200 202 10m, 401 5m</code>. defaults to <code>200 202 401 5m</code>.</p> <h2 id=global-auth-always-set-cookie>global-auth-always-set-cookie<a class=headerlink href=#global-auth-always-set-cookie title="Permanent link"> ¶</a></h2> <p>Always set a cookie returned by auth request. By default, the cookie will be set only if an upstream reports with the code 200, 201, 204, 206, 301, 302, 303, 304, 307, or 308. <em><strong>default:</strong></em> false</p> <h2 id=no-auth-locations>no-auth-locations<a class=headerlink href=#no-auth-locations title="Permanent link"> ¶</a></h2> <p>A comma-separated list of locations that should not get authenticated. <em><strong>default:</strong></em> "/.well-known/acme-challenge"</p> <h2 id=block-cidrs>block-cidrs<a class=headerlink href=#block-cidrs title="Permanent link"> ¶</a></h2> <p>A comma-separated list of IP addresses (or subnets), request from which have to be blocked globally.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_access_module.html#deny>https://nginx.org/en/docs/http/ngx_http_access_module.html#deny</a></p> <h2 id=block-user-agents>block-user-agents<a class=headerlink href=#block-user-agents title="Permanent link"> ¶</a></h2> <p>A comma-separated list of User-Agent, request from which have to be blocked globally. It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code>map</code> Nginx directive documentation.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#map>https://nginx.org/en/docs/http/ngx_http_map_module.html#map</a></p> <h2 id=block-referers>block-referers<a class=headerlink href=#block-referers title="Permanent link"> ¶</a></h2> <p>A comma-separated list of Referers, request from which have to be blocked globally. It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code>map</code> Nginx directive documentation.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_map_module.html#map>https://nginx.org/en/docs/http/ngx_http_map_module.html#map</a></p> <h2 id=proxy-ssl-location-only>proxy-ssl-location-only<a class=headerlink href=#proxy-ssl-location-only title="Permanent link"> ¶</a></h2> <p>Set if proxy-ssl parameters should be applied only on locations and not on servers. <em><strong>default:</strong></em> is disabled</p> <h2 id=default-type>default-type<a class=headerlink href=#default-type title="Permanent link"> ¶</a></h2> <p>Sets the default MIME type of a response. <em><strong>default:</strong></em> text/html</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_core_module.html#default_type>https://nginx.org/en/docs/http/ngx_http_core_module.html#default_type</a></p> <h2 id=global-rate-limit>global-rate-limit<a class=headerlink href=#global-rate-limit title="Permanent link"> ¶</a></h2> <ul> <li><code>global-rate-limit-status-code</code>: configure HTTP status code to return when rejecting requests. Defaults to 429.</li> </ul> <p>Configure <code>memcached</code> client for <a href=https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#global-rate-limiting>Global Rate Limiting</a>.</p> <ul> <li><code>global-rate-limit-memcached-host</code>: IP/FQDN of memcached server to use. Required to enable Global Rate Limiting.</li> <li><code>global-rate-limit-memcached-port</code>: port of memcached server to use. Defaults default memcached port of <code>11211</code>.</li> <li><code>global-rate-limit-memcached-connect-timeout</code>: configure timeout for connect, send and receive operations. Unit is millisecond. Defaults to 50ms.</li> <li><code>global-rate-limit-memcached-max-idle-timeout</code>: configure timeout for cleaning idle connections. Unit is millisecond. Defaults to 50ms.</li> <li><code>global-rate-limit-memcached-pool-size</code>: configure number of max connections to keep alive. Make sure your <code>memcached</code> server can handle <code>global-rate-limit-memcached-pool-size * worker-processes * &lt;number of ingress-nginx replicas&gt;</code> simultaneous connections.</li> </ul> <p>These settings get used by <a href=https://github.com/ElvinEfendi/lua-resty-global-throttle>lua-resty-global-throttle</a> that ingress-nginx includes. Refer to the link to learn more about <code>lua-resty-global-throttle</code>.</p> <h2 id=service-upstream>service-upstream<a class=headerlink href=#service-upstream title="Permanent link"> ¶</a></h2> <p>Set if the service's Cluster IP and port should be used instead of a list of all endpoints. This can be overwritten by an annotation on an Ingress rule. <em><strong>default:</strong></em> "false"</p> <h2 id=ssl-reject-handshake>ssl-reject-handshake<a class=headerlink href=#ssl-reject-handshake title="Permanent link"> ¶</a></h2> <p>Set to reject SSL handshake to an unknown virtualhost. This parameter helps to mitigate the fingerprinting using default certificate of ingress. <em><strong>default:</strong></em> "false"</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_reject_handshake>https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_reject_handshake</a></p> <h2 id=debug-connections>debug-connections<a class=headerlink href=#debug-connections title="Permanent link"> ¶</a></h2> <p>Enables debugging log for selected client connections. <em><strong>default:</strong></em> ""</p> <p><em>References:</em> <a href=http://nginx.org/en/docs/ngx_core_module.html#debug_connection>http://nginx.org/en/docs/ngx_core_module.html#debug_connection</a></p> <h2 id=strict-validate-path-type>strict-validate-path-type<a class=headerlink href=#strict-validate-path-type title="Permanent link"> ¶</a></h2> <p>Ingress objects contains a field called pathType that defines the proxy behavior. It can be <code>Exact</code>, <code>Prefix</code> and <code>ImplementationSpecific</code>.</p> <p>When pathType is configured as <code>Exact</code> or <code>Prefix</code>, there should be a more strict validation, allowing only paths starting with "/" and containing only alphanumeric characters and "-", "_" and additional "/".</p> <p>When this option is enabled, the validation will happen on the Admission Webhook, making any Ingress not using pathType <code>ImplementationSpecific</code> and containing invalid characters to be denied.</p> <p>This means that Ingress objects that rely on paths containing regex characters should use <code>ImplementationSpecific</code> pathType.</p> <p>The cluster admin should establish validation rules using mechanisms like <a href=https://www.openpolicyagent.org/ >Open Policy Agent</a> to validate that only authorized users can use <code>ImplementationSpecific</code> pathType and that only the authorized characters can be used.</p> <h2 id=grpc-buffer-size-kb>grpc-buffer-size-kb<a class=headerlink href=#grpc-buffer-size-kb title="Permanent link"> ¶</a></h2> <p>Sets the configuration for the GRPC Buffer Size parameter. If not set it will use the default from NGINX.</p> <p><em>References:</em> <a href=https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size>https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size</a></p> </article> </div> </div> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> Made with <a href=https://squidfunk.github.io/mkdocs-material/ target=_blank rel=noopener> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <script id=__config type=application/json>{"base": "../../..", "features": ["navigation.tabs", "navigation.tabs.sticky", "navigation.instant", "navigation.sections"], "search": "../../../assets/javascripts/workers/search.f886a092.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src=../../../assets/javascripts/bundle.aecac24b.min.js></script> </body> </html>
\ No newline at end of file