</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=http://nginx.org/en/docs/http/ngx_http_upstream_module.html#hash>consistent hashing</a> for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The <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>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>The annotations are:</p><ul><li><code>nginx.ingress.kubernetes.io/auth-tls-secret: secretName</code>: The name of the Secret that contains the full Certificate Authority chain <code>ca.crt</code> that is enabled to authenticate against this Ingress. This annotation expects the Secret name in the form "namespace/secretName".</li><li><code>nginx.ingress.kubernetes.io/auth-tls-verify-depth</code>: The validation depth between the provided client cer
</code></pre></div><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=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.</p><p>This service will be handle the response when the service in the Ingress rule does not have active endpoints. It will also handle the error responses if both this annotation and the <ahref=#custom-http-errors>custom-http-errors annotation</a> is 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><code>nginx.ingress.kubernetes.io/cors-allow-methods</code> controls which methods are accepted. This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).</li><li>Default: <code>GET, PUT, POST, DELETE, PATCH, OPTIONS</code></li><li><p>Example: <code>nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"</code></p></li><li><p><code>nginx.ingress.kubernetes.io/cors-allow-headers</code> controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.</p></li><li>Default: <code>DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization</code></li><li><p>Example: <code>nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"</code></p></li><li><p><code>nginx.ingress.kubernetes.io/cors-expose-headers</code> controls which headers are exposed to response. This is a multi-valued field, separated by ',' and accepts letters, numbers, _, - and *.</p></li><li>Default: <em>empty</em></li><li><p>Example: <code>nginx.ingress.kubernetes.io/cors-expose-headers: "*, X-CustomResponseHeader"</code></p></li><li><p><code>nginx.ingress.kubernetes.io/cors-allow-origin</code> controls what's the accepted Origin for CORS. This is a single field value, with the following format: <code>http(s)://origin-site.com</code> or <code>http(s)://origin-site.com:port</code></p></li><li>Default: <code>*</code></li><li><p>Example: <code>nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443"</code></p></li><li><p><code>nginx.ingress.kubernetes.io/cors-allow-credentials</code> controls if credentials can be passed during CORS operations.</p></li><li>Default: <code>true</code></li><li><p>Example: <code>nginx.ingress.kubernetes.io/cors-allow-credentials: "false"</code></p></li><li><p><code>nginx.ingress.kubernetes.io/cors-max-age</code> controls how long preflight requests can be cached. Default: <code>1728000</code> Example: <code>nginx.ingress.kubernetes.io/cors-max-age: 600</code></p></li></ul><divclass="admonition note"><pclass=admonition-title>Note</p><p>For more information please see <ahref=https://enable-cors.org/server_nginx.html>https://enable-cors.org</a></p></div><h3id=http2-push-preload>HTTP2 Push Preload.<aclass=headerlinkhref=#http2-push-preloadtitle="Permanent link"> ¶</a></h3><p>Enables automatic conversion of preload links specified in the “Link” response header fields into push requests.</p><divclass="admonition example"><pclass=admonition-title>Example</p><ul><li><code>nginx.ingress.kubernetes.io/http2-push-preload: "true"</code></li></ul></div><h3id=server-alias>Server Alias<aclass=headerlinkhref=#server-aliastitle="Permanent link"> ¶</a></h3><p>Allows the definition of one or more aliases in the server definition of the NGINX configurat
</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=http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size>http://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=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-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=http://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-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="l l-Scalar l-Scalar-Plain">http://foo.com/external-auth</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><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><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, <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. 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 must be used with <ahref=#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 a
</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=http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_domain>should be changed in the domain attribute</a> of the "Set-Cookie" header fields of a proxied server response.</p><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=http://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=http://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=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=http://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=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=http://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=s>"8k"</span>
</code></pre></div></p><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=http://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=http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size><code>proxy_buffer_size</code></a> and <ahref=http://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=http://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=http://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=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=http://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=s>"1.0"</span>
</code></pre></div><h3id=ssl-ciphers>SSL ciphers<aclass=headerlinkhref=#ssl-cipherstitle="Permanent link"> ¶</a></h3><p>Specifies the <ahref=http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers>enabled ciphers</a>.</p><p>Using this annotation will set the <code>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=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=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=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=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=s>"true"</span>
</code></pre></div><h3id=enable-opentracing>Enable Opentracing<aclass=headerlinkhref=#enable-opentracingtitle="Permanent link"> ¶</a></h3><p>Opentracing 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 tracing of external health check endpoints)</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/enable-opentracing</span><spanclass=p>:</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=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=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=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=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="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="p p-Indicator">|</span>
</code></pre></div></p><h3id=influxdb>InfluxDB<aclass=headerlinkhref=#influxdbtitle="Permanent link"> ¶</a></h3><p>Using <code>influxdb-*</code> annotations we can monitor requests passing through a Location by sending them to an InfluxDB backend exposing the UDP socket using the <ahref=https://github.com/influxdata/nginx-influxdb-module/>nginx-influxdb-module</a>.</p><divclass=highlight><pre><span></span><code><spanclass=nt>nginx.ingress.kubernetes.io/enable-influxdb</span><spanclass=p>:</span><spanclass=s>"true"</span>
</code></pre></div><p>For the <code>influxdb-host</code> parameter you have two options:</p><ul><li>Use an InfluxDB server configured with the <ahref=https://docs.influxdata.com/influxdb/v1.5/supported_protocols/udp/>UDP protocol</a> enabled.</li><li>Deploy Telegraf as a sidecar proxy to the Ingress controller configured to listen UDP with the <ahref=https://github.com/influxdata/telegraf/tree/release-1.6/plugins/inputs/socket_listener>socket listener input</a> and to write using anyone of the <ahref=https://github.com/influxdata/telegraf/tree/release-1.7/plugins/outputs>outputs plugins</a> like InfluxDB, Apache Kafka, Prometheus, etc.. (recommended)</li></ul><p>It's important to remember that there's no DNS resolver at this stage so you will have to configure an ip address to <code>nginx.ingress.kubernetes.io/influxdb-host</code>. If you deploy Influx or Telegraf as sidecar (another container in the same pod) this becomes straightforward since you can directly use <code>127.0.0.1</code>.</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, GRPC, GRPCS, AJP 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=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=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=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=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="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=s>"off"</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></article></div></div></main><footerclass=md-footer><divclass=md-footer-nav><navclass="md-footer-nav__inner md-grid"aria-label=Footer><ahref=../../basic-usage/class="md-footer-nav__link md-footer-nav__link--prev"rel=prev><divclass="md-footer-nav__button md-icon"><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg></div><divclass=md-footer-nav__title><divclass=md-ellipsis><spanclass=md-footer-nav__direction> Previous </span> Basic usage </div></div></a><ahref=../configmap/class="md-footer-nav__link md-footer-nav__link--next"rel=next><divclass=md-footer-nav__title><divclass=md-ellipsis><spanclass=md-footer-nav__direction> Next </span> ConfigMap </div></div><divclass="md-footer-nav__button md-icon"><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg></div></a></nav></div><divclass="md-footer-meta md-typeset"><divclass="md-footer-meta__inner md-grid"><divclass=md-footer-copyright> Made with <ahref=https://squidfunk.github.io/mkdocs-material/target=_blankrel=noopener> Material for MkDocs </a></div></div></div></footer></div><scriptsrc=../../../assets/javascripts/vendor.93c04032.min.js></script><scriptsrc=../../../assets/javascripts/bundle.83e5331e.min.js></script><scriptid=__langtype=application/json>{"clipboard.copy":"Copy to clipboard","clipboard.copied":"Copied to clipboard","search.config.lang":"en","search.config.pipeline":"trimmer, stopWordFilter","search.config.separator":"[\\s\\-]+","search.placeholder":"Search","search.result.placeholder":"Type to start searching","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.term.missing":"Missing"}</script><script>
