Kubernetes Gateway API Provider

The Future of Kubernetes Ingress - Gateway API Standard The Kubernetes Gateway API provider implements the Gateway API specification from Kubernetes SIGs. This next-generation API provides role-oriented design, portability, and expressive routing capabilities.

What is Gateway API?

Gateway API is a Kubernetes SIG project providing: ✅ Role-oriented design - Separate concerns between platform and application teams
✅ Portable configuration - Works across different ingress controllers
✅ Expressive routing - Advanced matching and traffic management
✅ Future Kubernetes standard - Eventually replaces Ingress

Conformance

Traefik supports Gateway API v1.4.0:

✅ Full HTTP core and extended features
✅ TCPRoute (Experimental channel)
✅ TLSRoute (Experimental channel)
📋 See conformance report

Quick Start

Install Gateway API CRDs

# Standard channel (HTTP routing)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

# OR Experimental channel (includes TCP/TLS)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/experimental-install.yaml

Install Traefik RBAC

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-gateway-rbac.yml

Enable Provider

providers:
  kubernetesGateway:
    enabled: true

Create Gateway and Route

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

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: traefik
  listeners:
    - name: http
      protocol: HTTP
      port: 80
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: my-cert

---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
  namespace: default
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - "example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: my-service
          port: 80

Gateway API Resources

GatewayClass

Defines the controller (Traefik):

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: traefik
spec:
  controllerName: traefik.io/gateway-controller
  description: "Traefik Gateway Controller"

Gateway

Defines infrastructure (listeners, ports):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: default
spec:
  gatewayClassName: traefik
  listeners:
    # HTTP listener
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    
    # HTTPS listener
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-cert
            namespace: default

HTTPRoute

Define HTTP routing rules:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: default
  
  hostnames:
    - "api.example.com"
  
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api-v1
          port: 8080

TCPRoute (Experimental)

Route TCP traffic:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: database-route
spec:
  parentRefs:
    - name: tcp-gateway
      sectionName: mysql
  
  rules:
    - backendRefs:
        - name: mysql-primary
          port: 3306

TCPRoute requires experimentalChannel: true and experimental CRDs.

TLSRoute (Experimental)

Route based on SNI:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: tls-route
spec:
  parentRefs:
    - name: production-gateway
  
  hostnames:
    - "secure.example.com"
  
  rules:
    - backendRefs:
        - name: secure-backend
          port: 443

Provider Configuration

endpoint

Optional, Default: Auto-detected

providers:
  kubernetesGateway:
    endpoint: "https://kubernetes.default.svc"

namespaces

Optional, Default: All namespaces

providers:
  kubernetesGateway:
    namespaces:
      - default
      - production

labelselector

Optional, Default: "" Filter GatewayClass resources:

providers:
  kubernetesGateway:
    labelSelector: "environment=production"

experimentalChannel

Optional, Default: false Enable TCPRoute and TLSRoute:

providers:
  kubernetesGateway:
    experimentalChannel: true

Requires experimental CRDs to be installed.

statusAddress

Configure Gateway status addresses:

IP Address
Hostname
From Service

providers:
  kubernetesGateway:
    statusAddress:
      ip: "203.0.113.10"

providers:
  kubernetesGateway:
    statusAddress:
      hostname: "lb.example.com"

providers:
  kubernetesGateway:
    statusAddress:
      service:
        namespace: traefik
        name: traefik

nativeLBByDefault

Optional, Default: false

providers:
  kubernetesGateway:
    nativeLBByDefault: true

throttleDuration

Optional, Default: 0

providers:
  kubernetesGateway:
    throttleDuration: "2s"

Complete Example

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

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: traefik
spec:
  gatewayClassName: traefik
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      allowedRoutes:
        namespaces:
          from: All
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-tls

Advanced Patterns

Request/Response Modification

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-modification
spec:
  parentRefs:
    - name: main-gateway
  
  rules:
    - filters:
        # Add request headers
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Custom-Header
                value: "custom-value"
            remove:
              - "X-Bad-Header"
        
        # Modify response headers
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            set:
              - name: X-Frame-Options
                value: "DENY"
      
      backendRefs:
        - name: my-service
          port: 80

Cross-Namespace Routing

# Gateway in 'traefik' namespace
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shared-gateway
  namespace: traefik
spec:
  gatewayClassName: traefik
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      allowedRoutes:
        namespaces:
          from: All  # Allow routes from any namespace

---
# HTTPRoute in 'app1' namespace
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app1-route
  namespace: app1
spec:
  parentRefs:
    - name: shared-gateway
      namespace: traefik  # Reference gateway in different namespace
  
  rules:
    - backendRefs:
        - name: app1-service
          port: 80

URL Rewriting

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rewrite-route
spec:
  parentRefs:
    - name: main-gateway
  
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /old-api
      
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /new-api
      
      backendRefs:
        - name: api-service
          port: 8080

Role-Based Configuration

Gateway API supports role separation:

Platform Team
Application Team

Platform team manages infrastructure:

GatewayClass
Gateway
Certificate management

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: platform
spec:
  gatewayClassName: traefik
  listeners:
    - name: https
      protocol: HTTPS
      port: 443

Application team manages routes:

HTTPRoute
Service references
Path matching

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: team-a
spec:
  parentRefs:
    - name: production-gateway
      namespace: platform
  rules:
    - backendRefs:
        - name: my-service
          port: 80

Troubleshooting

Gateway Not Ready

# Check Gateway status
kubectl describe gateway my-gateway

# Check GatewayClass
kubectl get gatewayclass traefik -o yaml

Route Not Attached

# Check HTTPRoute status
kubectl describe httproute my-route

# Verify parentRef matches Gateway name/namespace

CRDs Not Found

# List Gateway API CRDs
kubectl get crd | grep gateway

# Reinstall if needed
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

Migration from Ingress/CRD

Enable Gateway Provider

Keep existing providers enabled during migration.

Create Gateway Resources

Deploy GatewayClass and Gateway.

Convert Routes

Gradually migrate Ingress/IngressRoute to HTTPRoute.

Test and Verify

Ensure all routes work correctly.

Clean Up

Remove old resources after successful migration.

Next Steps

Gateway API Docs

Official Gateway API documentation

Routing Reference

Traefik-specific Gateway API routing guide

Getting Started

Core Configuration

Providers

Routing

Middlewares

HTTPS & TLS

Observability

Operations

​Kubernetes Gateway API Provider

​What is Gateway API?

​Conformance

​Quick Start

​Gateway API Resources

​GatewayClass

​Gateway

​HTTPRoute

​TCPRoute (Experimental)

​TLSRoute (Experimental)

​Provider Configuration

​endpoint

​namespaces

​labelselector

​experimentalChannel

​statusAddress

​nativeLBByDefault

​throttleDuration

​Complete Example

​Advanced Patterns

​Request/Response Modification

​Cross-Namespace Routing

​URL Rewriting

​Role-Based Configuration

​Troubleshooting

​Gateway Not Ready

​Route Not Attached

​CRDs Not Found

​Migration from Ingress/CRD

​Next Steps

Gateway API Docs

Routing Reference

Build docs developers (and LLMs) love

Kubernetes Gateway API Provider

What is Gateway API?

Conformance

Quick Start

Gateway API Resources

GatewayClass

Gateway

HTTPRoute

TCPRoute (Experimental)

TLSRoute (Experimental)

Provider Configuration

endpoint

namespaces

labelselector

experimentalChannel

statusAddress

nativeLBByDefault

throttleDuration

Complete Example

Advanced Patterns

Request/Response Modification

Cross-Namespace Routing

URL Rewriting

Role-Based Configuration

Troubleshooting

Gateway Not Ready

Route Not Attached

CRDs Not Found

Migration from Ingress/CRD

Next Steps