From e32a5a04bc2d61d1f430063cccb12d158b3de679 Mon Sep 17 00:00:00 2001 From: Kevin Pollet Date: Thu, 2 Apr 2026 15:54:05 +0200 Subject: [PATCH] Clarify IngressClass selection logic --- .../kubernetes/kubernetes-ingress-nginx.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-ingress-nginx.md b/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-ingress-nginx.md index aa42c8acb..6b8c2cff8 100644 --- a/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-ingress-nginx.md +++ b/docs/content/reference/install-configuration/providers/kubernetes/kubernetes-ingress-nginx.md @@ -42,6 +42,12 @@ This provider discovers all Ingresses in the cluster by default, which may lead - Configure `watchNamespace` to limit discovery to specific namespaces - Use `watchNamespaceSelector` to target Ingresses based on namespace labels +### IngressClass Selection Logic + +By default, the provider selects all IngressClasses whose `spec.controller` matches `controllerClass` (default: `k8s.io/ingress-nginx`) and picks up every Ingress referencing any of them. +Setting `ingressClassByName: true` adds a second inclusion path: IngressClasses whose name matches `ingressClass` are also picked up, even if their `spec.controller` does not match `controllerClass`. +It does not narrow down the controller-based selection — both paths apply independently. + ## Configuration Example You can enable the Kubernetes Ingress NGINX provider as detailed below: @@ -114,8 +120,8 @@ This provider watches for incoming Ingress events and automatically translates N ## Configuration Options -| Field | Description | Default | Required | -|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------|:--------|:---------| +| Field | Description | Default | Required | +|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------| | `providers.providers`
`ThrottleDuration` | 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](#endpoint). | "" | No | | `providers.`
`kubernetesIngressNGINX.`
`token` | Bearer token used for the Kubernetes client configuration. | "" | No | @@ -123,11 +129,11 @@ This provider watches for incoming Ingress events and automatically translates N | `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 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. | "nginx" | No | +| `providers.`
`kubernetesIngressNGINX.`
`ingressClass` | Name of the IngressClass this controller handles. When `ingressClassByName` is `true`, IngressClasses with this name are included in discovery regardless of their `spec.controller` value. | "nginx" | 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 fronting the Ingress controller. Takes the form `namespace/name`. | "" | No | +| `providers.`
`kubernetesIngressNGINX.`
`ingressClassByName` | When `true`, any IngressClass whose **name** matches `ingressClass` is include in discovery, even if its `spec.controller` does not match `controllerClass`. This is evaluated alongside the controller-based selection, not instead of it. | false | No | +| `providers.`
`kubernetesIngressNGINX.`
`publishService` | Service fronting the Ingress controller. 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 |