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 false.  

-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/default are used.
  • If /etc/nginx/secrets/default doesn’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.

Format: <namespace>/<name>  

-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.

Format: <namespace>/<name>  

-enable-custom-resources

Enables custom resources.

Default true.  

-enable-preview-policies

Enables preview policies. This flag is deprecated. To enable OIDC Policies please use -enable-oidc instead.

Default false.  

-enable-oidc

Enables OIDC policies.

Default false.  

-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.  

-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.

Default nginx.  

-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.

  • Default for NGINX is nginx.ingress.tmpl.
  • Default for NGINX Plus is nginx-plus.ingress.tmpl.  

-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.

Format: <namespace>/<name>  

-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.

Default is 60000.  

-nginx-status

Enable the NGINX stub_status, or the NGINX Plus API.

Default true.  

-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>

Log level for V logs.  

-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.

Format: <namespace>/<name>  

-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-address is 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-plus is 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-plus and enable-app-protect are 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-plus is 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-plus and enable-app-protect-dos are 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-plus and enable-app-protect-dos are 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-plus and enable-app-protect-dos are 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-plus and enable-app-protect-dos are 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.

Default true.  

-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.

Default false.