From 15d84d230a8c3d0f657ca3fd07e2a85befe8d752 Mon Sep 17 00:00:00 2001 From: k8s-ci-robot Date: Mon, 17 Apr 2023 00:27:34 +0000 Subject: [PATCH] Deploy GitHub Pages --- e2e-tests/index.html | 4 +- search/search_index.json | 2 +- sitemap.xml | 104 +++++++++--------- sitemap.xml.gz | Bin 719 -> 720 bytes .../annotations/index.html | 9 +- 5 files changed, 57 insertions(+), 62 deletions(-) diff --git a/e2e-tests/index.html b/e2e-tests/index.html index af411d56f..3950e49cb 100644 --- a/e2e-tests/index.html +++ b/e2e-tests/index.html @@ -1,7 +1,7 @@ - E2e tests - NGINX Ingress Controller
Skip to content

e2e test suite for Ingress NGINX Controller

[Admission] admission controller

affinitymode

server-alias

app-root

auth-tls-*

backend-protocol

client-body-buffer-size

connection-proxy-header

cors-*

custom-http-errors

default-backend

disable-access-log disable-http-access-log disable-stream-access-log

force-ssl-redirect

from-to-www-redirect

annotation-global-rate-limit

backend-protocol - GRPC

http2-push-preload

influxdb-*

whitelist-source-range

Annotation - limit-connections

limit-rate

enable-access-log enable-rewrite-log

mirror-*

modsecurity owasp

preserve-trailing-slash

proxy-*

proxy-ssl-*

permanent-redirect permanent-redirect-code

satisfy

server-snippet

service-upstream

configuration-snippet

ssl-ciphers

stream-snippet

upstream-hash-by-*

upstream-vhost

x-forwarded-prefix

denylist-source-range

rewrite-target use-regex enable-rewrite-log

backend-protocol - FastCGI

auth-*

canary-*

Debug CLI

[Default Backend] custom service

[Default Backend]

[Default Backend] SSL

[Default Backend] change default settings

[Endpointslices] long service name

[TopologyHints] topology aware routing

[Setting]

[Shutdown] Grace period shutdown

[Shutdown] ingress controller

[Shutdown] Graceful shutdown with pending request

[Ingress] DeepInspection

single ingress - multiple hosts

[Ingress] [PathType] exact

[Ingress] [PathType] mix Exact and Prefix paths

[Ingress] [PathType] prefix checks

[Ingress] definition without host

[Memory Leak] Dynamic Certificates

[Load Balancer] load-balance

[Load Balancer] EWMA

[Load Balancer] round-robin

[Lua] dynamic certificates

[Lua] dynamic configuration

nginx-configuration

[Security] request smuggling

[Service] backend status code 503

[Service] Type ExternalName

[Service] Nil Service Backend

access-log

Bad annotation values

brotli

add-headers

[SSL] [Flag] default-ssl-certificate

[Flag] disable-catch-all

[Flag] disable-service-external-name

enable-real-ip

use-forwarded-headers

Geoip2

[Security] block-*

[Security] global-auth-url

global-options

settings-global-rate-limit

hash size

[Flag] ingress-class

keep-alive keep-alive-requests

Configmap - limit-rate

[Flag] custom HTTP and HTTPS ports

log-format-*

[Lua] lua-shared-dicts

main-snippet

[Security] modsecurity-snippet

enable-multi-accept

Add no tls redirect locations

OCSP

Configure OpenTracing

plugins

[Security] Pod Security Policies

[Security] Pod Security Policies with volumes

proxy-connect-timeout

Dynamic $proxy_host

proxy-next-upstream

use-proxy-protocol

proxy-read-timeout

proxy-send-timeout

reuse-port

configmap server-snippet

server-tokens

ssl-ciphers

configmap stream-snippet

[SSL] TLS protocols, ciphers and headers)

[Flag] disable-sync-events

gzip

Configmap change

[Flag] watch namespace selector

With enable-ssl-passthrough enabled

[Security] no-auth-locations

Configure Opentelemetry

[SSL] redirect to HTTPS

[SSL] secret update

[Status] status update

[TCP] tcp-services

Skip to content

Annotations

You can add these Kubernetes annotations to specific Ingress objects to customize their behavior.

Tip

Annotation keys and values can only be strings. Other types, such as boolean or numeric values must be quoted, i.e. "true", "false", "100".

Note

The annotation prefix can be changed using the --annotations-prefix command line argument, but the default is nginx.ingress.kubernetes.io, as described in the table below.

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-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/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-name string
nginx.ingress.kubernetes.io/session-cookie-path string
nginx.ingress.kubernetes.io/session-cookie-domain string
nginx.ingress.kubernetes.io/session-cookie-change-on-failure "true" or "false"
nginx.ingress.kubernetes.io/session-cookie-samesite string
nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none "true" or "false"
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-opentracing "true" or "false"
nginx.ingress.kubernetes.io/opentracing-trust-incoming-span "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/enable-influxdb "true" or "false"
nginx.ingress.kubernetes.io/influxdb-measurement string
nginx.ingress.kubernetes.io/influxdb-port string
nginx.ingress.kubernetes.io/influxdb-host string
nginx.ingress.kubernetes.io/influxdb-server-name string
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

Canary

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 nginx.ingress.kubernetes.io/canary: "true" is set:

  • nginx.ingress.kubernetes.io/canary-by-header: 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 always, it will be routed to the canary. When the header is set to never, 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.

  • nginx.ingress.kubernetes.io/canary-by-header-value: 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 nginx.ingress.kubernetes.io/canary-by-header. The annotation is an extension of the nginx.ingress.kubernetes.io/canary-by-header to allow customizing the header value instead of using hardcoded values. It doesn't have any effect if the nginx.ingress.kubernetes.io/canary-by-header annotation is not defined.

  • nginx.ingress.kubernetes.io/canary-by-header-pattern: This works the same way as canary-by-header-value except it does PCRE Regex matching. Note that when canary-by-header-value is set this annotation will be ignored. When the given Regex causes error during request processing, the request will be considered as not matching.

  • nginx.ingress.kubernetes.io/canary-by-cookie: 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 always, it will be routed to the canary. When the cookie is set to never, 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.

  • nginx.ingress.kubernetes.io/canary-weight: 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 <weight-total> means implies all requests will be sent to the alternative service specified in the Ingress. <weight-total> defaults to 100, and can be increased via nginx.ingress.kubernetes.io/canary-weight-total.

  • nginx.ingress.kubernetes.io/canary-weight-total: The total weight of traffic. If unspecified, it defaults to 100.

Canary rules are evaluated in order of precedence. Precedence is as follows: canary-by-header -> canary-by-cookie -> canary-weight

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 nginx.ingress.kubernetes.io/load-balance, nginx.ingress.kubernetes.io/upstream-hash-by, and annotations related to session affinity. If you want to restore the original behavior of canaries when session affinity was ignored, set nginx.ingress.kubernetes.io/affinity-canary-behavior annotation with value legacy on the canary ingress definition.

Known Limitations

Currently a maximum of one canary ingress can be applied per Ingress rule.

Rewrite

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 nginx.ingress.kubernetes.io/rewrite-target to the path expected by the service.

If the Application Root is exposed in a different path and needs to be redirected, set the annotation nginx.ingress.kubernetes.io/app-root to redirect requests for /.

Example

Please check the rewrite example.

Session Affinity

The annotation nginx.ingress.kubernetes.io/affinity 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 cookie.

The annotation nginx.ingress.kubernetes.io/affinity-mode defines the stickiness of a session. Setting this to balanced (default) will redistribute some sessions if a deployment gets scaled up, therefore rebalancing the load on the servers. Setting this to persistent will not rebalance sessions to new servers, therefore providing maximum stickiness.

The annotation nginx.ingress.kubernetes.io/affinity-canary-behavior defines the behavior of canaries when session affinity is enabled. Setting this to sticky (default) will ensure that users that were served by canaries, will continue to be served by canaries. Setting this to legacy will restore original canary behavior, when session affinity was ignored.

Attention

If more than one Ingress is defined for a host and at least one Ingress uses nginx.ingress.kubernetes.io/affinity: cookie, then only paths on the Ingress using nginx.ingress.kubernetes.io/affinity 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.

Example

Please check the affinity example.

If you use the cookie affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name. The default is to create a cookie named 'INGRESSCOOKIE'.

The NGINX annotation nginx.ingress.kubernetes.io/session-cookie-path defines the path that will be set on the cookie. This is optional unless the annotation nginx.ingress.kubernetes.io/use-regex is set to true; Session cookie paths do not support regex.

Use nginx.ingress.kubernetes.io/session-cookie-domain to set the Domain attribute of the sticky cookie.

Use nginx.ingress.kubernetes.io/session-cookie-samesite to apply a SameSite attribute to the sticky cookie. Browser accepted values are None, Lax, and Strict. Some browsers reject cookies with SameSite=None, including those created before the SameSite=None specification (e.g. Chrome 5X). Other browsers mistakenly treat SameSite=None cookies as SameSite=Strict (e.g. Safari running on OSX 14). To omit SameSite=None from browsers with these incompatibilities, add the annotation nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true".

Authentication

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.

The annotations are: 

nginx.ingress.kubernetes.io/auth-type: [basic|digest]
+ Annotations - NGINX Ingress Controller      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
    
Annotations
 
You can add these Kubernetes annotations to specific Ingress objects to customize their behavior.
 
 
Tip
 
Annotation keys and values can only be strings. Other types, such as boolean or numeric values must be quoted, i.e. "true", "false", "100".
 
 
 
Note
 
The annotation prefix can be changed using the --annotations-prefix command line argument, but the default is nginx.ingress.kubernetes.io, as described in the table below.
 
 
  
 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-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/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-name string 
 
 nginx.ingress.kubernetes.io/session-cookie-path string 
 
 nginx.ingress.kubernetes.io/session-cookie-domain string 
 
 nginx.ingress.kubernetes.io/session-cookie-change-on-failure "true" or "false" 
 
 nginx.ingress.kubernetes.io/session-cookie-samesite string 
 
 nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none "true" or "false" 
 
 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-opentracing "true" or "false" 
 
 nginx.ingress.kubernetes.io/opentracing-trust-incoming-span "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 
  
 
Canary
 
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 nginx.ingress.kubernetes.io/canary: "true" is set:
 
     
  •  
    nginx.ingress.kubernetes.io/canary-by-header: 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 always, it will be routed to the canary. When the header is set to never, 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.
     
    •  
  •  
    nginx.ingress.kubernetes.io/canary-by-header-value: 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 nginx.ingress.kubernetes.io/canary-by-header. The annotation is an extension of the nginx.ingress.kubernetes.io/canary-by-header to allow customizing the header value instead of using hardcoded values. It doesn't have any effect if the nginx.ingress.kubernetes.io/canary-by-header annotation is not defined.
     
    •  
  •  
    nginx.ingress.kubernetes.io/canary-by-header-pattern: This works the same way as canary-by-header-value except it does PCRE Regex matching. Note that when canary-by-header-value is set this annotation will be ignored. When the given Regex causes error during request processing, the request will be considered as not matching.
     
    •  
  •  
    nginx.ingress.kubernetes.io/canary-by-cookie: 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 always, it will be routed to the canary. When the cookie is set to never, 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.
     
    •  
  •  
    nginx.ingress.kubernetes.io/canary-weight: 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 <weight-total> means implies all requests will be sent to the alternative service specified in the Ingress. <weight-total> defaults to 100, and can be increased via nginx.ingress.kubernetes.io/canary-weight-total.
     
    •  
  •  
    nginx.ingress.kubernetes.io/canary-weight-total: The total weight of traffic. If unspecified, it defaults to 100.
     
    •  
 
Canary rules are evaluated in order of precedence. Precedence is as follows: canary-by-header -> canary-by-cookie -> canary-weight
 
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 nginx.ingress.kubernetes.io/load-balance, nginx.ingress.kubernetes.io/upstream-hash-by, and annotations related to session affinity. If you want to restore the original behavior of canaries when session affinity was ignored, set nginx.ingress.kubernetes.io/affinity-canary-behavior annotation with value legacy on the canary ingress definition.
 
Known Limitations
 
Currently a maximum of one canary ingress can be applied per Ingress rule.
 
Rewrite
 
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 nginx.ingress.kubernetes.io/rewrite-target to the path expected by the service.
 
If the Application Root is exposed in a different path and needs to be redirected, set the annotation nginx.ingress.kubernetes.io/app-root to redirect requests for /.
 
 
Example
 
Please check the rewrite example.
 
 
Session Affinity
 
The annotation nginx.ingress.kubernetes.io/affinity 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 cookie.
 
The annotation nginx.ingress.kubernetes.io/affinity-mode defines the stickiness of a session. Setting this to balanced (default) will redistribute some sessions if a deployment gets scaled up, therefore rebalancing the load on the servers. Setting this to persistent will not rebalance sessions to new servers, therefore providing maximum stickiness.
 
The annotation nginx.ingress.kubernetes.io/affinity-canary-behavior defines the behavior of canaries when session affinity is enabled. Setting this to sticky (default) will ensure that users that were served by canaries, will continue to be served by canaries. Setting this to legacy will restore original canary behavior, when session affinity was ignored.
 
 
Attention
 
If more than one Ingress is defined for a host and at least one Ingress uses nginx.ingress.kubernetes.io/affinity: cookie, then only paths on the Ingress using nginx.ingress.kubernetes.io/affinity 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.
 
 
 
Example
 
Please check the affinity example.
 
  
If you use the cookie affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name. The default is to create a cookie named 'INGRESSCOOKIE'.
 
The NGINX annotation nginx.ingress.kubernetes.io/session-cookie-path defines the path that will be set on the cookie. This is optional unless the annotation nginx.ingress.kubernetes.io/use-regex is set to true; Session cookie paths do not support regex.
 
Use nginx.ingress.kubernetes.io/session-cookie-domain to set the Domain attribute of the sticky cookie.
 
Use nginx.ingress.kubernetes.io/session-cookie-samesite to apply a SameSite attribute to the sticky cookie. Browser accepted values are None, Lax, and Strict. Some browsers reject cookies with SameSite=None, including those created before the SameSite=None specification (e.g. Chrome 5X). Other browsers mistakenly treat SameSite=None cookies as SameSite=Strict (e.g. Safari running on OSX 14). To omit SameSite=None from browsers with these incompatibilities, add the annotation nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true".
 
Authentication
 
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.
 
The annotations are: 
nginx.ingress.kubernetes.io/auth-type: [basic|digest]
 
 
Indicates the HTTP Authentication Type: Basic or Digest Access Authentication.
 
nginx.ingress.kubernetes.io/auth-secret: secretName
 
 
The name of the Secret that contains the usernames and passwords which are granted access to the paths 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.
 
nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]
 
 
The auth-secret can have two forms:
 
     
  • auth-file - default, an htpasswd file in the key auth within the secret
    •  
  • auth-map - the keys of the secret are the usernames, and the values are the hashed passwords
    •  
 
nginx.ingress.kubernetes.io/auth-realm: "realm string"
@@ -50,12 +50,7 @@
 Include /etc/nginx/modsecurity/modsecurity.conf
 
 nginx 0.25.0 and above 
nginx.ingress.kubernetes.io/modsecurity-snippet: |
 Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf
-
 
InfluxDB
 
Using influxdb-* annotations we can monitor requests passing through a Location by sending them to an InfluxDB backend exposing the UDP socket using the nginx-influxdb-module.
 
nginx.ingress.kubernetes.io/enable-influxdb: "true"
-nginx.ingress.kubernetes.io/influxdb-measurement: "nginx-reqs"
-nginx.ingress.kubernetes.io/influxdb-port: "8089"
-nginx.ingress.kubernetes.io/influxdb-host: "127.0.0.1"
-nginx.ingress.kubernetes.io/influxdb-server-name: "nginx-ingress"
-
 
For the influxdb-host parameter you have two options:
 
     
  • Use an InfluxDB server configured with the UDP protocol enabled.
    •  
  • Deploy Telegraf as a sidecar proxy to the Ingress controller configured to listen UDP with the socket listener input and to write using anyone of the outputs plugins like InfluxDB, Apache Kafka, Prometheus, etc.. (recommended)
    •  
 
It's important to remember that there's no DNS resolver at this stage so you will have to configure an ip address to nginx.ingress.kubernetes.io/influxdb-host. If you deploy Influx or Telegraf as sidecar (another container in the same pod) this becomes straightforward since you can directly use 127.0.0.1.
 
Backend Protocol
 
Using backend-protocol annotations is possible to indicate how NGINX should communicate with the backend service. (Replaces secure-backends in older versions) Valid Values: HTTP, HTTPS, GRPC, GRPCS, AJP and FCGI
 
By default NGINX uses HTTP.
 
Example:
 
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
+
 
Backend Protocol
 
Using backend-protocol annotations is possible to indicate how NGINX should communicate with the backend service. (Replaces secure-backends in older versions) Valid Values: HTTP, HTTPS, GRPC, GRPCS, AJP and FCGI
 
By default NGINX uses HTTP.
 
Example:
 
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
 
 
Use Regex
 
 
Attention
 
When using this annotation with the NGINX annotation nginx.ingress.kubernetes.io/affinity of type cookie, nginx.ingress.kubernetes.io/session-cookie-path must be also set; Session cookie paths do not support regex.
 
 
Using the nginx.ingress.kubernetes.io/use-regex annotation will indicate whether or not the paths defined on an Ingress use regular expressions. The default value is false.
 
The following will indicate that regular expression paths are being used: 
nginx.ingress.kubernetes.io/use-regex: "true"
 
 
The following will indicate that regular expression paths are not being used: 
nginx.ingress.kubernetes.io/use-regex: "false"
 
 
When this annotation is set to true, 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.
 
Additionally, if the rewrite-target 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.
 
Please read about ingress path matching before using this modifier.
 
Satisfy
 
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.
 
nginx.ingress.kubernetes.io/satisfy: "any"