Command-line Arguments
The Ingress Controller supports several command-line arguments. Setting the arguments depends on how you install the Ingress Controller:
- If you’re using Kubernetes manifests (Deployment or DaemonSet) to install the Ingress Controller, to set the command-line arguments, modify those manifests accordingly. See the Installation with Manifests doc.
- If you’re using Helm to install the Ingress Controller, modify the parameters of the Helm chart that correspond to the command-line arguments. See the Installation with Helm doc.
Below we describe the available command-line arguments:
-enable-snippets
Enable custom NGINX configuration snippets in Ingress, VirtualServer, VirtualServerRoute and TransportServer resources.
-default-server-tls-secret <string>
Secret with a TLS certificate and key for TLS termination of the default server.
- If not set, certificate and key in the file
/etc/nginx/secrets/defaultare used. - If
/etc/nginx/secrets/defaultdoesn’t exist, the Ingress Controller will configure NGINX to reject TLS connections to the default server. - If a secret is set, but the Ingress Controller is not able to fetch it from Kubernetes API, or it is not set and the Ingress Controller fails to read the file “/etc/nginx/secrets/default”, the Ingress Controller will fail to start.
-wildcard-tls-secret <string>
A Secret with a TLS certificate and key for TLS termination of every Ingress/VirtualServer host for which TLS termination is enabled but the Secret is not specified.
-
If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
-
If the argument is set, but the Ingress Controller is not able to fetch the Secret from Kubernetes API, the Ingress Controller will fail to start.
-enable-custom-resources
Enables custom resources.
-enable-preview-policies
Enables preview policies. This flag is deprecated. To enable OIDC Policies please use -enable-oidc instead.
-enable-oidc
Enables OIDC policies.
-inlcude-year
Adds year to log headers.
Default false.
NOTE: This flag will be removed in release 2.7 and the year will be included by default.
-enable-leader-election
Enables Leader election to avoid multiple replicas of the controller reporting the status of Ingress, VirtualServer and VirtualServerRoute resources – only one replica will report status.
Default true.
See -report-ingress-status flag.
-enable-tls-passthrough
Enable TLS Passthrough on port 443.
Requires -enable-custom-resources.
-tls-passthrough-port <int>
Set the port for TLS Passthrough.
Format: [1024 - 65535] (default 443)
Requires -enable-custom-resources.
-enable-cert-manager
Enable x509 automated certificate management for VirtualServer resources using cert-manager (cert-manager.io).
Requires -enable-custom-resources.
-enable-external-dns
Enable integration with ExternalDNS for configuring public DNS entries for VirtualServer resources using ExternalDNS.
Requires -enable-custom-resources.
-external-service <string>
Specifies the name of the service with the type LoadBalancer through which the Ingress Controller pods are exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources.
For Ingress resources only: Requires -report-ingress-status.
-ingresslink <string>
Specifies the name of the IngressLink resource, which exposes the Ingress Controller pods via a BIG-IP system. The IP of the BIG-IP system is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources.
For Ingress resources only: Requires -report-ingress-status.
-global-configuration <string>
A GlobalConfiguration resource for global configuration of the Ingress Controller.
Format: <namespace>/<name>
Requires -enable-custom-resources.
-health-status
Adds a location “/nginx-health” to the default server. The location responds with the 200 status code for any request.
Useful for external health-checking of the Ingress Controller.
-health-status-uri <string>
Sets the URI of health status location in the default server. Requires -health-status. (default /nginx-health)
-ingress-class <string>
A class of the Ingress Controller.
A corresponding IngressClass resource with the name equal to the class must be deployed. Otherwise, the Ingress Controller will fail to start.
The Ingress Controller only processes resources that belong to its class - i.e. have the ingressClassName field resource equal to the class.
The Ingress Controller processes all the resources that do not have the ingressClassName field.
-ingress-template-path <string>
Path to the ingress NGINX configuration template for an ingress resource. Default for NGINX is nginx.ingress.tmpl; default for NGINX Plus is nginx-plus.ingress.tmpl.
-leader-election-lock-name <string>
Specifies the name of the ConfigMap, within the same namespace as the controller, used as the lock for leader election.
Requires -enable-leader-election.
-log_backtrace_at <value>
When logging hits line file:N, emit a stack trace.
-main-template-path <string>
Path to the main NGINX configuration template.
-nginx-configmaps <string>
A ConfigMap resource for customizing NGINX configuration. If a ConfigMap is set, but the Ingress Controller is not able to fetch it from Kubernetes API, the Ingress Controller will fail to start.
-nginx-debug
Enable debugging for NGINX. Uses the nginx-debug binary. Requires ’error-log-level: debug’ in the ConfigMap.
-nginx-plus
Enable support for NGINX Plus.
-nginx-reload-timeout <value>
Timeout in milliseconds which the Ingress Controller will wait for a successful NGINX reload after a change or at the initial start.
-nginx-status
Enable the NGINX stub_status, or the NGINX Plus API.
-nginx-status-allow-cidrs <string>
Add IP/CIDR blocks to the allow list for NGINX stub_status or the NGINX Plus API.
Separate multiple IP/CIDR by commas. (default 127.0.0.1,::1)
-nginx-status-port <int>
Set the port where the NGINX stub_status or the NGINX Plus API is exposed.
Format: [1024 - 65535] (default 8080)
-proxy <string>
Use a proxy server to connect to Kubernetes API started by “kubectl proxy” command. For testing purposes only.
The Ingress Controller does not start NGINX and does not write any generated NGINX configuration files to disk.
-report-ingress-status
Updates the address field in the status of Ingress resources.
Requires the -external-service or -ingresslink flag, or the external-status-address key in the ConfigMap.
-transportserver-template-path <string>
Path to the TransportServer NGINX configuration template for a TransportServer resource.
- Default for NGINX is
nginx.transportserver.tmpl. - Default for NGINX Plus is
nginx-plus.transportserver.tmpl.
-v <value>
-version
Print the version, git-commit hash and build date and exit.
-virtualserver-template-path <string>
Path to the VirtualServer NGINX configuration template for a VirtualServer resource.
- Default for NGINX is
nginx.ingress.tmpl. - Default for NGINX Plus is
nginx-plus.ingress.tmpl.
-vmodule <value>
A comma-separated list of pattern=N settings for file-filtered logging.
-watch-namespace <string>
Comma separated list of namespaces the Ingress Controller should watch for resources. By default the Ingress Controller watches all namespaces. Mutually exclusive with “watch-namespace-label”.
-watch-namespace-label <string>
Configures the Ingress Controller to watch only those namespaces with label foo=bar. By default the Ingress Controller watches all namespaces. Mutually exclusive with “watch-namespace”.
-watch-secret-namespace <string>
Comma separated list of namespaces the Ingress Controller should watch for secrets. If this arg is not configured, the Ingress Controller watches the same namespaces for all resources. See “watch-namespace” and “watch-namespace-label”.
-enable-prometheus-metrics
Enables exposing NGINX or NGINX Plus metrics in the Prometheus format.
-prometheus-metrics-listen-port <int>
Sets the port where the Prometheus metrics are exposed.
Format: [1024 - 65535] (default 9113)
-prometheus-tls-secret <string>
A Secret with a TLS certificate and key for TLS termination of the Prometheus metrics endpoint.
- If the argument is not set, the Prometheus endpoint will not use a TLS connection.
- If the argument is set, but the Ingress Controller is not able to fetch the Secret from Kubernetes API, the Ingress Controller will fail to start.
-enable-service-insight
Exposes the Service Insight endpoint for Ingress Controller.
-service-insight-listen-port <int>
Sets the port where the Service Insight is exposed.
Format: [1024 - 65535] (default 9114)
-service-insight-tls-secret <string>
A Secret with a TLS certificate and key for TLS termination of the Service Insight endpoint.
- If the argument is not set, the Service Insight endpoint will not use a TLS connection.
- If the argument is set, but the Ingress Controller is not able to fetch the Secret from Kubernetes API, the Ingress Controller will fail to start.
-spire-agent-address <string>
Specifies the address of a running Spire agent. For use with NGINX Service Mesh only.
- If the argument is set, but the Ingress Controller is unable to connect to the Spire Agent, the Ingress Controller will fail to start.
-enable-internal-routes
Enable support for internal routes with NGINX Service Mesh. For use with NGINX Service Mesh only.
Requires -spire-agent-address.
- If the argument is set, but
spire-agent-addressis not provided, the Ingress Controller will fail to start.
-enable-latency-metrics
Enable collection of latency metrics for upstreams. Requires -enable-prometheus-metrics.
-enable-app-protect
Enables support for App Protect.
Requires -nginx-plus.
- If the argument is set, but
nginx-plusis set to false, the Ingress Controller will fail to start.
-app-protect-log-level <string>
Sets log level for App Protect. Allowed values: fatal, error, warn, info, debug, trace.
Requires -nginx-plus and -enable-app-protect.
- If the argument is set, but
nginx-plusandenable-app-protectare set to false, the Ingress Controller will fail to start.
-enable-app-protect-dos
Enables support for App Protect DoS.
Requires -nginx-plus.
- If the argument is set, but
nginx-plusis set to false, the Ingress Controller will fail to start.
-app-protect-dos-debug
Enable debugging for App Protect DoS.
Requires -nginx-plus and -enable-app-protect-dos.
- If the argument is set, but
nginx-plusandenable-app-protect-dosare set to false, the Ingress Controller will fail to start.
-app-protect-dos-max-daemons
Max number of ADMD instances.
Default 1.
Requires -nginx-plus and -enable-app-protect-dos.
- If the argument is set, but
nginx-plusandenable-app-protect-dosare set to false, the Ingress Controller will fail to start.
-app-protect-dos-max-workers
Max number of nginx processes to support.
Default Number of CPU cores in the machine.
Requires -nginx-plus and -enable-app-protect-dos.
- If the argument is set, but
nginx-plusandenable-app-protect-dosare set to false, the Ingress Controller will fail to start.
-app-protect-dos-memory
RAM memory size to consume in MB
Default 50% of free RAM in the container or 80MB, the smaller.
Requires -nginx-plus and -enable-app-protect-dos.
- If the argument is set, but
nginx-plusandenable-app-protect-dosare set to false, the Ingress Controller will fail to start.
-ready-status
Enables the readiness endpoint /nginx-ready. The endpoint returns a success code when NGINX has loaded all the config after the startup.
-ready-status-port
The HTTP port for the readiness endpoint.
Format: [1024 - 65535] (default 8081)
-disable-ipv6
Disable IPV6 listeners explicitly for nodes that do not support the IPV6 stack.