</code></pre></div></p><p>Indicates the <ahref=https://tools.ietf.org/html/rfc2617>HTTP Authentication Type: Basic or Digest Access Authentication</a>.</p><divclass=highlight><pre><span></span><code>nginx.ingress.kubernetes.io/auth-secret: secretName
</code></pre></div><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><divclass=highlight><pre><span></span><code>nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]
</code></pre></div><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><divclass=highlight><pre><span></span><code>nginx.ingress.kubernetes.io/auth-realm: "realm string"
</code></pre></div><divclass="admonition example"><pclass=admonition-title>Example</p><p>Please check the <ahref=../../../examples/auth/basic/>auth</a> example.</p></div><h3id=custom-nginx-upstream-hashing>Custom NGINX upstream hashing<aclass=headerlinkhref=#custom-nginx-upstream-hashingtitle="Permanent link"> ¶</a></h3><p>NGINX supports load balancing by client-server mapping based on <ahref=https://nginx.org/en/docs/http/ngx_http_upstream_module.html#hash>consistent hashing</a> for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The <ahref=https://www.last.fm/user/RJ/journal/2007/04/10/rz_libketama_-_a_consistent_hashing_algo_for_memcache_clients>ketama</a> consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.</p><p>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 <ahref=../../../examples/chashsubset/deployment.yaml>chashsubset</a> example.</p><h3id=custom-nginx-load-balancing>Custom NGINX load balancing<aclass=headerlinkhref=#custom-nginx-load-balancingtitle="Permanent link"> ¶</a></h3><p>This is similar to <ahref=../configmap/#load-balance><code>load-balance</code> in ConfigMap</a>, but configures load balancing algorithm per ingress.</p><blockquote><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></blockquote><h3id=custom-nginx-upstream-vhost>Custom NGINX upstream vhost<aclass=headerlinkhref=#custom-nginx-upstream-vhosttitle="Permanent link"> ¶</a></h3><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><h3id=client-certificate-authentication>Client Certificate Authentication<aclass=headerlinkhref=#client-certificate-authenticationtitle="Permanent link"> ¶</a></h3><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.
</code></pre></div><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 <ahref=https://github.com/kubernetes/ingress-nginx/issues/7837>related issue on github</a> for more information.</p><h3id=custom-http-errors>Custom HTTP Errors<aclass=headerlinkhref=#custom-http-errorstitle="Permanent link"> ¶</a></h3><p>Like the <ahref=../configmap/#custom-http-errors><code>custom-http-errors</code></a> 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 <ahref=#default-backend>default backend annotation</a> 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: <divclass=highlight><pre><span></span><code>nginx.ingress.kubernetes.io/custom-http-errors: "404,415"
</code></pre></div></p><h3id=custom-headers>Custom Headers<aclass=headerlinkhref=#custom-headerstitle="Permanent link"> ¶</a></h3><p>This annotation is of the form <code>nginx.ingress.kubernetes.io/custom-headers: <namespace>/<custom headers configmap></code> to specify a namespace and configmap name that contains custom headers. This annotation uses <code>more_set_headers</code> nginx directive.</p><p>Example annotation for following example configmap:</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/custom-headers</span><spanclass=p>:</span><spanclass=w></span><spanclass="l l-Scalar l-Scalar-Plain">default/custom-headers-configmap</span>
</code></pre></div></p><divclass="admonition attention"><pclass=admonition-title>Attention</p></div><p>First define the allowed response headers in <ahref=https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/configmap.md#global-allowed-response-headers>global-allowed-response-headers</a>.</p><h3id=default-backend>Default Backend<aclass=headerlinkhref=#default-backendtitle="Permanent link"> ¶</a></h3><p>This annotation is of the form <code>nginx.ingress.kubernetes.io/default-backend: <svc name></code> to specify a custom default backend. This <code><svc name></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 <ahref=https://kubernetes.io/docs/concepts/services-networking/service/#multi-port-services>multiple ports</a>, 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 <ahref=#custom-http-errors>custom-http-errors annotation</a> are set.</p><h3id=enable-cors>Enable CORS<aclass=headerlinkhref=#enable-corstitle="Permanent link"> ¶</a></h3><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: <em>empty</em></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>protocol://origin-site.com</code> or <code>protocol://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, myprotocol://example.org:1199"</code></li></ul><p>It also supports single level wildcard subdomains and follows this format: <code>protocol://*.foo.bar</code>, <code>protocol://*.bar.foo:8080</code> or <code>protocol://*.abc.bar.foo:9000</code> - Example: <code>nginx.ingress.kubernetes.io/cors-allow-origin: "https://*.origin-site.com:4443, http://*.origin-site.com, myprotocol://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><l
</code></pre></div><divclass="admonition attention"><pclass=admonition-title>Attention</p><p>This annotation can be used only once per host.</p></div><h3id=client-body-buffer-size>Client Body Buffer Size<aclass=headerlinkhref=#client-body-buffer-sizetitle="Permanent link"> ¶</a></h3><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><divclass="admonition note"><pclass=admonition-title>Note</p><p>The annotation value must be given in a format understood by Nginx.</p></div><divclass="admonition example"><pclass=admonition-title>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></div><p>For more information please see <ahref=https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size>https://nginx.org</a></p><h3id=external-authentication>External Authentication<aclass=headerlinkhref=#external-authenticationtitle="Permanent link"> ¶</a></h3><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/auth-url</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"URL</span><spanclass=nv></span><spanclass=s>to</span><spanclass=nv></span><spanclass=s>the</span><spanclass=nv></span><spanclass=s>authentication</span><spanclass=nv></span><spanclass=s>service"</span>
</code></pre></div><p>Additionally it is possible to set:</p><ul><li><code>nginx.ingress.kubernetes.io/auth-keepalive</code>: <code><Connections></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 <ahref=https://github.com/openresty/lua-nginx-module#spdy-mode-not-fully-supported>subrequests</a>. <ahref=../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><Requests></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><Timeout></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><Method></code> to specify the HTTP method to use.</li><li><code>nginx.ingress.kubernetes.io/auth-signin</code>: <code><SignIn_URL></code> to specify the location of the error page.</li><li><code>nginx.ingress.kubernetes.io/auth-signin-redirect-param</code>: <code><SignIn_URL></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><Response_Header_1, ..., Response_Header_n></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><ConfigMap></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><Request_Redirect_URL></code> to specify the X-Auth-Request-Redirect header value.</li><li><code>nginx.ingress.kubernetes.io/auth-cache-key</code>: <code><Cache_Key></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><Cache_duration></code> to specify a caching time for auth responses based on their response codes, e.g. <code>200 202 30m</code>. See <ahref=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><Boolean_Flag></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><Auth_Snippet></code> to specify a custom snippet to use with external authentication, e.g.</li></ul><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/auth-url</span><spanclass=p>:</span><spanclass=w><
</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><divclass="admonition example"><pclass=admonition-title>Example</p><p>Please check the <ahref=../../../examples/auth/external-auth/>external-auth</a> example.</p></div><h4id=global-external-authentication>Global External Authentication<aclass=headerlinkhref=#global-external-authenticationtitle="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><divclass="admonition note"><pclass=admonition-title>Note</p><p>For more information please see <ahref=../configmap/#global-auth-url>global-auth-url</a>.</p></div><h3id=rate-limiting>Rate Limiting<aclass=headerlinkhref=#rate-limitingtitle="Permanent link"> ¶</a></h3><p>These annotations define limits on connections and transmission rates. These can be used to mitigate <ahref=https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus>DDoS Attacks</a>.</p><divclass="admonition attention"><pclass=admonition-title>Attention</p><p>Rate limits are applied per Ingress NGINX controller replica. If you're running multiple replicas or using a horizontal pod autoscaler (HPA), the effective rate limit will be multiplied by the number of replicas. When using HPA, the exact rate limit becomes dynamic as the number of replicas may change based on load.</p></div><ul><li><code>nginx.ingress.kubernetes.io/limit-connections</code>: number of concurrent connections allowed from a single IP address per controller replica. 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 per controller replica. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit, <ahref=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 per controller replica. The burst limit is set to this limit multiplied by the burst multiplier, the default multiplier is 5. When clients exceed this limit, <ahref=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, <ahref=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 <ahref=#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
</code></pre></div><h3id=proxy-cookie-domain>Proxy cookie domain<aclass=headerlinkhref=#proxy-cookie-domaintitle="Permanent link"> ¶</a></h3><p>Sets a text that <ahref=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 <ahref=../configmap/#proxy-cookie-domain>NGINX ConfigMap</a>.</p><h3id=proxy-cookie-path>Proxy cookie path<aclass=headerlinkhref=#proxy-cookie-pathtitle="Permanent link"> ¶</a></h3><p>Sets a text that <ahref=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 <ahref=../configmap/#proxy-cookie-path>NGINX ConfigMap</a>.</p><h3id=proxy-buffering>Proxy buffering<aclass=headerlinkhref=#proxy-bufferingtitle="Permanent link"> ¶</a></h3><p>Enable or disable proxy buffering <ahref=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 <ahref=../configmap/#proxy-buffering>NGINX ConfigMap</a>. To use custom values in an Ingress rule define these annotation:</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/proxy-buffering</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"on"</span>
</code></pre></div><h3id=proxy-buffers-number>Proxy buffers Number<aclass=headerlinkhref=#proxy-buffers-numbertitle="Permanent link"> ¶</a></h3><p>Sets the number of the buffers in <ahref=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 <ahref=../configmap/#proxy-buffers-number>NGINX ConfigMap</a>. To use custom values in an Ingress rule, define this annotation: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/proxy-buffers-number</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"4"</span>
</code></pre></div></p><h3id=proxy-buffer-size>Proxy buffer size<aclass=headerlinkhref=#proxy-buffer-sizetitle="Permanent link"> ¶</a></h3><p>Sets the size of the buffer <ahref=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 <ahref=../configmap/#proxy-buffer-size>NGINX ConfigMap</a>. To use custom values in an Ingress rule, define this annotation: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/proxy-buffer-size</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"8k"</span>
</code></pre></div></p><h3id=proxy-busy-buffers-size>Proxy busy buffers size<aclass=headerlinkhref=#proxy-busy-buffers-sizetitle="Permanent link"> ¶</a></h3><p><ahref=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size>Limits the total size of buffers that can be busy</a> sending a response to the client while the response is not yet fully read.</p><p>By default proxy busy buffers size is set as "8k".</p><p>To configure this setting globally, set <code>proxy-busy-buffers-size</code> in the <ahref=../configmap/#proxy-busy-buffers-size>ConfigMap</a>. To use custom values in an Ingress rule, define this annotation:</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/proxy-busy-buffers-size</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"16k"</span>
</code></pre></div><h3id=proxy-max-temp-file-size>Proxy max temp file size<aclass=headerlinkhref=#proxy-max-temp-file-sizetitle="Permanent link"> ¶</a></h3><p>When <ahref=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering><code>buffering</code></a> of responses from the proxied server is enabled, and the whole response does not fit into the buffers set by the <ahref=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size><code>proxy_buffer_size</code></a> and <ahref=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers><code>proxy_buffers</code></a> 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 <ahref=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size><code>proxy_max_temp_file_size</code></a>. The size of data written to the temporary file at a time is set by the <ahref=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_temp_file_write_size><code>proxy_temp_file_write_size</code></a> 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: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/proxy-max-temp-file-size</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"1024m"</span>
</code></pre></div></p><h3id=proxy-http-version>Proxy HTTP version<aclass=headerlinkhref=#proxy-http-versiontitle="Permanent link"> ¶</a></h3><p>Using this annotation sets the <ahref=https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version><code>proxy_http_version</code></a> that the Nginx reverse proxy will use to communicate with the backend. By default this is set to "1.1".</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/proxy-http-version</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"1.0"</span>
</code></pre></div><h3id=ssl-ciphers>SSL ciphers<aclass=headerlinkhref=#ssl-cipherstitle="Permanent link"> ¶</a></h3><p>Specifies the <ahref=https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers>enabled ciphers</a>.</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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/ssl-ciphers</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"</span>
</code></pre></div><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/ssl-prefer-server-ciphers</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"true"</span>
</code></pre></div><h3id=connection-proxy-header>Connection proxy header<aclass=headerlinkhref=#connection-proxy-headertitle="Permanent link"> ¶</a></h3><p>Using this annotation will override the default connection header set by NGINX. To use custom values in an Ingress rule, define the annotation:</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/connection-proxy-header</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"keep-alive"</span>
</code></pre></div><h3id=enable-access-log>Enable Access Log<aclass=headerlinkhref=#enable-access-logtitle="Permanent link"> ¶</a></h3><p>Access logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given ingress. To do this, use the annotation:</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/enable-access-log</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"false"</span>
</code></pre></div><h3id=enable-rewrite-log>Enable Rewrite Log<aclass=headerlinkhref=#enable-rewrite-logtitle="Permanent link"> ¶</a></h3><p>Rewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs. Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/enable-rewrite-log</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"true"</span>
</code></pre></div><h3id=enable-opentelemetry>Enable Opentelemetry<aclass=headerlinkhref=#enable-opentelemetrytitle="Permanent link"> ¶</a></h3><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/enable-opentelemetry</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"true"</span>
</code></pre></div><h3id=opentelemetry-trust-incoming-span>Opentelemetry Trust Incoming Span<aclass=headerlinkhref=#opentelemetry-trust-incoming-spantitle="Permanent link"> ¶</a></h3><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-spans</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"true"</span>
</code></pre></div><h3id=x-forwarded-prefix-header>X-Forwarded-Prefix Header<aclass=headerlinkhref=#x-forwarded-prefix-headertitle="Permanent link"> ¶</a></h3><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/x-forwarded-prefix</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"/path"</span>
</code></pre></div><h3id=modsecurity>ModSecurity<aclass=headerlinkhref=#modsecuritytitle="Permanent link"> ¶</a></h3><p><ahref=http://modsecurity.org/>ModSecurity</a> 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 <ahref=../configmap/#enable-modsecurity>ConfigMap</a>. 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: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/enable-modsecurity</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"true"</span>
</code></pre></div> ModSecurity will run in "Detection-Only" mode using the <ahref=https://github.com/SpiderLabs/ModSecurity/blob/v3/master/modsecurity.conf-recommended>recommended configuration</a>.</p><p>You can enable the <ahref=https://www.modsecurity.org/CRS/Documentation/>OWASP Core Rule Set</a> by setting the following annotation: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/enable-owasp-core-rules</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"true"</span>
</code></pre></div></p><p>You can pass transactionIDs from nginx by setting up the following: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/modsecurity-transaction-id</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"$request_id"</span>
</code></pre></div></p><p>You can also add your own set of modsecurity rules via a snippet: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/modsecurity-snippet</span><spanclass=p>:</span><spanclass=w></span><spanclass="p p-Indicator">|</span>
</code></pre></div></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 <ahref=https://www.modsecurity.org/CRS/Documentation/>OWASP Core Rule Set</a> or <ahref=https://github.com/SpiderLabs/ModSecurity/blob/v3/master/modsecurity.conf-recommended>recommended configuration</a> simply use the include statement:</p><p>nginx 0.24.1 and below <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/modsecurity-snippet</span><spanclass=p>:</span><spanclass=w></span><spanclass="p p-Indicator">|</span>
</code></pre></div></p><h3id=backend-protocol>Backend Protocol<aclass=headerlinkhref=#backend-protocoltitle="Permanent link"> ¶</a></h3><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/backend-protocol</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"HTTPS"</span>
</code></pre></div><h3id=use-regex>Use Regex<aclass=headerlinkhref=#use-regextitle="Permanent link"> ¶</a></h3><divclass="admonition attention"><pclass=admonition-title>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></div><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: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/use-regex</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"true"</span>
</code></pre></div></p><p>The following will indicate that regular expression paths are <strong>not</strong> being used: <divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/use-regex</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"false"</span>
</code></pre></div></p><p>When this annotation is set to <code>true</code>, the case insensitive regular expression <ahref=https://nginx.org/en/docs/http/ngx_http_core_module.html#location>location modifier</a> will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p><p>Additionally, if the <ahref=#rewrite><code>rewrite-target</code> annotation</a> is used on any Ingress for a given host, then the case insensitive regular expression <ahref=https://nginx.org/en/docs/http/ngx_http_core_module.html#location>location modifier</a> will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p><p>Please read about <ahref=../../ingress-path-matching/>ingress path matching</a> before using this modifier.</p><h3id=satisfy>Satisfy<aclass=headerlinkhref=#satisfytitle="Permanent link"> ¶</a></h3><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/satisfy</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"any"</span>
</code></pre></div><h3id=mirror>Mirror<aclass=headerlinkhref=#mirrortitle="Permanent link"> ¶</a></h3><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/mirror-target</span><spanclass=p>:</span><spanclass=w></span><spanclass="l l-Scalar l-Scalar-Plain">https://test.env.com$request_uri</span>
</code></pre></div><p>By default the request-body is sent to the mirror backend, but can be turned off by applying:</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/mirror-request-body</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"off"</span>
</code></pre></div><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><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/mirror-target</span><spanclass=p>:</span><spanclass=w></span><spanclass="l l-Scalar l-Scalar-Plain">https://1.2.3.4$request_uri</span>
</code></pre></div><p><strong>Note:</strong> 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 <ahref=https://nginx.org/en/docs/http/ngx_http_mirror_module.html>ngx_http_mirror_module</a></p><h3id=stream-snippet>Stream snippet<aclass=headerlinkhref=#stream-snippettitle="Permanent link"> ¶</a></h3><p>Using the annotation <code>nginx.ingress.kubernetes.io/stream-snippet</code> it is possible to add custom stream configuration.</p><divclass=highlight><pre><span></span><code><spanclass=nt>apiVersion</span><spanclass=p>:</span><spanclass=w></span><spanclass="l l-Scalar l-Scalar-Plain">networking.k8s.io/v1</span>
</code></pre></div></article></div></div></main><footerclass=md-footer><divclass="md-footer-meta md-typeset"><divclass="md-footer-meta__inner md-grid"><divclass=md-copyright> Made with <ahref=https://squidfunk.github.io/mkdocs-material/target=_blankrel=noopener> Material for MkDocs </a></div></div></div></footer></div><divclass=md-dialogdata-md-component=dialog><divclass="md-dialog__inner md-typeset"></div></div><scriptid=__configtype=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><scriptsrc=../../../assets/javascripts/bundle.aecac24b.min.js></script></body></html>
