ConfigMap¶
The controller reads its NGINX settings from one ConfigMap, named with -nginx-configmaps=<namespace>/<name>. With the
Helm chart you set its keys in controller.config.entries. A change of the ConfigMap is applied without a restart; with
-dynamic-upstreams NGINX is reloaded only when the generated configuration actually changes. The keys are those of
NGINX Ingress Controller. With -ingress-nginx-defaults the ConfigMap also accepts the keys of ingress-nginx, which are
translated as described in ingress-nginx keys.
An invalid value is ignored: the controller logs it and records a Warning event on the ConfigMap, and the default stays in effect. Annotations on an Ingress override the ConfigMap for that Ingress.
Defaults with and without -ingress-nginx-defaults¶
-ingress-nginx-defaults (Helm: controller.ingressNginxDefaults or controller.ingressNginxCompat) replaces the
defaults of NGINX Ingress Controller with those of ingress-nginx for everything neither the ConfigMap nor an annotation
sets. In the tables below, the column "Default" is the value without the flag and "ingress-nginx defaults" is the value
with it; an empty cell means it does not change. "not set" means wxingress does not render the directive, so NGINX's
own default applies.
Keys of wxingress¶
Timeouts and proxying¶
| Key | Default | ingress-nginx defaults | Description |
|---|---|---|---|
proxy-connect-timeout |
60s |
5s |
proxy_connect_timeout. A bare number is taken as seconds. |
proxy-read-timeout |
60s |
proxy_read_timeout. |
|
proxy-send-timeout |
60s |
proxy_send_timeout. |
|
client-max-body-size |
1m |
client_max_body_size. ingress-nginx's proxy-body-size. |
|
client-body-buffer-size |
not set | 8k |
client_body_buffer_size. |
proxy-buffering |
true |
false |
proxy_buffering. |
proxy-buffers |
not set | 4 4k |
proxy_buffers, for example 8 4k. |
proxy-buffer-size |
not set | 4k |
proxy_buffer_size. With ingress-nginx defaults and no proxy-buffers, it also sizes the four buffers of proxy_buffers, as in ingress-nginx. |
proxy-busy-buffers-size |
not set | proxy_busy_buffers_size. |
|
proxy-max-temp-file-size |
not set | proxy_max_temp_file_size. |
|
proxy-hide-headers |
Comma-separated headers from the upstream not passed to the client (proxy_hide_header). |
||
proxy-pass-headers |
Comma-separated headers passed to the client that NGINX would hide (proxy_pass_header). |
With ingress-nginx defaults, Ingress locations also get ingress-nginx's retry settings (proxy_next_upstream error
timeout, 3 tries), proxy_redirect off, its headers to the upstream (X-Request-ID, X-Scheme,
X-Forwarded-Scheme, X-Original-Forwarded-For, X-Forwarded-For $remote_addr) and WebSocket support. These have no
ConfigMap key in wxingress; the annotations of ingress-nginx set them per Ingress.
Upstreams¶
| Key | Default | ingress-nginx defaults | Description |
|---|---|---|---|
lb-method |
random two least_conn |
The load-balancing method of upstreams: round_robin, least_conn, ip_hash, random, random two, random two least_conn, least_time header, least_time last_byte (each optionally with inflight), or hash <key> [consistent]. With -dynamic-upstreams, an Ingress with ingress-nginx's load-balance, upstream-hash-by or affinity annotations is balanced by the wxingress module instead. |
|
keepalive |
0 (no keepalive) |
64 |
Idle keepalive connections to each upstream, per worker. ingress-nginx's upstream-keepalive-connections (320 there, for all backends together; every Service port is its own upstream here). |
max-fails |
1 |
max_fails of upstream servers. |
|
fail-timeout |
10s |
fail_timeout of upstream servers. |
|
upstream-zone-size |
256k |
The shared memory zone of each upstream. No effect with -dynamic-upstreams: the upstreams of Ingresses and VirtualServers then share one zone of 64m. |
Redirects, HSTS and HTTP/2¶
| Key | Default | ingress-nginx defaults | Description |
|---|---|---|---|
ssl-redirect |
true |
Redirect plain HTTP to HTTPS for hosts with TLS. | |
redirect-to-https |
false |
Redirect to HTTPS based on X-Forwarded-Proto, for TLS terminated in front of wxingress. |
|
http-redirect-code |
301 |
308 |
The status code of the HTTPS redirect: 301, 302, 307 or 308. |
hsts |
false |
true |
Send Strict-Transport-Security. With ingress-nginx defaults the other hsts-* keys apply without hsts being set, as in ingress-nginx. |
hsts-max-age |
2592000 |
31536000 |
max-age of HSTS. |
hsts-include-subdomains |
false |
true |
includeSubDomains. |
hsts-preload |
true |
false |
preload. |
hsts-behind-proxy |
false |
Send HSTS based on X-Forwarded-Proto. |
|
http2 |
false |
true |
HTTP/2 on TLS listeners. ingress-nginx's use-http2. |
TLS¶
| Key | Default | ingress-nginx defaults | Description |
|---|---|---|---|
ssl-protocols |
not set (NGINX: TLSv1.2 TLSv1.3) |
TLSv1.2 TLSv1.3 |
ssl_protocols. |
ssl-ciphers |
not set (NGINX: HIGH:!aNULL:!MD5) |
ingress-nginx's ECDHE/DHE AES-GCM and CHACHA20 list | ssl_ciphers. |
ssl-prefer-server-ciphers |
false |
true |
ssl_prefer_server_ciphers. |
ssl-dhparam-file |
The content of a DH parameters file (PEM). |
Client address and forwarded headers¶
| Key | Default | Description |
|---|---|---|
real-ip-header |
not set | real_ip_header, for example X-Forwarded-For or proxy_protocol. Ignored with TLS passthrough, which sets proxy_protocol itself. |
set-real-ip-from |
not set | Comma-separated trusted addresses or CIDRs (set_real_ip_from). |
real-ip-recursive |
false |
real_ip_recursive. |
proxy-protocol |
false |
Accept the PROXY protocol on the listeners. ingress-nginx's use-proxy-protocol. |
use-forwarded-headers |
false |
Pass on the client's X-Forwarded-* headers instead of replacing them. Mutually exclusive with disable-forwarded-headers. |
disable-forwarded-headers |
false |
Do not send X-Forwarded-* headers to upstreams. Requires -enable-snippets. |
Headers¶
| Key | Default | Description |
|---|---|---|
add-header |
Comma-separated Name: value response headers added at the http level. |
|
add-header-inherit |
not set | add_header_inherit: on, off or merge. |
global-allowed-response-headers |
Comma-separated headers that ingress-nginx's custom-headers annotation may set, as the ingress-nginx key of the same name. |
|
server-tokens |
true (on) |
server_tokens. ingress-nginx defaults: off. |
Logging¶
| Key | Default | Description |
|---|---|---|
error-log-level |
notice |
error_log level. |
access-log |
/dev/stdout main |
Only a syslog: destination is accepted, for example syslog:server=localhost:514. |
access-log-off |
false |
Turn the access log off. |
default-server-access-log-off |
false |
Turn the access log of the default server off. |
log-format |
wxingress's main format |
The HTTP access log format; several lines are joined. ingress-nginx's log-format-upstream. |
log-format-escaping |
default |
default, json or none. |
stream-log-format, stream-log-format-escaping |
The same for the stream (TCP/UDP) log. |
Note
ingress-nginx's log variables ($proxy_upstream_name, $req_id, ...) do not exist in wxingress. A
log-format-upstream taken over from ingress-nginx must be adapted, or NGINX refuses the configuration.
Workers and hash tables¶
| Key | Default | ingress-nginx defaults | Description |
|---|---|---|---|
worker-processes |
auto |
worker_processes. |
|
worker-connections |
1024 |
16384 |
worker_connections. ingress-nginx's max-worker-connections. |
worker-rlimit-nofile |
not set | worker_rlimit_nofile. ingress-nginx's max-worker-open-files. |
|
worker-cpu-affinity |
not set | worker_cpu_affinity. |
|
worker-shutdown-timeout |
not set | 240s |
worker_shutdown_timeout. |
keepalive-timeout |
75s |
Client keepalive_timeout. ingress-nginx's keep-alive. |
|
keepalive-requests |
1000 |
Client keepalive_requests. ingress-nginx's keep-alive-requests. |
|
server-names-hash-bucket-size |
256 |
server_names_hash_bucket_size. |
|
server-names-hash-max-size |
1024 |
server_names_hash_max_size. |
|
map-hash-bucket-size |
256 |
map_hash_bucket_size. |
|
map-hash-max-size |
2048 |
map_hash_max_size. |
|
variables-hash-bucket-size |
256 |
variables_hash_bucket_size. |
|
variables-hash-max-size |
1024 |
2048 |
variables_hash_max_size. |
Snippets and templates¶
| Key | Description |
|---|---|
main-snippets |
Lines for the main context. |
http-snippets |
Lines for the http context. |
server-snippets |
Lines for every server of Ingresses and VirtualServers. A resource with server snippets of its own (nginx.org/server-snippets, ingress-nginx's server-snippet, a VirtualServer's server-snippets) gets those instead. |
location-snippets |
Lines for every location of Ingresses and VirtualServers. A resource with location snippets of its own gets those instead. |
stream-snippets |
Lines for the stream context. |
main-template, ingress-template, virtualserver-template, transportserver-template |
Replacement templates. See the warning on custom templates. |
Snippets in the ConfigMap do not need -enable-snippets; only whoever can edit the ConfigMap can set them.
Default server and status¶
| Key | Default | Description |
|---|---|---|
default-server-return |
404 |
What the default server answers for unknown hosts: a status code, or a code and text or URL, as in return. With -default-backend-service, that Service answers instead unless this key is set. |
external-status-address |
The address written into the status of Ingresses (with -report-ingress-status); wins over -external-service. |
OpenTelemetry¶
| Key | Default | Description |
|---|---|---|
otel-exporter-endpoint |
not set | The OTLP/gRPC collector, host:port. Without it no traces are exported. |
otel-exporter-header-name, otel-exporter-header-value |
A header sent to the collector, for example for authentication. | |
otel-service-name |
The service name of the spans. | |
otel-trace-in-http |
false |
Trace every request (otel_trace on in the http context). |
otel-trace-context |
not set | extract, inject, propagate or ignore (otel_trace_context). |
OIDC¶
oidc-pkce-timeout (90s), oidc-id-tokens-timeout (1h), oidc-access-tokens-timeout (1h),
oidc-refresh-tokens-timeout (8h), oidc-sids-timeout (8h), oidc-pkce-zone-size (128K),
oidc-id-tokens-zone-size, oidc-access-tokens-zone-size, oidc-refresh-tokens-zone-size and
oidc-sids-zone-size (1M each) size and expire the key-value zones of NGINX Plus's OIDC. They are rendered only with
-nginx-plus. wxingress's own OIDC, which serves oidc Policies in the wxingress module without NGINX Plus, keeps no
key-value zones: its session is a sealed cookie that lasts as long as the ID token in it and is renewed with the refresh
token. These keys are therefore validated (an invalid value gets a Warning event) but have no effect.
NGINX Plus and App Protect only¶
These keys are inherited from NGINX Ingress Controller and only have an effect with -nginx-plus or App Protect,
which wxingress does not build. For their meaning see the upstream
ConfigMap reference.
| Keys | Without NGINX Plus or App Protect |
|---|---|
resolver-addresses, resolver-ipv6, resolver-timeout, resolver-valid |
Ignored with a Warning event (requires NGINX Plus). |
zone-sync, zone-sync-port, zone-sync-resolver-addresses, zone-sync-resolver-ipv6, zone-sync-resolver-valid |
zone-sync gets a Warning event (requires NGINX Plus); the others need zone-sync. |
app-protect-compressed-requests-action, app-protect-cookie-seed, app-protect-cpu-thresholds, app-protect-failure-mode-action, app-protect-physical-memory-util-thresholds, app-protect-reconnect-period-seconds, app-protect-dos-arb-fqdn, app-protect-dos-log-format, app-protect-dos-log-format-escaping |
Not read. |
oidc-* |
Validated, not rendered (see OIDC). |
license-token-secret-name, ssl-verify, ssl-certificate-secret-name, ssl-trusted-certificate-secret-name, enforce-initial-report, usage-report-endpoint, usage-report-interval, usage-report-proxy-host |
Not read from this ConfigMap at all: upstream reads them from the separate -mgmt-configmap, which needs -nginx-plus. Accepted here without a warning. |
Keys without effect
limit-req-status-code, max-conns and slow-start are accepted without a warning (also with
-ingress-nginx-defaults) but are never read, so they have no effect. In particular limit-req-status-code does not
change the status of rate-limited requests: ingress-nginx's limit-rps/limit-rpm annotations answer 503, and
nginx.org/limit-req-* answers 429 (503 with ingress-nginx defaults) unless nginx.org/limit-req-reject-code sets
another code.
ingress-nginx keys¶
With -ingress-nginx-defaults the ConfigMap also takes the keys of ingress-nginx, so that the controller.config of an
ingress-nginx Helm release can be used as it is. Without the flag only the keys of wxingress are read, and other keys
are ignored without a warning.
Every key that is not a key of wxingress is handled in one of the ways below. A key that is neither listed here nor
a wxingress key gets a Warning event on the ConfigMap (<key> is not supported by wxingress and is ignored).
Taken under the same name¶
These ingress-nginx keys are also keys of wxingress and mean the same: proxy-connect-timeout, proxy-read-timeout,
proxy-send-timeout, proxy-buffering, proxy-buffer-size, proxy-busy-buffers-size, proxy-max-temp-file-size,
client-body-buffer-size, ssl-redirect, http-redirect-code, hsts, hsts-include-subdomains, hsts-max-age,
hsts-preload, ssl-protocols, ssl-ciphers, server-tokens, use-forwarded-headers, error-log-level,
worker-processes, worker-cpu-affinity, worker-shutdown-timeout, map-hash-bucket-size,
variables-hash-bucket-size, variables-hash-max-size, otel-service-name, global-allowed-response-headers.
Renamed¶
| ingress-nginx key | wxingress key |
|---|---|
proxy-body-size |
client-max-body-size |
keep-alive |
keepalive-timeout (a bare number gets s) |
keep-alive-requests |
keepalive-requests |
upstream-keepalive-connections |
keepalive |
max-worker-connections |
worker-connections |
max-worker-open-files |
worker-rlimit-nofile |
use-proxy-protocol |
proxy-protocol (and the real client address from the PROXY header, see below) |
use-http2 |
http2 |
hide-headers |
proxy-hide-headers |
server-name-hash-max-size, server-name-hash-bucket-size |
server-names-hash-max-size, server-names-hash-bucket-size |
log-format-upstream, log-format-stream |
log-format, stream-log-format (with a warning: ingress-nginx's variables do not exist here) |
log-format-escape-json: "true", log-format-escape-none: "true" |
log-format-escaping: json, none |
main-snippet, http-snippet, server-snippet, location-snippet, stream-snippet |
main-snippets, http-snippets, server-snippets, location-snippets, stream-snippets |
otlp-collector-host, otlp-collector-port |
otel-exporter-endpoint (host:port, port 4317 by default) |
enable-opentelemetry |
otel-trace-in-http |
opentelemetry-trust-incoming-span |
otel-trace-context: propagate (default, as ingress-nginx), inject for "false" |
Where the ConfigMap has both the ingress-nginx key and the wxingress key it is renamed to, the wxingress key wins and the ingress-nginx key gets a warning.
Client address: enable-real-ip¶
With enable-real-ip: "true" or use-proxy-protocol: "true", the client address is taken as in ingress-nginx:
| ingress-nginx | wxingress |
|---|---|
use-proxy-protocol: "true" |
real-ip-header: proxy_protocol |
enable-real-ip: "true" with forwarded-for-header |
real-ip-header: <forwarded-for-header> (default X-Forwarded-For) |
proxy-real-ip-cidr |
set-real-ip-from (default 0.0.0.0/0, as ingress-nginx) |
real-ip-header and set-real-ip-from, if set in the ConfigMap, win. Without enable-real-ip: "true" or
use-proxy-protocol: "true", forwarded-for-header and proxy-real-ip-cidr are dropped without a warning.
Warning
As in ingress-nginx, enable-real-ip without proxy-real-ip-cidr trusts the header from every address. Set
proxy-real-ip-cidr to the addresses of your load balancer.
Allow and deny lists¶
allowlist-source-range (or the older whitelist-source-range; allowlist-source-range wins),
denylist-source-range and block-cidrs take comma-separated addresses and CIDRs (IPv4 and IPv6) and are rendered as
deny and allow rules in every server of Ingresses and VirtualServers: the denied ranges first, then the allowed
ones followed by deny all. NGINX's own servers (status, the module's API) are not affected. An Ingress with source
ranges of its own (annotations) uses those instead in its locations, as in ingress-nginx. A value that is not a list
of addresses or CIDRs denies every request, with a warning and an error in the log.
The rules are rendered on their own, independently of snippets: a resource with server snippets of its own
(nginx.org/server-snippets or ingress-nginx's server-snippet on an Ingress, server-snippets in a VirtualServer)
replaces the ConfigMap's server-snippets, but keeps these rules. Up to 5.7.1-wx9 they were part of the ConfigMap's
server-snippets and were lost with them.
Accepted without effect¶
These keys are accepted silently - no Warning event, no log line - because wxingress behaves as their usual setting anyway. They are not read, so whatever value they have is dropped:
| Key | Why |
|---|---|
allow-snippet-annotations, annotations-risk-level |
Snippets are controlled by -enable-snippets. |
enable-annotation-validations |
Annotations are always validated. |
strict-validate-path-type |
wxingress does not validate path types strictly. |
allow-cross-namespace-resources |
Secrets and ConfigMaps of other namespaces are never taken. |
no-tls-redirect-locations |
ACME challenges are never redirected. |
compute-full-forwarded-for |
With ingress-nginx defaults, X-Forwarded-For is $remote_addr, ingress-nginx's default (false). |
generate-request-id |
With ingress-nginx defaults, X-Request-ID is sent, ingress-nginx's default (true). |
ssl-session-tickets |
NGINX's default applies. |
Warning
Because these keys are not read, a non-default value is dropped without a warning:
compute-full-forwarded-for: "true" still sends X-Forwarded-For $remote_addr (with ingress-nginx defaults; the
client's X-Forwarded-For is not appended), generate-request-id: "false" still sends X-Request-ID, and
ssl-session-tickets: "false" (ingress-nginx's default) leaves NGINX's session tickets on. Check a ConfigMap taken
from ingress-nginx for these keys.
Keys that restrict access: served without them¶
ingress-nginx keys that restrict who gets an answer and that wxingress does not implement are reported loudly: a Warning event on the ConfigMap and an error in the controller log saying that the Ingresses are served without them.
| Key | Instead |
|---|---|
global-auth-* (global-auth-url, global-auth-signin, ...) |
ingress-nginx's auth-url annotations per Ingress, or an external-auth Policy. |
enable-modsecurity, enable-owasp-modsecurity-crs, modsecurity-snippet |
No ModSecurity in wxingress. Use a WAF in front of it or in the application path. |
block-user-agents, block-referers |
A map in http-snippets with a check in server-snippets, or a WAF. |
global-rate-limit-* |
ingress-nginx's limit-rps/limit-rpm annotations (per controller pod), or a rate-limit Policy. |
Danger
Check the controller log and the ConfigMap's events after the switch. An Ingress that relied on one of these keys for protection is reachable without it.
Not supported¶
Every other ingress-nginx key is ignored with a Warning event. Common ones and what to do:
| Keys | Alternative |
|---|---|
proxy-next-upstream, proxy-next-upstream-timeout, proxy-next-upstream-tries, proxy-request-buffering, proxy-redirect-from, proxy-http-version, proxy-buffers-number, proxy-cookie-domain, proxy-cookie-path |
Not ConfigMap keys in wxingress: the annotations of the same name per Ingress. With ingress-nginx defaults the defaults of ingress-nginx apply (for example 3 tries, proxy_redirect off, proxy_buffers 4 4k) whatever the ConfigMap says. For the buffers, the wxingress key proxy-buffers ("4 4k") sets the same. |
load-balance, upstream-keepalive-time, -timeout, -requests |
lb-method and keepalive in the ConfigMap; load-balance per Ingress as an annotation. |
use-gzip, gzip-*, enable-brotli, brotli-* |
http-snippets (gzip on; ...). |
ssl-session-cache, ssl-session-cache-size, ssl-session-timeout, ssl-buffer-size, ssl-early-data, ssl-ecdh-curve, ssl-dh-param |
http-snippets for the directives; ssl-dhparam-file for DH parameters. |
client-header-buffer-size, client-header-timeout, client-body-timeout, large-client-header-buffers, http2-max-concurrent-streams, enable-underscores-in-headers, ignore-invalid-headers |
http-snippets. NGINX's defaults equal ingress-nginx's. |
limit-conn-status-code |
ingress-nginx's limit-connections already answers 503. |
custom-http-errors |
The custom-http-errors annotation per Ingress. |
add-headers, proxy-set-headers |
add-header in the ConfigMap; custom-headers per Ingress; location-snippets. |
access-log-path, error-log-path, disable-access-log, skip-access-log-urls, enable-syslog |
access-log (syslog) and access-log-off. |
force-ssl-redirect |
The force-ssl-redirect annotation per Ingress. |
default-type, reuse-port, enable-multi-accept, bind-address, proxy-stream-* |
Not configurable. |
use-geoip2, enable-opentracing, plugins, lua-shared-dicts |
Not available: wxingress has no Lua and no GeoIP2 module. |
See ingress-nginx compatibility for how the defaults compare in detail.