Emile Vauge created Traefik and is the CTO of Traefik Labs. Nicolas Mengin is a Traefik maintainer who leads its Gateway API implementation. In this 44-minute Devoxx France 2025 session (recorded in Paris in April 2025, in French), they cover why Kubernetes needed a second specification for exposing workloads, how Gateway API is structured, and two recorded demos on Traefik. The slides and manifests are in nmengin/devoxx-2025.
The core claim: Gateway API is not only the future of Kubernetes networking, it is already usable, and a new project should start on it instead of planning an Ingress migration in a year or two.
Why Ingress wasn’t enough
Kubernetes and Traefik both appeared in 2015. The first need was to put a container on the internet in a standard way, and Ingress was the answer: one resource, neutral across implementations. Its strength is simplicity. It routes HTTP by host, path and wildcard, has a default backend for requests that match no rule, and supports TLS. That is the whole spec.
For a basic route it delivers on neutrality. The same Ingress works on NGINX and Traefik, and only the ingress class changes. Real workloads need more:
- TCP and UDP, for applications that aren’t HTTP
- mTLS between clients and servers
- Advanced matching: by method, regex, AND/OR between rules
- Rate limiting, retries, canary releases
- Authentication and CORS policies
- Header and response modification
- Multi-tenancy and namespace isolation on shared clusters
Two structural problems sit under that list. There is no separation of concerns: an Ingress is one resource that devs and ops can all edit the same way, so safe multi-tenancy isn’t possible. And the only extension mechanism is annotations.
Annotations are key-value strings. ingress-nginx has 117 of them, which Vauge compares to an aircraft cockpit. They are unstructured, can’t be validated against a schema, and are easy to get wrong. His example is one Ingress with mTLS, sticky sessions and CORS on NGINX:
| Feature | Annotations needed on ingress-nginx |
|---|---|
| mTLS | 4 |
| Sticky sessions | 3 at minimum (5 in the example) |
| CORS (enable, two origins, restrict methods) | 3 |
The same setup on Traefik uses annotations for sticky sessions, but custom resources for mTLS (TLSOption) and CORS (a middleware). So the Ingress that was meant to be vendor-neutral can’t be moved from one controller to another.
Vendor CRDs, then a shared spec
Vendors reacted by designing their own structured resources. Traefik shipped IngressRoute in 2019, and Contour built HTTPProxy. Both are validated CRDs and far more capable than annotations, but each is tied to one vendor, so migration is still hard.
Gateway API started the same year under the name Service APIs. It took four years to reach v1.0, the production-ready release, at the end of 2023.
The role split: ops own the entry points, devs own the routes
Gateway API’s base principle is separation of concerns. It defines two broad roles and gives each its own resources:
| Resource | Owner | What it defines |
|---|---|---|
GatewayClass |
Ops | Which gateway controller handles the gateways attached to it (the equivalent of an IngressClass) |
Gateway |
Ops | The entry points into the cluster: ports, protocols, TLS, and which routes may attach |
HTTPRoute and other routes |
Dev | How an application is exposed: hostnames, path prefixes, matches, filters, backends |
Devs get RBAC on routes only, so a developer can’t change the port the cluster listens on.
Put a basic Ingress beside the equivalent Gateway API resources and the difference is that everything on the Gateway API side is structured and schema-validated. The entry-point annotations become listeners on a Gateway. The path matching moves to the HTTPRoute. Header modification, which Traefik did with a middleware, becomes a filter.
Gateway controllers and conformance
A gateway controller is a reverse proxy that implements the Gateway API specification: Traefik, Envoy, NGINX, Kong and others. Features come in three support levels:
| Level | Meaning |
|---|---|
| Core | Must be implemented to call yourself a gateway controller |
| Extended | Defined by the spec, optional to implement |
| Implementation-specific | Outside the spec, provided by one controller |
The spec ships a conformance test suite. For each Gateway API version, controllers run it and publish a report, so you can compare which extended features each one supports before choosing.
Gateway API resources are CRDs that you install yourself. Their version is not tied to the Kubernetes version, so you pick each independently.
On Traefik, the Helm chart enables the Gateway API provider, creates a default GatewayClass, and can create a default Gateway (the demo turns that off and writes its own).
GatewayClass
A GatewayClass is a small object. It names the controller, and it has an optional parametersRef that points at a controller-specific configuration object. When the class is bound, the controller loads that configuration.
Gateway and listeners
A Gateway attaches to exactly one GatewayClass and carries a list of listeners. Listeners are where entry points are defined and where route attachment is restricted. Each one sets:
- Port and protocol:
HTTP,HTTPS, and for layer 4TCP,TLS,UDP. Layer 4 is still experimental.TLShere means TCP with routing on the SNI. - Hostname: expected in the request host or the SNI. A route whose hostnames don’t intersect with it can’t attach.
- allowedRoutes: restricts routes by namespace (
Same,All, or aSelectoron namespace labels) and by kind (for example onlyHTTPRoute). - tls (HTTPS and TLS listeners):
Terminateon the gateway, with certificates from Secrets, orPassthroughto the backend, which works only for TCP streams.
For multi-tenancy, put two listeners on one Gateway with the same port and different hostnames, and let each accept routes from a different set of namespaces.
listeners:
- name: websecure
port: 8443
protocol: HTTPS
hostname: "*.docker.localhost"
allowedRoutes:
namespaces:
from: Selector
selector:
matchLabels:
type: tls-routes
kinds:
- kind: HTTPRoute
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: external-certs
namespace: routes
Routes, matches and filters
Routes are protocol-oriented: HTTPRoute (the most used), GRPCRoute, and at layer 4 TCPRoute, TLSRoute and UDPRoute. The layer 4 routes are experimental, and SIG Network is still discussing whether TCPRoute and TLSRoute should merge.
A route spec has these parts:
- parentRefs: the Gateways to attach to. A route can attach to several, in other namespaces, and
sectionNamenarrows it to one listener. - hostnames: must overlap the listener’s hostname for the route to attach.
- matches: on path, headers, method and query parameters. Conditions inside one match are ANDed, and separate matches are ORed.
- backendRefs: one or more Services, with weights. An 80/20 split between two backends gives you a canary deployment.
- filters: operations on requests and responses.
rules:
- matches:
- path: { type: PathPrefix, value: /api }
method: GET
headers:
- name: app
value: v2
- path: { type: PathPrefix, value: /else }
backendRefs:
- name: app-v1
port: 80
weight: 80
- name: app-v2
port: 80
weight: 20
Filters follow the same support levels as the rest of the spec:
| Filter type | Example | Who implements it |
|---|---|---|
| Core | RequestHeaderModifier |
Every gateway controller |
| Extended | URLRewrite |
Optional per controller (Traefik does) |
ExtensionRef |
Any Traefik middleware | One controller |
Demo 1: a first route
Traefik is installed with the Kubernetes Ingress provider disabled, the Gateway API provider and its experimental channel enabled, and no default Gateway. Mengin inspects resources with gwctl, the kubectl counterpart for Gateway API objects. On a GatewayClass it shows the features the controller supports and the Gateways attached to it.
The Gateway traefik-gateway-http lives in the traefik namespace, listens for HTTP on *.docker.localhost, and accepts routes from its own namespace only. The HTTPRoute in the same namespace matches whoami.docker.localhost, sends traffic to a whoami Service, and adds a request header:
filters:
- type: RequestHeaderModifier
requestHeaderModifier:
add:
- name: x-devoxx
value: Paris-2025
After applying, the GatewayClass lists the Gateway, the Gateway’s status lists the attached HTTPRoute and the Service behind it, and a curl returns the whoami page with the added header.
Demo 2: cross-namespace references and TLS to the backend
Two more objects come in here.
ReferenceGrant allows references across namespaces: a route to a Service, or a Gateway to a Secret. You create it in the namespace of the target object. from lists the kind and namespace allowed to reference (today HTTPRoute or Gateway), and to lists what they may reach, optionally down to a single named Service or Secret.
BackendTLSPolicy makes the gateway open a TLS connection to the backend while the route stays HTTP. A TLS listener in passthrough mode also reaches a TLS backend, but then you lose HTTP routing and filters. With the policy, the gateway terminates TLS, then forges a new HTTPS request to the backend with the right SNI. It sets the hostname to send as SNI (it must match the backend’s certificate), where to find the CA (a ConfigMap, or well-known CAs), and the target Service. It must live in the same namespace as that Service. At the time of the talk it was experimental and expected to move to standard soon, which is why the demo enables the experimental channel.
The pieces, in order:
- A
whoami-tlsDeployment serves HTTPS on 8443 with certificates from a Secret, and its Service setsappProtocol: https. - A new Gateway,
traefik-gateway-https, has an HTTPS listener that accepts only HTTPRoutes from namespaces labelledtype=tls-routes, terminates TLS, and takes its certificate from a Secret in theroutesnamespace. - A ReferenceGrant in
routeslets Gateways fromtraefikread Secrets there. - An HTTPRoute in
routesattaches to thewebsecurelistener, matches the exact path/whoami, and points atwhoami-tls:8443in thewhoaminamespace. - A ReferenceGrant in
whoamilets HTTPRoutes fromroutesreach thewhoami-tlsService only. - A BackendTLSPolicy in
whoamitargets the Service, sets the SNI hostname and references theinternal-caConfigMap.
kind: BackendTLSPolicy
apiVersion: gateway.networking.k8s.io/v1alpha3
metadata:
name: whoami-policy
namespace: whoami
spec:
targetRefs:
- group: ""
kind: Service
name: whoami-tls
validation:
hostname: whoami-tls.docker.localhost
caCertificateRefs:
- group: ""
kind: ConfigMap
name: internal-ca
A curl over HTTPS with the right hostname and path gets the gateway’s certificate and a response from the TLS backend.
How the spec evolves: GEPs and channels
Gateway API is run by SIG Network’s Gateway API subproject. Every new feature goes through a GEP (Gateway Enhancement Proposal): discussion with the maintainers, a written spec, an implementation. Once stable enough it enters the experimental channel. That means two things: the spec may still change, and a feature that doesn’t get enough use can be removed. Promotion to the standard channel can take months or years.
What was not in the standard channel at the time of the talk:
| Feature | Status then |
|---|---|
| mTLS (client certificate validation) | Experimental |
| Session stickiness (cookies) | Experimental |
| BackendTLSPolicy | Experimental |
| TCPRoute, TLSRoute | Experimental |
| CORS filter | Experimental from v1.3 |
Vauge adds that Traefik’s observability is still more granular on Ingress and IngressRoute than on Gateway API, and expects that gap to close quickly. Enabling the experimental channel is a normal way to use the spec, as long as you know which features you depend on.
What v1.3 brings
v1.2 was the stable release, and v1.3 was at release candidate stage. Its contents, as described in the talk (the final release is covered in the Kubernetes v1.3 announcement):
| Change | Channel | What it does |
|---|---|---|
| Percentage-based request mirroring | Standard | Mirror a share of requests to a second backend and raise it gradually, for progressive rollouts or debugging |
| CORS filter | Experimental | CORS configuration on an HTTPRoute |
XListenerSet |
Experimental | Group listeners together and reuse them |
XBackendTrafficPolicy |
Experimental | Retry budgets, so a burst of retries can’t overload a backend, like a circuit breaker inside the retry |
Try it yourself
The commands come from the demo repo’s README. You need Docker, k3d, kubectl, helm and curl.
1. Create the cluster without the bundled Traefik:
git clone https://github.com/nmengin/devoxx-2025 && cd devoxx-2025
k3d cluster create devoxx \
--port 80:80@loadbalancer --port 443:443@loadbalancer \
--port 8080:8080@loadbalancer --port 9090:9090@loadbalancer \
--k3s-arg "--disable=traefik@server:0"
How to check it worked: kubectl get nodes shows one node in Ready.
2. Install the experimental Gateway API CRDs:
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/experimental-install.yaml
How to check it worked: kubectl get crd | grep gateway.networking.k8s.io lists gatewayclasses, gateways, httproutes, referencegrants and backendtlspolicies, among others.
3. Install Traefik with the repo’s values file. It disables the Ingress provider, enables kubernetesGateway with experimentalChannel: true, and sets gateway.enabled: false:
helm repo add --force-update traefik https://traefik.github.io/charts
helm upgrade --install --create-namespace --namespace traefik \
traefik traefik/traefik -f ./traefik_values.yaml
How to check it worked: kubectl get gatewayclass shows traefik with ACCEPTED set to True, and http://dashboard.docker.localhost/ opens the Traefik dashboard. With gwctl installed, gwctl describe gatewayclass traefik also lists the supported features.
4. Deploy the first route:
kubectl apply -f manifests/01-first-route
curl http://whoami.docker.localhost/
The listener port is 8000 because that is the container port of Traefik’s web entry point, which the chart publishes as port 80.
How to check it worked: kubectl get gateway,httproute -n traefik shows traefik-gateway-http with PROGRAMMED set to True and httproute-whoami. The curl output includes the line X-Devoxx: Paris-2025.
5. Deploy the cross-namespace TLS backend. The repo’s certs/ folder is empty. Add a certificate and key for the gateway (external-crt.pem, external-key.pem), a certificate and key for whoami-tls.docker.localhost (internal-crt.pem, internal-key.pem), and the CA that signed the internal pair (internal-rootCA.pem). Then:
kubectl create namespace routes
kubectl label namespace routes type=tls-routes --overwrite
kubectl create namespace whoami
kubectl create secret tls external-certs --namespace routes \
--cert=./certs/external-crt.pem --key=./certs/external-key.pem
kubectl create secret tls internal-certs --namespace whoami \
--cert=./certs/internal-crt.pem --key=./certs/internal-key.pem
kubectl create configmap internal-ca --namespace whoami \
--from-file ca.crt=./certs/internal-rootCA.pem
kubectl apply -f manifests/02-refgrant-backentlspolicy
curl -k https://whoami-tls.docker.localhost/whoami
Drop -k if your machine trusts the CA behind the external certificate.
How to check it worked: the curl output starts with Name: tls-whoami. kubectl get httproute -n routes shows httproute-whoami-tls, and kubectl describe gateway -n traefik traefik-gateway-https reports one attached route on the websecure listener. To see the permission model working, delete one ReferenceGrant (kubectl delete referencegrant -n whoami allow-whoami-traffic) and the same curl stops reaching the backend. Re-apply the manifests to restore it.
6. Clean up: k3d cluster delete devoxx.
How to check it worked: k3d cluster list no longer shows devoxx.
How it ties together
- Ingress standardised only host, path and TLS. Everything else went into unvalidated annotations that differ per controller, so it was never portable in practice.
- Gateway API replaces annotations with structured CRDs and splits them by role: ops own
GatewayClassandGateway, devs own routes. - A GatewayClass picks the controller, a Gateway defines listeners (port, protocol, hostname, TLS, allowed routes), and a route attaches to listeners and maps matches to backends through filters.
- Core, extended and implementation-specific support levels, plus published conformance reports, tell you what a given controller really supports.
- Crossing a namespace always needs consent from the target side:
allowedRouteson the listener, a ReferenceGrant for Secrets and Services. - BackendTLSPolicy gives you TLS to the backend without giving up HTTP routing and filters.
- Features move from GEP to the experimental channel to standard. Check which channel a feature is in before you depend on it.
- The speakers’ recommendation for a new cluster: start on Gateway API now.