Traefik Kubernetes Ingress NGINX Documentation

Since v3.18

The Traefik Hub API Gateway Kubernetes Ingress NGINX provider is a Kubernetes Ingress controller; i.e, it manages access to cluster services by supporting the Ingress specification. It also supports some of the ingress-nginx annotations on ingresses to customize their behavior.

NGINX Ingress Controller Retirement

The Kubernetes NGINX Ingress Controller project has announced its retirement in March 2026 and will no longer receive updates or security patches. Traefik provides a migration path by supporting NGINX annotations, allowing you to transition your workloads without rewriting all your Ingress configurations. For more information about the NGINX Ingress Controller retirement, see the official Kubernetes blog announcement.

Ingress Discovery

The Kubernetes Ingress NGINX provider is discovering by default all Ingresses in the cluster, which may lead to duplicated routers if you are also using the Kubernetes Ingress provider. We recommend to use IngressClass for the Ingresses you want to be handled by this provider, or to use the watchNamespace or watchNamespaceSelector options to limit the discovery of Ingresses to a specific namespace or set of namespaces.

Disable the kubernetesIngress provider when using NGINX annotations

The kubernetesIngress provider is enabled by default in Traefik Hub API Gateway and will pick up your Ingress objects before kubernetesIngressNGINX does. When that happens, the NGINX-specific annotations (including all WAF/ModSecurity annotations) are silently ignored because the route is owned by the wrong provider.

To make sure NGINX annotations are honored, explicitly disable the default Ingress provider in your Helm values:

providers:
  kubernetesIngressNGINX:
    enabled: true
    ingressClassByName: true
  kubernetesIngress:
    enabled: false

You can confirm which provider owns a route in the Traefik Dashboard — the provider column should read kubernetesIngressNGINX.

---

Configuration Example

As this provider is an experimental feature, it needs to be enabled in the experimental and in the provider sections of the configuration. You can enable the Kubernetes Ingress NGINX provider as detailed below:

Install Configuration

providers:
  kubernetesIngressNGINX: {}

Helm Chart Values

# values.yaml
providers:
  kubernetesIngressNGINX:
    enabled: true

The provider then watches for incoming ingresses events, such as the example below, and derives the corresponding Routing Configuration from it, which in turn creates the resulting routers, services, handlers, etc.

Configuration Options

Field	Description	Default	Required
providers. providersThrottleDuration	Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event. If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded. This option cannot be set per provider, but the throttling algorithm applies to each of them independently.	2s	No
providers .kubernetesIngressNGINX.endpoint	Server endpoint URL. More information here.	""	No
providers. kubernetesIngressNGINX.token	Bearer token used for the Kubernetes client configuration.	""	No
providers. kubernetesIngressNGINX.certAuthFilePath	Path to the certificate authority file. Used for the Kubernetes client configuration.	""	No
providers. kubernetesIngressNGINX.throttleDuration	Minimum amount of time to wait between two Kubernetes events before producing a new configuration. This prevents a Kubernetes cluster that updates many times per second from continuously changing your Traefik Hub API Gateway configuration. If empty, every event is caught.	0s	No
providers .kubernetesIngressNGINX.watchNamespace	Namespace the controller watches for updates to Kubernetes objects. All namespaces are watched if this parameter is left empty.	""	No
providers. kubernetesIngressNGINX.watchNamespaceSelector	Selector selects namespaces the controller watches for updates to Kubernetes objects.	""	No
providers .kubernetesIngressNGINX.ingressClass	Name of the ingress class this controller satisfies.	""	No
providers. kubernetesIngressNGINX.controllerClass	Ingress Class Controller value this controller satisfies.	""	No
providers .kubernetesIngressNGINX.watchIngressWithoutClass	Define if Ingress Controller should also watch for Ingresses without an IngressClass or the annotation specified.	false	No
providers .kubernetesIngressNGINX.ingressClassByName	Define if Ingress Controller should watch for Ingress Class by Name together with Controller Class.	false	No
providers .kubernetesIngressNGINX.publishService	Service that fronts the Ingress controller (typically the LoadBalancer Service). When set, the controller publishes that Service's address into the status.loadBalancer.ingress field of every matching Ingress, so external tools (DNS controllers, kubectl get ingress, etc.) can report the actual external entry point of your traffic. Takes the form namespace/name.	""	No
providers. kubernetesIngressNGINX.publishStatusAddress	Customized address (or addresses, separated by comma) to set as the load-balancer status of Ingress objects this controller satisfies.	""	No
providers. kubernetesIngressNGINX.defaultBackendService	Service used to serve HTTP requests not matching any known server name (catch-all). Takes the form 'namespace/name'.	""	No
providers. kubernetesIngressNGINX.disableSvcExternalName	Disable support for Services of type ExternalName.	false	No
providers. kubernetesIngressNGINX.allowSnippetAnnotations	Enables parsing and adding -snippet annotations/directives.	false	No
providers. kubernetesIngressNGINX.strictValidatePathType	Rejects the entire Ingress when any path contains regex characters and pathType is Prefix or Exact.	true	No
providers. kubernetesIngressNGINX.allowCrossNamespaceResources	Allow Ingress to reference resources (e.g. ConfigMaps, Secrets) in different namespaces.	false	No
providers. kubernetesIngressNGINX.globalAllowedResponseHeaders	List of allowed response headers inside the custom-headers annotation. It is required to configure it for the custom headers annotation to take effect.	[]	No
providers. kubernetesIngressNGINX.httpEntryPoint	EntryPoint used for HTTP requests handled by this provider. When set, it overrides the default entry point selection for Ingresses managed by kubernetesIngressNGINX.	""	No
providers. kubernetesIngressNGINX.httpsEntryPoint	EntryPoint used for HTTPS requests handled by this provider. When set, it overrides the default entry point selection for Ingresses managed by kubernetesIngressNGINX.	""	No
providers. kubernetesIngressNGINX.ipAllowListStrategy	Defines the IP strategy used to determine the client IP for the allowlist-source-range and whitelist-source-range annotations. When set, the strategy is applied to every generated IPAllowList middleware.	-	No
providers. kubernetesIngressNGINX.ipAllowListStrategy.depth	Number of trusted proxy hops to skip when extracting the client IP from the X-Forwarded-For header. 0 disables depth-based extraction.	0	No
providers. kubernetesIngressNGINX.ipAllowListStrategy.excludedIPs	List of IPs to exclude when scanning the X-Forwarded-For header to find the client IP.	[]	No
providers. kubernetesIngressNGINX.ipAllowListStrategy.ipv6Subnet	IPv6 subnet size used to group IPv6 addresses when checking the allow list. 0 disables subnet grouping.	0	No
providers. kubernetesIngressNGINX.modsec.snippet	Default ModSecurity directive snippet applied to all ingresses. When set, ModSecurity is enabled by default (opt-out model). More information here.	""	No
providers. kubernetesIngressNGINX.modsec.OWASPCoreRules	Load the OWASP Core Rule Set (CRS) by default.	false	No

endpoint

The Kubernetes server endpoint URL.

When deployed into Kubernetes, Traefik Hub API Gateway reads the environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT or KUBECONFIG to construct the endpoint.

The access token is looked up in /var/run/secrets/kubernetes.io/serviceaccount/token and the SSL CA certificate in /var/run/secrets/kubernetes.io/serviceaccount/ca.crt. Both are mounted automatically when deployed inside Kubernetes.

The endpoint may be specified to override the environment variable values inside a cluster.

When the environment variables are not found, Traefik Hub API Gateway tries to connect to the Kubernetes API server with an external-cluster client.

In this case, the endpoint is required. Specifically, it may be set to the URL used by kubectl proxy to connect to a Kubernetes cluster using the granted authentication and authorization of the associated kubeconfig.

Install Configuration

providers:
  kubernetesIngressNGINX:
    endpoint: "http://localhost:8080"
    # ...

Helm Chart Values

# values.yaml
providers:
  kubernetesIngressNGINX:
    endpoint: "http://localhost:8080"

modsec

The modsec options activate ModSecurity (WAF) support powered by Coraza. When configured, the provider injects a Coraza middleware for each ingress, honoring the standard NGINX ModSecurity annotations.

The default behavior follows the NGINX ConfigMap model:

• Opt-out model: When the modsec configuration block is set (e.g. modsec.snippet or modsec.OWASPCoreRules), ModSecurity is on by default for all ingresses. Individual ingresses can opt out with enable-modsecurity: "false".
• Opt-in model: When no modsec configuration is set, ModSecurity is off by default. Individual ingresses opt in with enable-modsecurity: "true".

For annotation details, see ModSecurity / WAF annotations.

Install Configuration

providers:
  kubernetesIngressNGINX:
    modsec:
      snippet: |
        SecRuleEngine On
      OWASPCoreRules: true

Helm Chart Values

# values.yaml
providers:
  kubernetesIngressNGINX:
    modsec:
      enabled: true
      owaspCoreRules: true
      snippet: |
        SecRuleEngine On

OWASP Core Rules need a writable volume

Before enabling OWASP Core Rules, make sure your Traefik Hub deployment has a writable emptyDir volume mounted at /var/log. The default OWASP ruleset writes an audit log there and will fail to start without it.

# values.yaml
deployment:
  additionalVolumes:
    - name: varlog
      emptyDir: {}
additionalVolumeMounts:
  - name: varlog
    mountPath: /var/log
    readOnly: false

The audit log is only populated when ModSecurity runs in detection mode (SecRuleEngine DetectionOnly); requests blocked by SecRuleEngine On are not written to the audit log. This is the default Coraza behavior.

Incompatible ModSecurity directives

The Coraza engine does not support every ModSecurity directive. The following directives from the standard modsecurity.conf-recommended are not compatible with Coraza and must be removed from custom snippets:

• SecRequestBodyJsonDepthLimit
• SecAuditLogRelevantStatus
• SecUnicodeMapFile
• SecStatusEngine

Routing Configuration

See the dedicated section in routing.