Traefik & Ingresses with NGINX Annotations¶
The experimental Kubernetes Controller for Ingresses with NGINX annotations.
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.
Routing Configuration¶
The Kubernetes Ingress NGINX provider watches for incoming ingresses events, such as the example below, and derives the corresponding dynamic configuration from it, which in turn will create the resulting routers, services, handlers, etc.
Configuration Example¶
Configuring Kubernetes Ingress NGINX Controller
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: traefik-ingress-controller
rules:
- apiGroups:
- ""
resources:
- namespaces
verbs:
- get
- apiGroups:
- ""
resources:
- configmaps
- pods
- secrets
- endpoints
verbs:
- get
- list
- watch
- apiGroups:
- ""
resources:
- services
verbs:
- get
- list
- watch
- apiGroups:
- networking.k8s.io
resources:
- ingresses
verbs:
- get
- list
- watch
- apiGroups:
- networking.k8s.io
resources:
- ingresses/status
verbs:
- update
- apiGroups:
- networking.k8s.io
resources:
- ingressclasses
verbs:
- get
- list
- watch
- apiGroups:
- ""
resources:
- events
verbs:
- create
- patch
- apiGroups:
- discovery.k8s.io
resources:
- endpointslices
verbs:
- list
- watch
- get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: traefik-ingress-controller
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: traefik-ingress-controller
subjects:
- kind: ServiceAccount
name: traefik-ingress-controller
namespace: default---
apiVersion: v1
kind: ServiceAccount
metadata:
name: traefik-ingress-controller
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: traefik
labels:
app: traefik
spec:
replicas: 1
selector:
matchLabels:
app: traefik
template:
metadata:
labels:
app: traefik
spec:
serviceAccountName: traefik-ingress-controller
containers:
- name: traefik
image: traefik:v3.5
args:
- --entryPoints.web.address=:80
- --providers.kubernetesingressnginx
ports:
- name: web
containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: traefik
spec:
type: LoadBalancer
selector:
app: traefik
ports:
- name: web
port: 80
targetPort: 80---
apiVersion: apps/v1
kind: Deployment
metadata:
name: whoami
labels:
app: whoami
spec:
replicas: 2
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: whoami
spec:
selector:
app: whoami
ports:
- name: http
port: 80---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: nginx
spec:
controller: k8s.io/ingress-nginx
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: myingress
spec:
ingressClassName: nginx
rules:
- host: whoami.localhost
http:
paths:
- path: /bar
pathType: Exact
backend:
service:
name: whoami
port:
number: 80
- path: /foo
pathType: Exact
backend:
service:
name: whoami
port:
number: 80Annotations Support¶
This section lists all known NGINX Ingress annotations, split between those currently implemented (with limitations if any) and those not implemented. Limitations or behavioral differences are indicated where relevant.
Global configuration
Traefik does not expose all global configuration options to control default behaviors for ingresses.
Some behaviors that are globally configurable in NGINX (such as default SSL redirect, rate limiting, or affinity) are currently not supported and cannot be overridden per-ingress as in NGINX.
Caveats and Key Behavioral Differences¶
- Authentication: Forward auth behaves differently and session caching is not supported. NGINX supports sub-request based auth, while Traefik forwards the original request.
- Session Affinity: Only persistent mode is supported.
- Leader Election: Not supported; no cluster mode with leader election.
- Default Backend: Only
defaultBackendin Ingress spec is supported; the annotation is ignored. - Load Balancing: Only round_robin is supported; EWMA and IP hash are not supported.
- CORS: NGINX responds with all configured headers unconditionally; Traefik handles headers differently between pre-flight and regular requests.
- TLS/Backend Protocols: AUTO_HTTP, FCGI and some TLS options are not supported in Traefik.
- Path Handling: Traefik preserves trailing slashes by default; NGINX removes them unless configured otherwise.
Supported NGINX Annotations¶
Unsupported NGINX Annotations¶
Want to Add Support for More Annotations?
You can help extend support in two ways:
- Open a PR with the new annotation support.
- Reach out to the Traefik Labs support team.
All contributions and suggestions are welcome — let's build this together!