Getting started with Kubernetes Gateway API and Traefik

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 commands to execute:

$ 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 requestHeaderModifier and requestRedirect.
Extended Filters: Optional filters for GatewayControllers, such as responseHeaderModifier and requestMirror.
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!