Kubernetes providers

Kubernetes routing is by far the largest provider surface. Five separate providers live under pkg/provider/kubernetes/, each handling a different resource model.

The five providers

Provider	Package	Resources
Ingress	pkg/provider/kubernetes/ingress	Standard networking.k8s.io/v1.Ingress.
IngressRoute (CRD)	pkg/provider/kubernetes/crd	Traefik's own CRDs (IngressRoute, IngressRouteTCP, IngressRouteUDP, Middleware, MiddlewareTCP, TraefikService, TLSOption, TLSStore, ServersTransport).
Gateway API	pkg/provider/kubernetes/gateway	gateway.networking.k8s.io and the experimental sub-APIs.
Ingress-NGINX shim	pkg/provider/kubernetes/ingress-nginx	Reads NGINX-flavored Ingress annotations and renders them as Traefik configuration.
Knative Serving	pkg/provider/kubernetes/knative	serving.knative.dev resources.

The shared client bootstrapping (in-cluster vs out-of-cluster, kubeconfig discovery, namespaces, label-selector filtering) lives in pkg/provider/kubernetes/k8s/.

Ingress

pkg/provider/kubernetes/ingress/ consumes plain Kubernetes Ingress resources. Annotations like traefik.ingress.kubernetes.io/router.entrypoints configure router-level fields that aren't expressible in the standard schema.

A typical Ingress becomes one router (per host/path) and one service (the backend). The provider supports:

• IngressClass filtering — only Ingresses with the configured class are picked up.
• defaultBackend — emits a router with no rule when set.
• TLS — converts Ingress TLS sections to dynamic certificates references.

IngressRoute (CRD)

The CRD provider exposes the full Traefik configuration model directly as Kubernetes resources. Files:

File	Resource
ingressroute.go	IngressRoute, IngressRouteTCP, IngressRouteUDP.
middleware.go, middlewaretcp.go	Middleware resources.
traefikservice.go	Weighted/mirroring TraefikService resources.
tlsoption.go, tlsstore.go	TLS configuration resources.
serverstransport.go, serverstransporttcp.go	Upstream transport configuration.
kubernetes.go	The provider implementation that watches all of the above.

IngressRoute's match field carries a Traefik rule directly:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
spec:
  entryPoints: [websecure]
  routes:
    - match: Host(`api.example.com`) && PathPrefix(`/v1`)
      kind: Rule
      services:
        - name: api
          port: 8080
      middlewares:
        - name: rate-limit

Generated Go types and the typed client live in pkg/provider/kubernetes/crd/generated/. They are produced by script/code-gen.sh (run by make generate-crd).

Gateway API

pkg/provider/kubernetes/gateway/ implements the Gateway API spec. It watches Gateway, GatewayClass, HTTPRoute, TLSRoute, TCPRoute, and GRPCRoute and translates them into Traefik dynamic configuration.

Conformance is enforced by a dedicated CI workflow:

make test-gateway-api-conformance

The integration test (integration/gateway_api_conformance_test.go) runs the upstream conformance suite against a live Traefik image.

Ingress-NGINX

pkg/provider/kubernetes/ingress-nginx/ reads Ingress resources annotated for the Ingress-NGINX controller and translates the NGINX-specific annotations to Traefik configuration. This is a migration shim: someone moving from Ingress-NGINX to Traefik can keep their existing manifests and have them work, with caveats documented in the official migration guide.

The package shares logic with pkg/middlewares/ingressnginx/ for header/path transformations. The recent commit "Use a metamodel to generate dynamic configuration in ingress-nginx" tightened the translation by introducing a metamodel that disambiguates which annotation maps to which Traefik primitive.

Knative

pkg/provider/kubernetes/knative/ adapts Knative Serving resources (Routes, Configurations, Revisions) into Traefik routers/services. Knative's traffic-splitting between revisions is honored.

The integration test (integration/knative_conformance_test.go) runs the Knative conformance suite via:

make test-knative-conformance

Common implementation patterns

All five providers share:

• Client construction in pkg/provider/kubernetes/k8s/client.go. Handles in-cluster, out-of-cluster (kubeconfig), and per-API-group typed clients.
• Informer-based caching — providers use client-go informers to watch and cache resources. The cache is queried per apply, not per request.
• Status reporting — IngressRoute and Gateway API resources have status subresources Traefik updates with the result of applying the route. The status writer is in pkg/provider/kubernetes/crd/kubernetes_dispatch.go (CRD) and pkg/provider/kubernetes/gateway/kubernetes.go (Gateway).
• Namespace and label-selector filtering — every provider supports namespaces: and labelSelector: static-config fields.

Multi-cluster and federated setups

Each Kubernetes provider has its own endpoint, token, certAuthFilePath settings — you can run multiple instances in the same Traefik configuration to aggregate routes across clusters. The aggregator deduplicates by name/provider, so cross-cluster name collisions need namespacing.

Tests

• Each subpackage has its own *_test.go covering fixture-based table tests.
• integration/k8s_test.go exercises the providers end-to-end against a kindest cluster.
• integration/gateway_api_conformance_test.go and integration/knative_conformance_test.go run upstream conformance suites.

Entry points for modification

• A new CRD or annotation: add Go types under pkg/provider/kubernetes/crd/ (or update the relevant translator), regenerate clientsets via make generate-crd, update conformance fixtures.
• Tightening Gateway API behavior: usually a small change in pkg/provider/kubernetes/gateway/kubernetes.go plus a conformance run.
• Migration features for Ingress-NGINX: extend the metamodel under pkg/provider/kubernetes/ingress-nginx/.