MSE Ingress gateways support the core and common annotations of NGINX Ingress gateways, making migration straightforward. They also provide 40 additional annotations for advanced traffic management.
Standard Kubernetes Ingress resources handle only Transport Layer Security (TLS) encryption and basic Layer-7 HTTP routing. NGINX Ingress controllers alone define more than 100 custom annotations to address real-world traffic management and security requirements. MSE Ingress gateways are compatible with the most common NGINX Ingress annotations so existing workloads migrate without rewriting Ingress configurations.
Overview
The following table summarizes annotation coverage at a glance.
NGINX Ingress annotation coverage
| Category | Count | Notes |
|---|---|---|
| Supported | 51 | Covers 90% of use cases |
| No configuration required | 15 | Functionality is available without explicit configuration |
| Planned | 48 | Applies to a small number of use cases |
| Not supported | 5 | Tied to NGINX-specific code snippets |
MSE implements features differently from NGINX. NGINX variables used in NGINX Ingress annotations and code snippets are not compatible with their NGINX counterparts.
Large request bodies: The nginx.ingress.kubernetes.io/proxy-body-size annotation sets a maximum request body size in NGINX, rejecting anything larger. MSE uses chunked transfer encoding instead, which handles large bodies automatically without a size limit. To set upstream connection buffer limits, configure the DownstreamConnectionBufferLimits parameter in the Parameter Settings pane of your MSE gateway.
Redirects and NGINX variables: NGINX variables (such as $host or $request_uri) in redirect annotations may work in some NGINX Ingress versions but are not officially documented. Avoid using NGINX variables for redirects in NGINX Ingress — they are not compatible with MSE.
MSE-exclusive annotations
| Category | Count | Notes |
|---|---|---|
| Extended annotations | 40 | Adds traffic governance and security protection capabilities beyond NGINX Ingress |
Annotation scope
Each annotation applies at one of three scopes:
-
Ingress — applies to the routing rules defined on the Ingress resource.
-
Domain — applies to the hostnames defined on the Ingress resource and also takes effect on the same hostnames of other Ingress resources.
-
Service — applies to the backend services referenced by the Ingress resource and also takes effect on the same services referenced by other Ingress resources.
Annotation prefixes
MSE-compatible annotations accept either the nginx or mse prefix. For example, nginx.ingress.kubernetes.io/ssl-redirect and mse.ingress.kubernetes.io/ssl-redirect are equivalent.
MSE-exclusive annotations use only the mse prefix. Replacing mse with nginx for these annotations has no effect.
Quick-reference index
The following table lists all supported annotations with their compatibility status and category. Use this table to quickly check whether a specific annotation is supported before reading the full details below.
| Annotation | Status | Category |
|---|---|---|
nginx.ingress.kubernetes.io/canary |
Compatible | Canary release |
nginx.ingress.kubernetes.io/canary-by-header |
Compatible | Canary release |
nginx.ingress.kubernetes.io/canary-by-header-value |
Compatible | Canary release |
nginx.ingress.kubernetes.io/canary-by-header-pattern |
Compatible | Canary release |
mse.ingress.kubernetes.io/canary-by-query |
MSE-exclusive | Canary release |
mse.ingress.kubernetes.io/canary-by-query-value |
MSE-exclusive | Canary release |
mse.ingress.kubernetes.io/canary-by-query-pattern |
MSE-exclusive | Canary release |
nginx.ingress.kubernetes.io/canary-by-cookie |
Compatible | Canary release |
mse.ingress.kubernetes.io/canary-by-cookie-value |
MSE-exclusive (V1.2.30+) | Canary release |
nginx.ingress.kubernetes.io/canary-weight |
Compatible | Canary release |
nginx.ingress.kubernetes.io/canary-weight-total |
Compatible | Canary release |
mse.ingress.kubernetes.io/destination |
MSE-exclusive | Multi-service routing |
mse.ingress.kubernetes.io/service-subset |
MSE-exclusive (V1.2.25+) | Service subset |
mse.ingress.kubernetes.io/subset-labels |
MSE-exclusive (V1.2.25+) | Service subset |
nginx.ingress.kubernetes.io/default-backend |
Compatible | Fallback service |
nginx.ingress.kubernetes.io/custom-http-errors |
Compatible | Fallback service |
nginx.ingress.kubernetes.io/use-regex |
Compatible | Regex path matching |
nginx.ingress.kubernetes.io/rewrite-target |
Compatible | Path rewrite |
nginx.ingress.kubernetes.io/upstream-vhost |
Compatible | Path rewrite |
nginx.ingress.kubernetes.io/ssl-redirect |
Compatible | Redirect |
nginx.ingress.kubernetes.io/force-ssl-redirect |
Compatible | Redirect |
nginx.ingress.kubernetes.io/permanent-redirect |
Compatible | Redirect |
nginx.ingress.kubernetes.io/permanent-redirect-code |
Compatible | Redirect |
nginx.ingress.kubernetes.io/temporal-redirect |
Compatible | Redirect |
nginx.ingress.kubernetes.io/app-root |
Compatible | Redirect |
nginx.ingress.kubernetes.io/enable-cors |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-origin |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-methods |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-headers |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-expose-headers |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-credentials |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-max-age |
Compatible | CORS |
mse.ingress.kubernetes.io/request-header-control-add |
MSE-exclusive | Header control |
mse.ingress.kubernetes.io/request-header-control-update |
MSE-exclusive | Header control |
mse.ingress.kubernetes.io/request-header-control-remove |
MSE-exclusive | Header control |
mse.ingress.kubernetes.io/response-header-control-add |
MSE-exclusive | Header control |
mse.ingress.kubernetes.io/response-header-control-update |
MSE-exclusive | Header control |
mse.ingress.kubernetes.io/response-header-control-remove |
MSE-exclusive | Header control |
mse.ingress.kubernetes.io/timeout |
MSE-exclusive | Timeout |
nginx.ingress.kubernetes.io/proxy-next-upstream-tries |
Compatible | Retry |
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout |
Compatible | Retry |
nginx.ingress.kubernetes.io/proxy-next-upstream |
Compatible | Retry |
mse.ingress.kubernetes.io/mirror-target-service |
MSE-exclusive | Traffic mirroring |
mse.ingress.kubernetes.io/mirror-percentage |
MSE-exclusive (V1.2.32+) | Traffic mirroring |
nginx.ingress.kubernetes.io/server-alias |
Partially compatible (V1.2.30+) | Domain alias |
mse.ingress.kubernetes.io/route-limit-rpm |
MSE-exclusive | Rate limiting (single-gateway, to be deprecated) |
mse.ingress.kubernetes.io/route-limit-rps |
MSE-exclusive | Rate limiting (single-gateway, to be deprecated) |
mse.ingress.kubernetes.io/route-limit-burst-multiplier |
MSE-exclusive | Rate limiting (single-gateway, to be deprecated) |
mse.ingress.kubernetes.io/rate-limit |
MSE-exclusive (V1.2.25+) | Rate limiting (global) |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code |
MSE-exclusive (V1.2.25+) | Rate limiting (global) |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type |
MSE-exclusive (V1.2.25+) | Rate limiting (global) |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body |
MSE-exclusive (V1.2.25+) | Rate limiting (global) |
mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url |
MSE-exclusive (V1.2.25+) | Rate limiting (global) |
mse.ingress.kubernetes.io/concurrency-limit |
MSE-exclusive (V1.2.25+) | Concurrency control |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code |
MSE-exclusive (V1.2.25+) | Concurrency control |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type |
MSE-exclusive (V1.2.25+) | Concurrency control |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body |
MSE-exclusive (V1.2.25+) | Concurrency control |
mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url |
MSE-exclusive (V1.2.25+) | Concurrency control |
nginx.ingress.kubernetes.io/backend-protocol |
Partially compatible | Backend protocol |
nginx.ingress.kubernetes.io/load-balance |
Partially compatible | Load balancing |
nginx.ingress.kubernetes.io/upstream-hash-by |
Partially compatible | Load balancing |
mse.ingress.kubernetes.io/warmup |
MSE-exclusive | Service warm-up |
nginx.ingress.kubernetes.io/affinity |
Compatible | Cookie affinity |
nginx.ingress.kubernetes.io/affinity-mode |
Partially compatible | Cookie affinity |
nginx.ingress.kubernetes.io/session-cookie-name |
Compatible | Cookie affinity |
nginx.ingress.kubernetes.io/session-cookie-path |
Compatible | Cookie affinity |
nginx.ingress.kubernetes.io/session-cookie-max-age |
Compatible | Cookie affinity |
nginx.ingress.kubernetes.io/session-cookie-expires |
Compatible | Cookie affinity |
nginx.ingress.kubernetes.io/whitelist-source-range |
Compatible | IP access control |
nginx.ingress.kubernetes.io/denylist-source-range |
Compatible (V1.2.31+) | IP access control |
mse.ingress.kubernetes.io/blacklist-source-range |
MSE-exclusive | IP access control |
mse.ingress.kubernetes.io/domain-whitelist-source-range |
MSE-exclusive | IP access control |
mse.ingress.kubernetes.io/domain-blacklist-source-range |
MSE-exclusive | IP access control |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection |
MSE-exclusive | Connection pool |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint |
MSE-exclusive | Connection pool |
mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection |
MSE-exclusive | Connection pool |
mse.ingress.kubernetes.io/tls-min-protocol-version |
MSE-exclusive | TLS (client-to-gateway) |
mse.ingress.kubernetes.io/tls-max-protocol-version |
MSE-exclusive | TLS (client-to-gateway) |
nginx.ingress.kubernetes.io/ssl-cipher |
Compatible | TLS (client-to-gateway) |
mse.ingress.kubernetes.io/auth-tls-secret |
Partially compatible | TLS (client-to-gateway) |
nginx.ingress.kubernetes.io/proxy-ssl-secret |
Compatible | TLS (gateway-to-backend) |
nginx.ingress.kubernetes.io/proxy-ssl-name |
Compatible | TLS (gateway-to-backend) |
nginx.ingress.kubernetes.io/proxy-ssl-server-name |
Compatible | TLS (gateway-to-backend) |
nginx.ingress.kubernetes.io/auth-type |
Partially compatible | Authentication |
nginx.ingress.kubernetes.io/auth-secret |
Compatible | Authentication |
nginx.ingress.kubernetes.io/auth-secret-type |
Compatible | Authentication |
nginx.ingress.kubernetes.io/auth-realm |
Compatible | Authentication |
Supported annotations
Traffic governance
Canary release
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/canary |
Ingress | Compatible | Enables canary release for the Ingress. |
nginx.ingress.kubernetes.io/canary-by-header |
Ingress | Compatible | Splits traffic by request header key. |
nginx.ingress.kubernetes.io/canary-by-header-value |
Ingress | Compatible | Splits traffic by request header value. Supports exact matching. |
nginx.ingress.kubernetes.io/canary-by-header-pattern |
Ingress | Compatible | Splits traffic by request header value. Supports regular expression matching. |
mse.ingress.kubernetes.io/canary-by-query |
Ingress | MSE-exclusive | Splits traffic by URL query parameter key. |
mse.ingress.kubernetes.io/canary-by-query-value |
Ingress | MSE-exclusive | Splits traffic by URL query parameter value. Supports exact matching. |
mse.ingress.kubernetes.io/canary-by-query-pattern |
Ingress | MSE-exclusive | Splits traffic by URL query parameter value. Supports regular expression matching. |
nginx.ingress.kubernetes.io/canary-by-cookie |
Ingress | Compatible | Splits traffic by cookie key. |
mse.ingress.kubernetes.io/canary-by-cookie-value |
Ingress | MSE-exclusive (requires gateway V1.2.30 or later) | Splits traffic by cookie value. Supports exact matching. |
nginx.ingress.kubernetes.io/canary-weight |
Ingress | Compatible | Sets the traffic weight for the canary service. |
nginx.ingress.kubernetes.io/canary-weight-total |
Ingress | Compatible | Sets the total weight used for traffic splitting calculations. |
Multi-service routing
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/destination |
Ingress | MSE-exclusive | Distributes traffic across multiple services by weight. |
Syntax: {weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}
Configuring this annotation overrides the destination services for all routing rules on the Ingress. If the syntax is invalid, the annotation is ignored and the original routing rules remain in effect.
Example:
annotations:
# Route 60% of traffic to foo and 40% to bar
mse.ingress.kubernetes.io/destination: |
60% foo.default.svc.cluster.local:8080
40% bar.default.svc.cluster.local:9090Service subset
Use service subsets when a single Kubernetes Service manages multiple deployments — for example, a stable version and a canary version. A subset directs requests to a specific group of pods.
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/service-subset |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Routes requests to a pod subset of the target service. When mse.ingress.kubernetes.io/subset-labels is not set, the routing behavior depends on this annotation's value: set it to "" or base to target pods with opensergo.io/canary: "" or pods without the opensergo.io/canary label prefix; set it to any other value (for example, gray) to target pods with the label opensergo.io/canary-gray: gray. When mse.ingress.kubernetes.io/subset-labels is set, requests are forwarded only to pods whose labels match the key-value pairs defined there. If no pods match the label, requests fall back to all pods of the service. |
mse.ingress.kubernetes.io/subset-labels |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Optional. Use with mse.ingress.kubernetes.io/service-subset to specify the labels that define the pod subset. |
Fallback service
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/default-backend |
Ingress | Compatible | Specifies a fallback service. If no nodes are available for the service defined in an Ingress rule, requests are forwarded to this service. |
nginx.ingress.kubernetes.io/custom-http-errors |
Ingress | Compatible | Works with nginx.ingress.kubernetes.io/default-backend. When a backend returns one of the specified HTTP status codes, the request is forwarded to the fallback service with the path rewritten to /. |
Regex path matching
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/use-regex |
Ingress | Compatible | Enables regular expression matching for the path defined in the Ingress rule. Uses RE2 syntax. |
Path rewrite
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/rewrite-target |
Ingress | Compatible | Rewrites the request path before forwarding to the backend. Supports capture groups. |
nginx.ingress.kubernetes.io/upstream-vhost |
Ingress | Compatible | Rewrites the Host header to the specified value when forwarding requests to the backend. |
Redirect
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/ssl-redirect |
Ingress | Compatible | Redirects HTTP requests to HTTPS. |
nginx.ingress.kubernetes.io/force-ssl-redirect |
Ingress | Compatible | Forcibly redirects HTTP requests to HTTPS. |
nginx.ingress.kubernetes.io/permanent-redirect |
Ingress | Compatible | Redirects requests to the specified URL with a permanent redirect. |
nginx.ingress.kubernetes.io/permanent-redirect-code |
Ingress | Compatible | Sets the HTTP status code for permanent redirects. |
nginx.ingress.kubernetes.io/temporal-redirect |
Ingress | Compatible | Redirects requests to the specified URL with a temporary redirect. |
nginx.ingress.kubernetes.io/app-root |
Ingress | Compatible | Redirects requests from / to the specified application root path. |
Cross-origin resource sharing (CORS)
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/enable-cors |
Ingress | Compatible | Enables cross-origin resource sharing (CORS). |
nginx.ingress.kubernetes.io/cors-allow-origin |
Ingress | Compatible | Sets the allowed origins for CORS requests. |
nginx.ingress.kubernetes.io/cors-allow-methods |
Ingress | Compatible | Sets the allowed HTTP methods for CORS requests, such as GET, POST, and PUT. |
nginx.ingress.kubernetes.io/cors-allow-headers |
Ingress | Compatible | Sets the allowed request headers for CORS requests. |
nginx.ingress.kubernetes.io/cors-expose-headers |
Ingress | Compatible | Sets the response headers exposed to browsers in CORS responses. |
nginx.ingress.kubernetes.io/cors-allow-credentials |
Ingress | Compatible | Specifies whether credentials can be included in CORS requests. |
nginx.ingress.kubernetes.io/cors-max-age |
Ingress | Compatible | Sets the duration for which preflight request results are cached. |
Header control
Header control annotations on base routes and canary routes are independent and validated separately. Configure different header policies for base-route traffic and canary-route traffic as needed.
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/request-header-control-add |
Ingress | MSE-exclusive | Adds a header to requests before forwarding to the backend. If the header already exists, the new value is appended to the original. For a single header, use a key-value pair. For multiple headers, use a YAML literal block (|) with one key-value pair per line. |
mse.ingress.kubernetes.io/request-header-control-update |
Ingress | MSE-exclusive | Modifies a header in requests before forwarding to the backend. If the header exists, the new value overwrites the original. Same syntax as request-header-control-add. |
mse.ingress.kubernetes.io/request-header-control-remove |
Ingress | MSE-exclusive | Removes headers from requests before forwarding to the backend. For a single header, specify the key. For multiple headers, separate keys with commas. |
mse.ingress.kubernetes.io/response-header-control-add |
Ingress | MSE-exclusive | Adds a header to responses before forwarding to the client. If the header already exists, the new value is appended to the original. Same syntax as request-header-control-add. |
mse.ingress.kubernetes.io/response-header-control-update |
Ingress | MSE-exclusive | Modifies a header in responses before forwarding to the client. If the header exists, the new value overwrites the original. Same syntax as request-header-control-add. |
mse.ingress.kubernetes.io/response-header-control-remove |
Ingress | MSE-exclusive | Removes headers from responses before forwarding to the client. For a single header, specify the key. For multiple headers, separate keys with commas. |
Timeout
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/timeout |
Ingress | MSE-exclusive | Sets the request timeout in seconds. No timeout is applied by default. Applies at the application layer, not at the TCP transport layer. |
Retry
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/proxy-next-upstream-tries |
Ingress | Compatible | Sets the maximum number of retry attempts. Default: 3. |
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout |
Ingress | Compatible | Sets the timeout for retry attempts in seconds. No timeout is applied by default. |
nginx.ingress.kubernetes.io/proxy-next-upstream |
Ingress | Compatible | Sets the conditions that trigger a retry. See NGINX retry mechanism for supported values. |
Traffic mirroring
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/mirror-target-service |
Ingress | MSE-exclusive | Forwards a copy of incoming traffic to the specified service. Format: namespace/name:port. The namespace defaults to the Ingress gateway's namespace. The port defaults to the first port of the service. |
mse.ingress.kubernetes.io/mirror-percentage |
Ingress | MSE-exclusive (requires gateway V1.2.32 or later) | Sets the percentage of traffic to mirror. Valid values: 0–100. Default: 100. |
Domain alias
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/server-alias |
Domain | Partially compatible — exact match domains and wildcard domains only (requires gateway V1.2.30 or later) | Defines a domain alias for the hostname in the Ingress spec. The alias inherits the TLS, routing, and traffic governance configuration of the source domain. |
Rate limiting (single-gateway, to be deprecated)
When throttling is triggered, the response body is local_rate_limited. The response status code depends on gateway version: gateways earlier than V1.2.23 return 503; V1.2.23 and later return 429.
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/route-limit-rpm |
Ingress | MSE-exclusive | Sets the maximum requests per minute (RPM) on a route. The burst limit equals this value multiplied by mse.ingress.kubernetes.io/route-limit-burst-multiplier. |
mse.ingress.kubernetes.io/route-limit-rps |
Ingress | MSE-exclusive | Sets the maximum requests per second (RPS) on a route. The burst limit equals this value multiplied by mse.ingress.kubernetes.io/route-limit-burst-multiplier. |
mse.ingress.kubernetes.io/route-limit-burst-multiplier |
Ingress | MSE-exclusive | Sets the burst limit multiplier. Default: 5. |
Rate limiting (global, recommended)
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/rate-limit |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the maximum RPS for global rate limiting on a route. |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the HTTP response code returned when rate limiting is triggered. Default: 429. Mutually exclusive with mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url. |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the format of the rate-limit response body. Default: text. Setting text returns Content-Type: text/plain; charset=UTF-8. Setting JSON returns Content-Type: application/json; charset=UTF-8. |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the body content of the rate-limit response. Default: sentinel rate limited. |
mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Redirects requests to the specified URL when rate limiting is triggered. Mutually exclusive with mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code. |
Concurrency control (global)
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/concurrency-limit |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the maximum number of concurrent requests on a route. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the HTTP response code when concurrency control is triggered. Default: 429. Mutually exclusive with mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the format of the concurrency-limit response body. Default: text. Setting text returns Content-Type: text/plain; charset=UTF-8. Setting JSON returns Content-Type: application/json; charset=UTF-8. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Sets the body content of the concurrency-limit response. Default: sentinel rate limited. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url |
Ingress | MSE-exclusive (requires gateway V1.2.25 or later) | Redirects requests to the specified URL when concurrency control is triggered. Mutually exclusive with mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code. |
Backend protocol
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/backend-protocol |
Service | Partially compatible — AJP and FCGI are not supported | Sets the protocol used to communicate with backend services. Default: HTTP. Supported values: HTTP, HTTP2, HTTPS, gRPC, gRPCS. |
Load balancing
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/load-balance |
Service | Partially compatible — the Exponentially Weighted Moving Average (EWMA) algorithm is not supported and falls back to round-robin | Sets the load balancing algorithm. Default: round_robin. Supported values: round_robin, least_conn, random. |
nginx.ingress.kubernetes.io/upstream-hash-by |
Service | Partially compatible — combining NGINX variables with constants is not supported | Enables consistent hashing. Supported hash key types: $request_uri (request path, including path parameters), $host (request hostname), $remote_addr (client IP address), $http_<headerName> (request header value), $arg_<varName> (URL query parameter value). |
Service warm-up (graceful start)
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/warmup |
Service | MSE-exclusive | Sets the warm-up duration in seconds. Disabled by default. Supported only with round_robin and least_conn load balancing algorithms. |
Cookie affinity
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/affinity |
Service | Compatible | Sets the affinity type. The only valid value is cookie. |
nginx.ingress.kubernetes.io/affinity-mode |
Service | Partially compatible — persistent mode is not supported |
Sets the affinity mode. The only valid value is balanced. |
nginx.ingress.kubernetes.io/session-cookie-name |
Service | Compatible | Sets the cookie name used as the hash key for session affinity. |
nginx.ingress.kubernetes.io/session-cookie-path |
Service | Compatible | Sets the path attribute of the generated session cookie. Default: /. |
nginx.ingress.kubernetes.io/session-cookie-max-age |
Service | Compatible | Sets the Max-Age of the generated session cookie in seconds. Defaults to session-level expiration. |
nginx.ingress.kubernetes.io/session-cookie-expires |
Service | Compatible | Sets the Expires attribute of the generated session cookie in seconds. Defaults to session-level expiration. |
IP address-based access control
Route-level allowlists take precedence over domain-level allowlists. Route-level blocklists take precedence over domain-level blocklists.
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/whitelist-source-range |
Ingress | Compatible | Sets an IP allowlist for the route. Accepts IP addresses and CIDR blocks, separated by commas. |
nginx.ingress.kubernetes.io/denylist-source-range |
Ingress | Compatible (requires gateway V1.2.31 or later) | Sets an IP blocklist for the route. Accepts IP addresses and CIDR blocks, separated by commas. Takes precedence over mse.ingress.kubernetes.io/blacklist-source-range. |
mse.ingress.kubernetes.io/blacklist-source-range |
Ingress | MSE-exclusive | Sets an IP blocklist for the route. Accepts IP addresses and CIDR blocks, separated by commas. |
mse.ingress.kubernetes.io/domain-whitelist-source-range |
Ingress | MSE-exclusive | Sets an IP allowlist at the domain level. Accepts IP addresses and CIDR blocks, separated by commas. |
mse.ingress.kubernetes.io/domain-blacklist-source-range |
Ingress | MSE-exclusive | Sets an IP blocklist at the domain level. Accepts IP addresses and CIDR blocks, separated by commas. |
Connection pool (gateway to backend)
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection |
Service | MSE-exclusive | Sets the maximum number of TCP connections between the gateway and the backend service. |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint |
Service | MSE-exclusive | Sets the maximum number of TCP connections between the gateway and a single backend pod. |
mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection |
Service | MSE-exclusive | Sets the maximum number of HTTP requests per connection between the gateway and the backend service. |
Security protection
TLS between clients and the gateway
| Annotation | Scope | Support status | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/tls-min-protocol-version |
Domain | MSE-exclusive | Sets the minimum TLS version. Default: TLSv1.0. Valid values: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. |
mse.ingress.kubernetes.io/tls-max-protocol-version |
Domain | MSE-exclusive | Sets the maximum TLS version. Default: TLSv1.3. Valid values: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. |
nginx.ingress.kubernetes.io/ssl-cipher |
Domain | Compatible | Sets the TLS cipher suites, separated by commas. Takes effect only for TLS 1.0–1.2 handshakes. Default cipher suites: ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-SHA, ECDHE-RSA-AES128-SHA, AES128-GCM-SHA256, AES128-SHA, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES256-SHA, AES256-GCM-SHA384, AES256-SHA. |
mse.ingress.kubernetes.io/auth-tls-secret |
Domain | Partially compatible — the secret name must follow the format <domain-certificate-secret-name>-cacert |
Specifies the CA certificate the gateway uses to verify client certificates during mutual TLS (mTLS) handshakes. |
TLS between the gateway and backend services
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/proxy-ssl-secret |
Service | Compatible | Specifies the client certificate the gateway presents to backend services during TLS handshakes. |
nginx.ingress.kubernetes.io/proxy-ssl-name |
Service | Compatible | Sets the Server Name Indication (SNI) value used during the TLS handshake with the backend. |
nginx.ingress.kubernetes.io/proxy-ssl-server-name |
Service | Compatible | Enables or disables SNI during the TLS handshake with the backend. |
Authentication
Basic authentication
| Annotation | Scope | Support status | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/auth-type |
Ingress | Partially compatible — only basic authentication is supported |
Sets the authentication type. |
nginx.ingress.kubernetes.io/auth-secret |
Ingress | Compatible | Specifies the secret that contains credentials for the route. Format: <namespace>/<name>. |
nginx.ingress.kubernetes.io/auth-secret-type |
Ingress | Compatible | Sets the format of the secret data. auth-file: the auth key holds newline-separated username:password pairs. auth-map: each key is a username and its value is the password. |
nginx.ingress.kubernetes.io/auth-realm |
Ingress | Compatible | Sets the authentication realm. Credentials are shared within a realm. |
For the full list of NGINX Ingress annotations, see Annotations.