The wxingress controller is configured with command-line flags on its container (/nginx-ingress -flag=value;
--flag works as well). The Helm chart sets them from its values, so with the chart you normally change a
Helm value rather than a flag; the column "Helm value" names the value that sets each flag. Settings
of NGINX itself (timeouts, buffers, TLS, logging) are not flags but keys of the ConfigMap.
Boolean flags take -flag, -flag=true or -flag=false. Values written as <namespace>/<name> refer to a
Kubernetes object. An invalid value of most flags stops the controller at startup with a message naming the flag.
Defaults of the binary and of the chart
The defaults below are those of the controller binary. The Helm chart sets some of them differently, for
example -watch-ingress-without-class (on in the chart) and -report-ingress-status (on in the chart). See
Helm values for the chart's defaults.
The class of the controller. Ingresses whose ingressClassName (or kubernetes.io/ingress.class annotation) names it are served, whether or not an IngressClass of that name exists; a missing IngressClass, or one with another controller, only logs a warning. VirtualServers, VirtualServerRoutes and TransportServers without ingressClassName are served as well.
Comma-separated list of IngressClass spec.controller values. The Ingresses of every IngressClass whose controller is in the list are served, whatever the class is called. Add k8s.io/ingress-nginx to serve the classes of ingress-nginx, beside it or in its place. Changes of IngressClasses take effect without a restart.
Serve Ingresses without any class (no ingressClassName, no kubernetes.io/ingress.class), as ingress-nginx's --watch-ingress-without-class. Without it they are served only when a served IngressClass is the cluster's default.
-watch-namespace
all namespaces
controller.watchNamespace
Comma-separated list of namespaces to watch. Mutually exclusive with -watch-namespace-label.
-watch-namespace-label
(none)
controller.watchNamespaceLabel
Watch only the namespaces with this label selector, for example foo=bar. Mutually exclusive with -watch-namespace.
-watch-secret-namespace
the watched namespaces
controller.watchSecretNamespace
Comma-separated list of namespaces to watch for Secrets, if different from the namespaces watched for other resources.
-allow-empty-ingress-host
false
controller.allowEmptyIngressHost (on with controller.ingressNginxCompat)
Accept Ingresses without a host, including an Ingress with only spec.defaultBackend (a catch-all). TLS for them comes from -default-server-tls-secret, their ports from -default-http-listener-port and -default-https-listener-port.
-enable-custom-resources
true
controller.enableCustomResources
Serve the custom resources (VirtualServer, VirtualServerRoute, TransportServer, Policy, GlobalConfiguration). Required by the Gateway API, TLS passthrough, cert-manager and external-dns support.
The GlobalConfiguration resource (<namespace>/<name>) that defines extra listeners for TransportServers. Requires -enable-custom-resources.
-enable-snippets
false
controller.enableSnippets
Allow snippets in Ingresses (server-snippet, configuration-snippet, stream-snippet, auth-snippet, nginx.org/*-snippets), VirtualServers, VirtualServerRoutes and TransportServers. Without it snippet annotations are ignored with a warning. Snippets in the ConfigMap do not need it.
-nginx-configmaps
(none)
set by the chart (controller.config, controller.customConfigMap)
The ConfigMap (<namespace>/<name>) with the NGINX settings. The controller does not start if it is set but cannot be read.
controller.ingressNginxDefaults (on with controller.ingressNginxCompat)
Use the defaults of ingress-nginx instead of those of NGINX Ingress Controller for everything neither the ConfigMap nor an annotation sets: timeouts, buffering, retries, upstream keepalive, the redirect code, HSTS, HTTP/2, TLS, the headers sent to the upstream, and WebSocket support in every Ingress location. It also makes the ConfigMap accept the keys of ingress-nginx (see ConfigMap).
-ingress-nginx-cross-namespace
false
controller.ingressNginxCrossNamespace (not set by controller.ingressNginxCompat)
Let Ingresses of different namespaces share a host as ingress-nginx does: the paths of every Ingress of the host are merged into the server of the oldest one whatever its namespace, and a canary Ingress attaches to the Ingresses of other namespaces. Whoever may create an Ingress in any namespace can then add paths to, or divert the traffic of, the hosts of every other namespace. Off, a host belongs to the namespace of the Ingress that holds it: Ingresses of other namespaces with the host lose it (with a warning), and a canary attaches only to Ingresses of its own namespace. See Ingresses written for ingress-nginx.
-dynamic-upstreams
false
controller.dynamicUpstreams (on with controller.ingressNginxCompat)
Update upstream servers, certificates, canaries and load-balancing rules through the API of the wxingress NGINX module instead of reloading NGINX. Required for canary Ingresses, ingress-nginx's balancers (ewma, chash, sticky sessions as ingress-nginx writes them) and the ingress-nginx request metrics. Ignored with -nginx-plus.
-sync-rate-limit
0.3
controller.syncRateLimit
With -dynamic-upstreams: the maximum number of NGINX reloads per second, as ingress-nginx's --sync-rate-limit. A change that comes sooner after a reload waits, and all changes that arrive meanwhile are applied in one reload. Changes that need no reload (upstream servers, canaries, certificates) do not wait. 0 disables the limit; a negative value is treated as 0.
A ConfigMap (<namespace>/<name>) of TCP services in ingress-nginx's format: "<port>": "<namespace>/<service>:<port>[:PROXY][:PROXY]". NGINX listens on the port and passes connections to the Service; the first PROXY accepts the PROXY protocol from the client, the second sends it to the Service. Watched; with -dynamic-upstreams endpoint changes need no reload.
A ConfigMap (<namespace>/<name>) of UDP services: "<port>": "<namespace>/<service>:<port>".
-default-backend-service
(none)
controller.defaultBackendService
A Service (<namespace>/<name>) that answers, as ingress-nginx's --default-backend-service, the requests for unknown hosts and paths, and the custom-http-errors of Ingresses without a default-backend annotation. Its first port is used; with -dynamic-upstreams endpoint changes need no reload.
The address the admission webhook listens on with TLS, for example :8443, as ingress-nginx's --validating-webhook. A ValidatingWebhookConfiguration sends it the Ingresses being created or updated, and it refuses those that are invalid, that have the host and path of another Ingress, that carry a snippet annotation while snippets are disabled, or whose configuration fails nginx -t. At most 4 reviews are taken at once (more get 503, so the webhook's failurePolicy applies), none bigger than 3.5 MiB, and nginx -t is stopped after 10 seconds. The webhook does not authenticate its callers: let only the API server reach it (NetworkPolicy).
-validating-webhook-certificate
/usr/local/certificates/cert
controller.admissionWebhooks.certificate
The webhook's certificate (PEM). Read again when the file changes.
-validating-webhook-key
/usr/local/certificates/key
controller.admissionWebhooks.key
The key (PEM) of the webhook's certificate.
-validating-webhook-nginx-test
true
controller.admissionWebhooks.nginxTest
Run nginx -t on the configuration an Ingress would produce. Never done while -enable-snippets is on: whoever can reach the webhook could otherwise have a snippet executed by nginx -t (CVE-2025-1974, for which ingress-nginx dropped the test entirely).
Serve the Gateway API: the GatewayClass -gateway-class if it names -gateway-controller-name, its Gateways and their routes. Requires -enable-custom-resources and the Gateway API CRDs.
The Gateway (<namespace>/<name>) that shares the address of the controller's Service (-external-service) and NGINX's default ports with Ingresses and VirtualServers, for a migration from Ingress. Its listeners may only be HTTP on 80 and HTTPS on 443. Sharing an address with other resources is a deliberate deviation from the Gateway API.
-gateway-service-type
LoadBalancer
controller.gatewayAPI.service.type
The type of the Services the controller creates for Gateways with their own address: LoadBalancer, NodePort or ClusterIP.
-gateway-listener-ports
20000-29999
controller.gatewayAPI.listenerPorts
The port range (<first>-<last>) NGINX listens on for the listeners of Gateways with their own address.
A TLS Secret (<namespace>/<name>) for the default server, and for hosts without a valid certificate of their own. Without it the file /etc/nginx/secrets/default is used. If that file does not exist either, then with -dynamic-upstreams the controller generates ingress-nginx's self-signed "Kubernetes Ingress Controller Fake Certificate" at startup, and without it TLS handshakes to the default server are rejected. The controller does not start if the Secret is set but cannot be read.
-wildcard-tls-secret
(none)
controller.wildcardTLS.secret (or .cert/.key)
A TLS Secret (<namespace>/<name>) for every Ingress or VirtualServer host that enables TLS without naming a Secret. Without it, TLS handshakes for such hosts fail.
-ssl-dynamic-reload
true
controller.enableSSLDynamicReload
Load changed certificates without reloading NGINX.
-enable-tls-passthrough
false
controller.enableTLSPassthrough
Enable TLS passthrough (also used for ingress-nginx's ssl-passthrough annotation, the equivalent of its --enable-ssl-passthrough). Requires -enable-custom-resources.
-tls-passthrough-port
443
controller.tlsPassthroughPort
The port of TLS passthrough.
-enable-cert-manager
false
controller.enableCertManager
Let cert-manager issue certificates for VirtualServers. Requires -enable-custom-resources.
The port of the HTTP default_server (and of Ingresses without a host).
-default-https-listener-port
443
controller.defaultHTTPSListenerPort
The port of the HTTPS default_server (and of Ingresses without a host).
-disable-ipv6
false
controller.disableIPV6
Do not open IPv6 listeners, for nodes without IPv6.
-nginx-reload-timeout
60000
controller.nginxReloadTimeout
How long, in milliseconds, the controller waits for a successful NGINX reload after a change or at startup.
-enable-config-safety
false
controller.enableConfigSafety
Validate the configuration before reloading NGINX.
-enable-directive-autoadjust
false
controller.directiveAutoAdjust
Adjust proxy buffer directives automatically so that they do not conflict.
-nginx-debug
false
controller.nginxDebug
Run the nginx-debug binary. Needs error-log-level: debug in the ConfigMap.
-enable-topology-aware-routing
false
controller.enableTopologyAwareRouting
Honour EndpointSlice topology hints, preferring endpoints in the same zone as the controller pod. Each replica then routes only to its own zone; spread replicas accordingly. The zone is read from the node at startup.
-main-template-path
built-in nginx.tmpl
(none)
Path to a replacement for the main NGINX configuration template.
-ingress-template-path
built-in nginx.ingress.tmpl
(none)
Path to a replacement for the Ingress template.
-virtualserver-template-path
built-in nginx.virtualserver.tmpl
(none)
Path to a replacement for the VirtualServer template.
-transportserver-template-path
built-in nginx.transportserver.tmpl
(none)
Path to a replacement for the TransportServer template.
Custom templates
Replacing a template opts out of everything wxingress renders for ingress-nginx compatibility in that template.
Prefer snippets or the ConfigMap; a replaced template must be kept in step with every wxingress release by hand.
Write the controller's external address into the status of Ingresses. Needs -external-service, -ingresslink or the ConfigMap key external-status-address.
-external-service
(none)
controller.reportIngressStatus.externalService (default: the chart's Service)
The Service whose external address is reported in the status of Ingresses, VirtualServers and VirtualServerRoutes. With the Gateway API it is also the address of the default Gateway.
-ingresslink
(none)
controller.reportIngressStatus.ingressLink
The IngressLink resource (F5 BIG-IP) whose address is reported instead. Inherited from NIC, not tested in wxingress.
Elect one leader among the replicas. Only the leader writes status and manages shared objects (for example the Services of Gateways). The leader releases its lock when it stops, so another replica takes over within seconds.
Comma-separated addresses and CIDRs allowed to read stub_status.
-enable-prometheus-metrics
false
prometheus.create (chart default true)
Export metrics in the Prometheus format: the controller's own and, with -dynamic-upstreams, the request metrics of ingress-nginx under its names and labels.
-prometheus-metrics-listen-port
9113
prometheus.port
The metrics port (1024-65535). ingress-nginx used 10254; set this if your scrape configuration expects it.
-prometheus-tls-secret
(none)
prometheus.secret
A TLS Secret (<namespace>/<name>) to serve the metrics over HTTPS.
-enable-latency-metrics
false
controller.enableLatencyMetrics
Collect upstream latency metrics. Requires -enable-prometheus-metrics, else ignored with a warning.
-latency-metrics-buckets
built-in set
controller.latencyMetricsBuckets
Comma-separated, strictly ascending bucket bounds in milliseconds for the latency histogram, for example 5,10,25,50,100,250,500,1000. Requires -enable-latency-metrics; an invalid list falls back to the default buckets.
Enable oidc Policies. Without NGINX Plus they need -dynamic-upstreams, which loads the wxingress module that implements them; see JWT and OIDC.
-oidc-revocations-configmap
(none)
set by the chart with controller.enableOIDC and dynamic upstreams
With -enable-oidc and -dynamic-upstreams: a ConfigMap (<namespace>/<name>) whose revocations end sessions of the wxingress module before their ID tokens expire. Each replica writes the logouts it handled into it, so a logout reaches all replicas without a reload.
trace, debug, info, warning, error or fatal. An invalid value falls back to info with a warning.
-log-format
glog
controller.logFormat
glog, text or json (also accepted: json-unix, json-unix-ms, text-unix, text-unix-ms). An invalid value falls back to glog with a warning.
-version
Print the version, git commit and build date, and exit.
-proxy
(none)
Connect to the Kubernetes API through kubectl proxy at this URL. For development only: NGINX is not started and no configuration is written.
-enable-telemetry-reporting
false
controller.telemetryReporting.enable
Ignored: wxingress has no telemetry. Kept so that existing arguments keep working.
Inherited from NGINX Ingress Controller, not supported in wxingress¶
wxingress is built on NGINX Ingress Controller and keeps its flags for NGINX Plus, F5 WAF (App Protect), App Protect
DoS and NGINX Agent, so that the code base stays close to upstream. wxingress ships an open-source NGINX image;
these flags are neither supported nor tested in wxingress. Their meaning is that of the upstream
NGINX Ingress Controller command-line arguments.
Flag
Default
Notes
-nginx-plus
false
NGINX Plus. Turns -dynamic-upstreams off.
-mgmt-configmap
(none)
The NGINX Plus mgmt ConfigMap. Ignored with a warning without -nginx-plus.