Skip to main content

Traefik Hub API Gateway & Kubernetes Gateway API

When using the Kubernetes Gateway API provider, Traefik Hub API Gateway leverages the Gateway API Custom Resource Definitions (CRDs) to obtain its routing configuration.

The Kubernetes Gateway API provider supports version v1.2.0 of the specification.

It fully supports all HTTPRoute core and some extended features, like GRPCRoute, as well as the TCPRoute and TLSRoute resources from the Experimental channel.

For more details, check out the conformance report.

tip

For detailed information on the Gateway API concepts and resources, refer to the official documentation.

Deploying a Gateway​

A Gateway is a core resource in the Gateway API specification that defines the entry point for traffic into a Kubernetes cluster. It is linked to a GatewayClass, which specifies the controller responsible for managing and handling the traffic, ensuring that it is directed to the appropriate Kubernetes backend services.

The GatewayClass is a cluster-scoped resource typically defined by the infrastructure provider. The following GatewayClass defines that gateways attached to it must be managed by the Traefik controller.

GatewayClass
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: traefik
spec:
  controllerName: traefik.io/gateway-controller

Next, the following Gateway manifest configures the running Traefik controller to handle the incoming traffic.

Listener ports

Please note that Gateway listener ports must match the configured EntryPoint ports of the Traefik deployment. In case they do not match, an ERROR message is logged, and the resource status is updated accordingly.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: traefik
  namespace: default
spec:
  gatewayClassName: traefik

  # Only Routes from the same namespace are allowed.
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same

    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: secret-tls
            namespace: default

      allowedRoutes:
        namespaces:
          from: Same

    - name: tcp
      protocol: TCP
      port: 3000
      allowedRoutes:
        namespaces:
          from: Same

    - name: tls
      protocol: TLS
      port: 3443
      tls:
        mode: Terminate
        certificateRefs:
          - name: secret-tls
            namespace: default

      allowedRoutes:
        namespaces:
          from: Same

Deploying a Gateway in a multi-tenant environment​

When working with multi-tenant environments, it is often necessary to run multiple Gateways and GatewayClasses in different namespaces of the same cluster. Some solutions limit you to a single installation of their gateway with the Kubernetes Gateway API, preventing multiple deployments from operating side by side.

In contrast, Traefik Hub API Gateway does not have this limitation. It discovers all GatewayClasses that specify the controllerName field as traefik.io/gateway-controller. To focus on a specific set of GatewayClasses for a given tenant or namespace, use the labelselector option in your configuration. By applying labels to your GatewayClasses, you can create different groups of GatewayClasses for each tenant. Traefik will only process those that match the specified label selector, allowing multiple sets of GatewayClasses and Gateways to coexist without conflict.

For example, if you label your GatewayClasses with app=traefik, you can instruct Traefik Hub API Gateway to process only those GatewayClasses:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: traefik
  labels:
    app: traefik
spec:
  controllerName: traefik.io/gateway-controller

This configuration lets you define different label values for each tenant. Each Traefik Hub API Gateway instance or configuration can target a distinct set of GatewayClasses, making it possible to run multiple tenants with their own isolated Gateways in the same cluster.

Exposing a route​

Once a Gateway is deployed (see Deploying a Gateway) HTTPRoute, TCPRoute, and/or TLSRoute resources must be deployed to forward some traffic to Kubernetes backend services.

Attaching to Gateways

As demonstrated in the following examples, a Route resource must be configured with ParentRefs that reference the parent Gateway it should be associated with.

HTTP/HTTPS​

The HTTPRoute is a core resource in the Gateway API specification, designed to define how HTTP traffic should be routed within a Kubernetes cluster. It allows the specification of routing rules that direct HTTP requests to the appropriate Kubernetes backend services.

For more details on the resource and concepts, check out the Kubernetes Gateway API documentation.

For example, the following manifests configure a whoami backend and its corresponding HTTPRoute, reachable through the deployed Gateway at the http://whoami.localhost address.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami-http
  namespace: default
spec:
  parentRefs:
    - name: traefik
      sectionName: http
      kind: Gateway

  hostnames:
    - whoami.localhost

  rules:
     - matches:
        - path:
            type: PathPrefix
            value: /

       backendRefs:
        - name: whoami
          namespace: default
          port: 80

To secure the connection with HTTPS and redirect non-secure request to the secure endpoint, we will update the above HTTPRoute manifest to add a RequestRedirect filter, and add a new HTTPRoute which binds to the https Listener and forward the traffic to the whoami backend.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami-http
  namespace: default
spec:
  parentRefs:
    - name: traefik
      sectionName: http
      kind: Gateway

  hostnames:
    - whoami.localhost

  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https

Once everything is deployed, sending a GET request to the HTTP and HTTPS endpoints should return the following responses:

$ curl -I http://whoami.localhost

HTTP/1.1 302 Found
Location: https://whoami.localhost/
Date: Thu, 11 Jul 2024 15:11:31 GMT
Content-Length: 5

GRPC​

The GRPCRoute is an extended resource in the Gateway API specification, designed to define how GRPC traffic should be routed within a Kubernetes cluster. It allows the specification of routing rules that direct GRPC requests to the appropriate Kubernetes backend services.

For more details on the resource and concepts, check out the Kubernetes Gateway API documentation.

For example, the following manifests configure an echo backend and its corresponding GRPCRoute, reachable through the deployed Gateway at the echo.localhost:80 address.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: echo
  namespace: default
spec:
  parentRefs:
    - name: traefik
      sectionName: http
      kind: Gateway

  hostnames:
    - echo.localhost

  rules:
    - matches:
        - method:
            type: Exact
            service: grpc.reflection.v1alpha.ServerReflection

        - method:
            type: Exact
            service: gateway_api_conformance.echo_basic.grpcecho.GrpcEcho
            method: Echo

      backendRefs:
        - name: echo
          namespace: default
          port: 3000

Once everything is deployed, sending a GRPC request to the HTTP endpoint should return the following responses:

$ grpcurl -plaintext echo.localhost:80 gateway_api_conformance.echo_basic.grpcecho.GrpcEcho/Echo

{
  "assertions": {
    "fullyQualifiedMethod": "/gateway_api_conformance.echo_basic.grpcecho.GrpcEcho/Echo",
    "headers": [
      {
        "key": "x-real-ip",
        "value": "10.42.2.0"
      },
      {
        "key": "x-forwarded-server",
        "value": "traefik-74b4cf85d8-nkqqf"
      },
      {
        "key": "x-forwarded-port",
        "value": "80"
      },
      {
        "key": "x-forwarded-for",
        "value": "10.42.2.0"
      },
      {
        "key": "grpc-accept-encoding",
        "value": "gzip"
      },
      {
        "key": "user-agent",
        "value": "grpcurl/1.9.1 grpc-go/1.61.0"
      },
      {
        "key": "content-type",
        "value": "application/grpc"
      },
      {
        "key": "x-forwarded-host",
        "value": "echo.localhost:80"
      },
      {
        "key": ":authority",
        "value": "echo.localhost:80"
      },
      {
        "key": "accept-encoding",
        "value": "gzip"
      },
      {
        "key": "x-forwarded-proto",
        "value": "http"
      }
    ],
    "authority": "echo.localhost:80",
    "context": {
      "namespace": "default",
      "pod": "echo-78f76675cf-9k7rf"
    }
  }
}

TCP​

Experimental Channel

The TCPRoute resource described below is currently available only in the Experimental channel of the Gateway API specification. To use this resource, the experimentalChannel option must be enabled in the Traefik deployment.

The TCPRoute is a resource in the Gateway API specification designed to define how TCP traffic should be routed within a Kubernetes cluster.

For more details on the resource and concepts, check out the Kubernetes Gateway API documentation.

For example, the following manifests configure a whoami backend and its corresponding TCPRoute, reachable through the deployed Gateway at the localhost:3000 address.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: whoami-tcp
  namespace: default
spec:
  parentRefs:
    - name: traefik
      sectionName: tcp
      kind: Gateway

  rules:
     - backendRefs:
        - name: whoamitcp
          namespace: default
          port: 3000

Once everything is deployed, sending the WHO command should return the following response:

$ nc localhost 3000

WHO
Hostname: whoamitcp-85d644bfc-ktzv4
IP: 127.0.0.1
IP: ::1
IP: 10.42.1.4
IP: fe80::b89e:85ff:fec2:7d21

TLS​

Experimental Channel

The TLSRoute resource described below is currently available only in the Experimental channel of the Gateway API. Therefore, to use this resource, the experimentalChannel option must be enabled.

The TLSRoute is a resource in the Gateway API specification designed to define how TLS (Transport Layer Security) traffic should be routed within a Kubernetes cluster. It specifies routing rules for TLS connections, directing them to appropriate backend services based on the SNI (Server Name Indication) of the incoming connection.

For more details on the resource and concepts, check out the Kubernetes Gateway API documentation.

For example, the following manifests configure a whoami backend and its corresponding TLSRoute, reachable through the deployed Gateway at the localhost:3443 address via a secure connection with the whoami.localhost SNI.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: whoami-tls
  namespace: default
spec:
  parentRefs:
    - name: traefik
      sectionName: tls
      kind: Gateway

  hostnames:
    - whoami.localhost

  rules:
    - backendRefs:
        - name: whoamitcp
          namespace: default
          port: 3000

Once everything is deployed, sending the WHO command should return the following response:

$ openssl s_client -quiet -connect localhost:3443 -servername whoami.localhost
Connecting to ::1
depth=0 C=FR, L=Lyon, O=Traefik Labs, CN=Whoami
verify error:num=18:self-signed certificate
verify return:1
depth=0 C=FR, L=Lyon, O=Traefik Labs, CN=Whoami
verify return:1

WHO
Hostname: whoamitcp-85d644bfc-hnmdz
IP: 127.0.0.1
IP: ::1
IP: 10.42.2.4
IP: fe80::d873:20ff:fef5:be86

Using Traefik middleware as HTTPRoute filter​

An HTTP filter is an HTTPRoute component which enables the modification of HTTP requests and responses as they traverse the routing infrastructure.

There are three types of filters:

  • Core: Mandatory filters for every Gateway controller, such as RequestHeaderModifier and RequestRedirect.
  • Extended: Optional filters for Gateway controllers, such as ResponseHeaderModifier and RequestMirror.
  • ExtensionRef: Additional filters provided by the Gateway controller. In Traefik Hub API Gateway, these are the HTTP middlewares supported through the Middleware CRD.
ExtensionRef Filters

To use Traefik middlewares as ExtensionRef filters, the Kubernetes IngressRoute provider must be enabled in the static configuration, as detailed in the documentation.

For example, the following manifests configure an HTTPRoute using the Traefik AddPrefix middleware, reachable through the deployed Gateway at the http://whoami.localhost address:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami-http
  namespace: default
spec:
  parentRefs:
    - name: traefik
      sectionName: http
      kind: Gateway

  hostnames:
    - whoami.localhost

  rules:
    - backendRefs:
        - name: whoami
          namespace: default
          port: 80

      filters:
        - type: ExtensionRef
          extensionRef:
            group: traefik.io
            kind: Middleware
            name: add-prefix

Once everything is deployed, sending a GET request should return the following response:

$ curl http://whoami.localhost

Hostname: whoami-697f8c6cbc-kw954
IP: 127.0.0.1
IP: ::1
IP: 10.42.2.6
IP: fe80::a460:ecff:feb6:3a56
RemoteAddr: 10.42.2.4:54758
GET /prefix/ HTTP/1.1
Host: whoami.localhost
User-Agent: curl/7.87.1-DEV
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.2.1
X-Forwarded-Host: whoami.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: traefik-6b66d45748-ns8mt
X-Real-Ip: 10.42.2.1

Native load balancing​

By default, Traefik Hub API Gateway sends the traffic directly to the pod IPs and reuses the established connections to the backends for performance purposes.

It is possible to override this behavior and configure Traefik Hub API Gateway to send the traffic to the service IP. The Kubernetes service itself does the load balancing to the pods. It can be done with the annotation traefik.io/service.nativelb on the backend Service.

By default, NativeLB is false.

"Default value"

Note that it is possible to override the default value by using the option nativeLBByDefault at the provider level.

Enable native load balancing
apiVersion: v1
kind: Service
metadata:
  name: myservice
  namespace: default
  annotations:
    traefik.io/service.nativelb: "true"
spec:
[...]