Solutions
Audit & Optimization Platform Design Automation Team Structure
Documentation Blog
Get Started

Gateway API

Gateway API is a modern, role-oriented API for service networking in Kubernetes. It’s designed as the evolution of Ingress, providing more expressive and extensible routing capabilities. Unlike Ingress which focuses on HTTP routing, Gateway API supports multiple protocols (HTTP, TCP, UDP, TLS) and provides role-based separation between infrastructure providers and application developers.

What is Gateway API?

Gateway API is a collection of Kubernetes resources that model service networking:

  • Gateway - Defines how traffic enters the cluster
  • GatewayClass - Defines types of Gateways
  • HTTPRoute - Routes HTTP traffic
  • TCPRoute, UDPRoute, TLSRoute - Route other protocols

Gateway API separates concerns:

  • Infrastructure providers manage Gateways
  • Application developers create Routes
graph TB A[Infrastructure Admin] --> B[Creates Gateway] C[Application Developer] --> D[Creates HTTPRoute] D --> B B --> E[Traffic Routes to Services] style A fill:#e1f5ff style C fill:#fff4e1 style B fill:#e8f5e9 style E fill:#fff4e1

Gateway API vs Ingress

Gateway API addresses limitations of Ingress:

graph TB subgraph ingress[Ingress] A[Single Resource] B[HTTP/HTTPS Only] C[Limited Expressiveness] D[No Role Separation] end subgraph gatewayapi[Gateway API] E[Multiple Resources] F[HTTP, TCP, UDP, TLS] G[Highly Expressive] H[Role-Based Separation] end style ingress fill:#fff4e1 style gatewayapi fill:#e8f5e9

Ingress limitations:

  • Single resource for all configuration
  • HTTP/HTTPS only
  • Limited routing capabilities
  • No role separation

Gateway API benefits:

  • Multiple resources (Gateway, Routes)
  • Multiple protocols
  • Rich routing features
  • Role-based access control

Core Resources

GatewayClass

Defines types of Gateways (similar to StorageClass):

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

Gateway

Defines how traffic enters the cluster:

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

HTTPRoute

Routes HTTP traffic to Services:

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

Role-Based Model

Gateway API separates infrastructure and application concerns:

Infrastructure Provider Role

Manages Gateways and GatewayClasses:

# Created by cluster admin
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shared-gateway
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    protocol: HTTP
    port: 80

Application Developer Role

Creates Routes that reference Gateways:

# Created by app developer
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-route
spec:
  parentRefs:
  - name: shared-gateway  # References infrastructure Gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /my-app
    backendRefs:
    - name: my-app-service
      port: 80
graph TB A[Infrastructure Admin] --> B[Gateway] C[App Developer 1] --> D[HTTPRoute 1] C --> E[HTTPRoute 2] F[App Developer 2] --> G[HTTPRoute 3] D --> B E --> B G --> B B --> H[Traffic Routes to Services] style A fill:#e1f5ff style B fill:#e8f5e9 style D fill:#fff4e1 style E fill:#fff4e1 style G fill:#fff4e1

HTTPRoute Features

HTTPRoute provides rich routing capabilities:

Path Matching

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

Header Matching

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - headers:
      - name: version
        value: v2
    backendRefs:
    - name: api-v2-service
      port: 80

Traffic Splitting

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: split-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-v1-service
      port: 80
      weight: 90
    - name: api-v2-service
      port: 80
      weight: 10

Request/Response Modification

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: modified-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-Forwarded-For
          value: "true"
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /v1
    backendRefs:
    - name: api-service
      port: 80

When to Use Gateway API

Use Gateway API when:

✅ Modern routing needs - Need advanced HTTP routing features
✅ Multiple protocols - Need TCP, UDP, or TLS routing
✅ Role separation - Want to separate infrastructure and application concerns
✅ Future-proofing - Gateway API is the direction Kubernetes is heading
✅ Rich features - Need traffic splitting, header matching, etc.
✅ Multi-tenant - Multiple teams sharing infrastructure

Consider Ingress when:

  • Simple HTTP routing is sufficient
  • You need immediate compatibility (Ingress is more widely supported)
  • Your use case doesn’t need Gateway API features

Gateway API Status

Gateway API is evolving:

  • v1.0 - Core HTTP routing (stable)
  • v1.1 - Additional features (stable)
  • v1.2+ - Ongoing development

Adoption:

  • Supported by major Ingress Controllers (NGINX, Traefik, Istio)
  • Cloud providers adding support
  • Active development and community

Best Practices

  1. Evaluate your needs - Determine if Gateway API features are necessary
  2. Check controller support - Verify your controller supports Gateway API
  3. Use role separation - Leverage role-based model for multi-tenant clusters
  4. Start simple - Begin with basic routing, add complexity gradually
  5. Monitor adoption - Gateway API is evolving, stay updated
  6. Test thoroughly - Gateway API is newer, test your use cases
  7. Document routes - Keep HTTPRoute configurations documented
  8. Use namespaces - Organize routes by namespace
  9. Plan migration - If migrating from Ingress, plan carefully
  10. Leverage features - Use advanced features like traffic splitting when beneficial

Troubleshooting

Gateway Not Ready

  1. Check Gateway status: kubectl get gateway <name>
  2. Verify GatewayClass: kubectl get gatewayclass
  3. Check controller: Ensure Gateway API controller is running
  4. Review events: kubectl describe gateway <name>
  5. Check listeners: Verify listeners are configured correctly

HTTPRoute Not Working

  1. Check route status: kubectl get httproute <name>
  2. Verify parent reference: Ensure Gateway name is correct
  3. Check backend Services: Verify referenced Services exist
  4. Review route rules: Ensure rules are correctly configured
  5. Check controller logs: Review Gateway API controller logs

Traffic Not Routing

  1. Verify Gateway is ready: Check Gateway status
  2. Check HTTPRoute status: Look for acceptance/conditions
  3. Test backend Services: Verify Services work directly
  4. Review routing rules: Ensure matches are correct
  5. Check controller support: Verify controller supports used features

See Also