We're continuing our in-depth series on Traefik 3. If you missed it, be sure to read the previous articles on migrating from Traefik v2, WASM support with Coraza WAF, Open Telemetry, and SPIFFE, Tailscale, and HTTP/3. This article dives into how to get started with GatewayAPI and Traefik.
In 2015, when Traefik was just born, Kubernetes released the first version of its Ingress specifications. The goal of Ingress was to provide a straightforward, vendor-neutral method for exposing Kubernetes services. However, the premise has quickly been broken.
While Ingress could handle basic service exposure, adding functionalities like rate-limiting or IP checking required numerous vendor-specific annotations.
To address these limitations, a new standard began to take shape in 2019: GatewayAPI was born. Officially released in its v1.0 form at the end of 2023, the GatewayAPI aims to be the new standard for exposing services in Kubernetes. It offers a set of core rules designed to meet most needs while allowing the Gateway Controller to extend these rules with their features.
Traefik has been a Kubernetes first-class citizen for a long time, initially supporting Ingress and later expanding with our IngressRoutes to surpass Ingress limitations, adding features like TCP, UDP, and structured options declaration.
We quickly embraced the big changes in Kubernetes with the Gateway API, offering early experimental support since 2022.
With the release of Traefik v3.1, we’ve taken a major step forward: our GatewayAPI provider is now production-ready. Traefik v3.1 today meets and exceeds 100% of the core requirements, as shown in our SIG network conformance tests report.
Let’s see together how you can start with GatewayAPI and Traefik v3!
Install Traefik as GatewayController
To begin, ensure you have installed the most recent version of Traefik on your Kubernetes cluster, utilizing the Helm Chart for streamlined deployment. This setup enables the GatewayAPI provider to effectively discover and expose your applications.
Define your installation configuration
First, customize your values to enable Traefik to discover GatewayAPI objects on your Kubernetes cluster. Create a values.yaml file with the following minimal configuration:
## File values.yaml ##
providers:
# Disable the Ingress provider (optional)
# We do not want to use Ingress objects anymore!
kubernetesIngress:
enabled: false
# Enable the GatewayAPI provider
kubernetesGateway:
enabled: true
# Allow the Gateway to expose HTTPRoute from all namespaces
gateway:
namespacePolicy: All
Next, execute the following commands to deploy Traefik in the traefik namespace using the previously described configuration:
$ helm repo add traefik https://traefik.github.io/charts
$ helm repo update
$ kubectl create namespace traefik
$ helm upgrade --install --version 0.29.1 --namespace traefik traefik traefik/traefik -f values.yaml
And voilà! You have deployed Traefik on your Kubernetes cluster:
$ kubectl describe deployments.apps traefik --namespace traefik
Name: traefik
Namespace: traefik
…
Containers:
traefik:
Image: docker.io/traefik:v3.1
Ports: 9100/TCP, 9000/TCP, 8000/TCP, 8443/TCP
Host Ports: 0/TCP, 0/TCP, 0/TCP, 0/TCP
Args:
--entryPoints.web.address=:8000/tcp
--entryPoints.websecure.address=:8443/tcp
--api.dashboard=true
--ping=true
--providers.kubernetescrd
--providers.kubernetesgateway
--entryPoints.websecure.http.tls=true
…
As you can see, both kubernetescrd and kubernetesgateway providers are enabled. The kubernetescrd provider allows you to define Traefik specific resources like Middlewares.
The entrypoints web and websecure will be used to expose your applications.
Additionally, when Traefik is installed with the GatewayAPI provider enabled, it automatically creates a default GatewayClass named traefik:
$ kubectl describe GatewayClass traefik
Name: traefik
…
API Version: gateway.networking.k8s.io/v1
Kind: GatewayClass
…
Controller Name: traefik.io/gateway-controller
As you can see above, the option Controller Name is set to traefik.io/gateway-controller. Thus, it allows you to expose every Gateway attached to the traefik GatewayClass using your Traefik Gateway Controller.
Additionally, the Gateway traefik-gateway is also deployed:
$ kubectl describe Gateway traefik --namespace traefik
Name: traefik-gateway
Namespace: traefik
…
API Version: gateway.networking.k8s.io/v1
Kind: Gateway
…
Spec:
Gateway Class Name: traefik
Listeners:
Allowed Routes:
Namespaces:
From: All
Name: web
Port: 8000
Protocol: HTTP
This Gateway allows you to expose HTTPRoute in HTTP on the port 8000 of your Traefik Gateway Controller.
Let’s now expose your first application using a GatewayAPI HTTPRoute.
Deploy your first HTTPRoute
A GatewayAPI HTTPRoute enables you to expose an application through Gateways using HTTP(S).
To do this, reference the Services to reach (using the backendRefs option) and the Gateways (using the parentRef option) as shown in the snippet below:
# Application to expose
kind: Deployment
apiVersion: apps/v1
metadata:
name: whoami
namespace: whoami
spec:
replicas: 3
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
# Service to reach the application on the cluster
apiVersion: v1
kind: Service
metadata:
name: whoami
namespace: whoami
labels:
app: whoami
spec:
type: ClusterIP
ports:
- port: 80
name: whoami
selector:
app: whoami
---
# HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: whoami-httproute
namespace: whoami
spec:
parentRefs:
- name: traefik-gateway
namespace: traefik
hostnames:
- whoami.myexample.io
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: whoami
namespace: whoami
port: 80
This example demonstrates how to expose a web server that displays some headers when Traefik is accessed using the hostname whoami.myexample.io.
You can use the following curl command to verify that the application is correctly exposed:
$ curl http://whoami.myexample.io/
Hostname: whoami-697f8c6cbc-7nqmf
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.9
IP: fe80::e8c0:86ff:feba:5e06
RemoteAddr: 10.42.0.14:59316
GET / HTTP/1.1
Host: whoami.myexample.io
User-Agent: curl/7.88.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.myexample.io
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: traefik-5d476f955f-cn7xs
X-Real-Ip: 10.42.0.1
Congratulations, you've successfully deployed your first HTTPRoute with Traefik!
Now, let's take it a step further by adding a few operations to the requests.
Go beyond with Filters
GatewayAPI Filters enable Traefik to perform various operations on requests and responses.
There are three types of filters:
- Core Filters: Mandatory filters for every GatewayController, such as
requestHeaderModifierandrequestRedirect. - Extended Filters: Optional filters for
GatewayControllers, such asresponseHeaderModifierandrequestMirror. - ExtensionRef Filters: Additional filters provided by the GatewayController. In Traefik, these are the HTTP middlewares.
Let's modify the HTTPRoute to:
Add the header x-post-topic using the core filter.
Add the prefix gatewayapi to the request using the middleware AddPrefix.
# HTTPRoute with the Filters
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: whoami-httproute
namespace: whoami
spec:
parentRefs:
- name: traefik-gateway
namespace: traefik
hostnames:
- whoami.myexample.io
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: whoami
namespace: whoami
port: 80
filters:
# Core filter which adds a header
- type: RequestHeaderModifier
requestHeaderModifier:
add:
- name: x-post-topic
value: GatewayAPI
# ExtensionRef filter to use the Traefik Middleware AddPrefix
- type: ExtensionRef
extensionRef:
group: traefik.io
kind: Middleware
name: addprefix
---
# Traefik Middleware AddPrefix
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: addprefix
namespace: whoami
spec:
addPrefix:
prefix: /gatewayapi
You can check the modification using a curl command:
$ curl http://whoami.myexample.io/
Hostname: whoami-697f8c6cbc-2xkpr
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.10
IP: fe80::b8b5:6fff:fe48:19e9
RemoteAddr: 10.42.0.14:40044
GET /gatewayapi/ HTTP/1.1
Host: whoami.myexample.io
User-Agent: curl/7.88.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.myexample.io
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: traefik-5d476f955f-cn7xs
X-Post-Topic: GatewayAPI
X-Real-Ip: 10.42.0.1
As we have seen, the GatewayAPI integration in Traefik simplifies the initial setup significantly. We successfully exposed our first HTTPRoute and added a couple of operations to the requests. Traefik has many more GatewayAPI capabilities, such as TCPRoute, TLSRoute, and ReferenceGrant that are not covered in this blog post, but we highly encourage you to explore them further.
Conclusion
GatewayAPI is undoubtedly the new standard for exposing your resources in a Kubernetes cluster. Its specifications already surpass those of Ingress, and with a strong community backing it, GatewayAPI will continue to grow.
As a Kubernetes first-class citizen, Traefik is of course strongly supporting this effort and will continue to contribute to this community project.
We've improved status management, updated route priority rules, and introduced the ReferenceGrant feature to make Traefik even more robust and flexible for your Kubernetes setup.
But it’s just the beginning! We plan to further advance this integration by adding support for features like GRPCRoute, UDPRoute, and BackendTLSPolicy.
Our goal is to provide comprehensive support, enabling you to fully leverage GatewayAPI in your Kubernetes journey. Stay tuned for more updates!
Useful Links
This is a companion discussion topic for the original entry at https://traefik.io/blog/getting-started-with-kubernetes-gateway-api-and-traefik