Kubernetes Gateway API: A Comprehensive Guide

This document provides an in-depth exploration of the Kubernetes Gateway API, designed to serve as a comprehensive guide for advanced learners. It covers the motivations behind its creation, its core concepts, comparisons with existing ingress solutions, deployment considerations, and practical examples.

Introduction: The Evolution of Ingress in Kubernetes

Managing external access to applications running within a Kubernetes cluster is crucial. This "north-south" traffic, often referred to as ingress, has evolved significantly within the Kubernetes ecosystem. Initially, the Service API provided basic load balancing capabilities, but it lacked fine-grained control over routing. The Ingress API emerged as a solution specifically for HTTP routing, but its limitations in expressiveness and extensibility led to the development of the Gateway API.

From Service to Ingress to Gateway: A Comparative Overview

Feature	Service API	Ingress API	Gateway API
Focus	Exposing workloads within the cluster	HTTP routing to backend services	Service networking, encompassing HTTP, gRPC, TCP, and UDP traffic
Load Balancing	Basic, single external IP per service	Within the cluster, single external IP for multiple services	More flexible and granular control over load balancing strategies
Protocol Support	TCP, UDP	Primarily HTTP	HTTP, gRPC, TCP, UDP, and future protocols
Routing	Limited (port-based)	Host-based and path-based	Richer routing based on headers, query parameters, methods, and more
Extensibility	Limited	Annotations (controller-specific, non-portable)	Filters, policies, and custom resources, offering standardized extensibility
Role Separation	Not explicitly defined	Implicitly managed by cluster administrators	Explicit role separation (Infrastructure Provider, Cluster Operator, Application Developer)
TLS Management	Basic	Annotations and Secrets	More flexible and robust TLS configuration, including SNI and multiple certificates per listener
Configuration	Simple, but limited routing capabilities	Terse, relies heavily on annotations	Declarative, structured resources with well-defined fields, promoting portability and maintainability

Core Concepts of the Gateway API

The Gateway API introduces several key resources that work together to manage ingress traffic:

GatewayClass: Defines a type of gateway implementation (e.g., "nginx", "contour", "istio"). It is managed by the Infrastructure Provider and represents the underlying controller responsible for handling traffic.
Gateway: An instance of a GatewayClass, deployed and managed by the Cluster Operator. It defines the entry point for external traffic, specifying listeners (ports and protocols).
HTTPRoute: Defines HTTP routing rules, managed by Application Developers. It specifies how traffic should be routed to backend services based on various matching criteria (hostnames, paths, headers, etc.).
TCPRoute: Defines TCP routing rules for Layer 4 traffic.
UDPRoute: Defines UDP routing rules for Layer 4 traffic.
TLSRoute: Defines routing rules for TLS-encrypted traffic at Layer 4, offering more control than TCPRoute.
ReferencePolicy: A mechanism to control which namespaces can reference resources in other namespaces.

Role-Oriented Design

The Gateway API's role-oriented design is a significant improvement over the Ingress API. It promotes collaboration and security by clearly separating responsibilities:

Infrastructure Provider: Creates and manages GatewayClasses.
Cluster Operator: Deploys and manages Gateways, configuring listeners and overall network policies.
Application Developer: Defines Routes to expose their applications through existing Gateways.

Example: Basic HTTP Routing

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: my-http-route
spec:
  parentRefs:
    - name: my-gateway # Reference to the Gateway
  hostnames:
    - "example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /app
      action:
        forwardTo:
          - serviceName: my-app-service
            port: 8080

This HTTPRoute directs traffic to example.com/app to the my-app-service on port 8080.

Example: Header-Based Routing

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: header-routing
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
  - "example.com"
  rules:
  - matches:
    - headers:
      - name: X-User-Type
        value: premium
    action:
      forwardTo:
      - serviceName: premium-service
        port: 80
  - matches:
    - headers:
      - name: X-User-Type
        value: free
    action:
      forwardTo:
      - serviceName: free-service
        port: 80

This example routes traffic based on the X-User-Type header.

Example: Traffic Splitting

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: traffic-splitting
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /app
      filters:
        - type: RequestMirror
          requestMirror:
            backendRef:
              name: canary-service
              port: 8080
      action:
        forwardTo:
          - serviceName: stable-service
            port: 8080
            weight: 80
          - serviceName: canary-service
            port: 8080
            weight: 20

This configuration splits traffic to /app with 80% directed to the stable version of the application and 20% to a canary version.

Extensibility with Filters

The Gateway API's extensibility is achieved through filters. Filters can modify requests and responses, enabling functionalities like URL rewriting, header manipulation, and traffic splitting.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: rewrite-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - "example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /old-path
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              replaceFullPath: /new-path
      action:
        forwardTo:
          - serviceName: my-service
            port: 80

This example rewrites /old-path to /new-path before forwarding the request.

TLS Configuration

TLS configuration is handled within the Listener resource of a Gateway:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: my-gateway
spec:
  listeners:
  - name: https-listener
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
        - name: my-tls-secret
          kind: Secret

This configures TLS termination at the Gateway using the my-tls-secret.

Example: Multi-Tenant Gateways

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: multi-tenant-gateway
spec:
  listeners:
  - name: tenant-a
    hostname: tenant-a.example.com
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - name: tenant-a-cert
  - name: tenant-b
    hostname: tenant-b.example.com
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - name: tenant-b-cert

This example demonstrates how multiple tenants can share a single Gateway, with separate hostnames and certificates.

Deployment and Installation

Install CRDs: The Gateway API requires installing CRDs. This can be done independently or as part of a Gateway controller installation.
Install a Gateway Controller: Choose a suitable controller (e.g., Envoy Gateway, Contour, NGINX Gateway Fabric). Follow the controller's documentation

Key Concepts

The Kubernetes Gateway API offers a modern approach to managing ingress traffic in your cluster. It surpasses the Ingress API in flexibility and power, allowing you to define intricate routing rules and leverage different gateway controllers.

Core Components

GatewayClass: Defines the behavior of a set of gateways. It establishes a one-to-one relationship with a gateway controller, which provisions infrastructure to handle ingress traffic. Multiple GatewayClass resources can coexist, catering to different environments or needs (e.g., production vs. development).
Gateway: Represents how external traffic is translated to backend services. It references a GatewayClass and defines listeners (logical endpoints) for accepting traffic. Gateways enable advanced configurations, such as specifying allowed protocols and enabling mutual TLS authentication.
Listener: Binds to an address and port, specifying the protocol (e.g., HTTP, HTTPS, TCP) to accept incoming requests. Listeners can include multiple TLS certificates for scenarios like multi-domain hosting.
HTTPRoute: Defines how HTTP traffic matching a specific profile should be routed to a backend service. It references a Gateway and its listener(s) and specifies routing rules based on hostnames, paths, and headers. Advanced features include traffic splitting and fault injection for testing resilience.
TCPRoute: Facilitates routing for non-HTTP protocols at Layer 4, enabling support for custom TCP-based applications.
UDPRoute: Routes Layer 4 UDP traffic for use cases like DNS or video streaming.
TLSRoute: Provides explicit control over TLS traffic at Layer 4, complementing the flexibility of TCPRoute.

Routing HTTP Traffic

Define a GatewayClass: Associate it with a specific gateway controller (e.g., Envoy Gateway) running in your cluster. Ensure the controller is installed and configured properly.
Create a Gateway: Specify listeners for incoming traffic. Use advanced listener configurations, such as specifying SNI (Server Name Indication) for multi-domain TLS support.
Define HTTPRoutes: Map incoming HTTP requests to backend services based on hostnames, paths, headers, or query parameters. Advanced use cases include routing traffic based on geolocation or user agents.

Example: Routing Based on Query Parameters

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: query-routing
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - queryParams:
            - name: version
              value: beta
      action:
        forwardTo:
          - serviceName: beta-service
            port: 8080
    - matches:
        - queryParams:
            - name: version
              value: stable
      action:
        forwardTo:
          - serviceName: stable-service
            port: 8080

This example routes requests based on the version query parameter.

Associating a GatewayClass with a Gateway Controller

Each GatewayClass references a specific gateway controller by name.
The gateway controller manages the lifecycle of gateways belonging to its associated GatewayClass. For example, the nginx gateway controller provisions and manages gateways for an NginxGatewayClass.
You can have multiple GatewayClasses and controllers to cater to different routing needs or leverage cloud-provider-specific controllers like AWS or GCP.

Configuring a Gateway for Ingress

Gateways define listeners to accept traffic based on port and protocol. Advanced configurations allow:
- Associating multiple hostnames to a single listener for virtual hosting.
- Implementing rate limiting at the gateway level.
Gateways reference the GatewayClass that determines the responsible gateway controller, enabling features like automatic scaling and load balancing.

Defining Routes to Application Services

HTTPRoutes specify routing rules for HTTP traffic, supporting advanced features like retries, timeouts, and custom headers.
They reference the gateway and its listener(s) that should handle the traffic.
Routes can specify one or more hostnames to match incoming requests.
Paths within the URL can be used for more granular routing within the route.
Each route references the backend service (usually a ClusterIP service) that should receive the traffic. For redundancy, routes can distribute traffic among multiple backends using weighted rules.

Example: Fault Injection

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: fault-injection
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /test
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              X-Debug-Mode: "true"
        - type: FaultInjection
          faultInjection:
            delay:
              fixedDelay: 5s
            abort:
              httpStatus: 503
      action:
        forwardTo:
          - serviceName: test-service
            port: 80

This example adds a 5-second delay and injects an HTTP 503 error for debugging.

Demo: Consuming a Kubernetes Application Using the Gateway API

This demo showcases a basic scenario where the Envoy Gateway controller is used:

A simple application is deployed in the cluster.
A GatewayClass for the Envoy Gateway is defined.
A Gateway with an HTTP listener on port 80 is created.
An HTTPRoute references the gateway and its listener, and routes traffic to the application's service.
Accessing the external IP address associated with the gateway leads to the application.

Example: Gateway with Multi-Protocol Support

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: multi-protocol-gateway
spec:
  listeners:
  - name: http-listener
    port: 80
    protocol: HTTP
  - name: tcp-listener
    port: 3306
    protocol: TCP
  - name: tls-listener
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - name: my-tls-cert

This example demonstrates how a single gateway can handle HTTP, TCP, and HTTPS traffic.

Migrating from the Ingress API to the Gateway API

Existing Ingress definitions need to be converted to Gateway API resources.
The Ingress2gateway tool can help automate this process for basic scenarios.
Key differences between the APIs include:
- Gateway API requires explicit listener definitions in gateways.
- Processing is dictated by gateways referenced in HTTPRoutes (not IngressClasses).
- Gateway API doesn't have a default backend service (explicit routing is required).

Additional Migration Considerations

TLS: Ensure TLS configurations in Ingress are explicitly defined as Listeners in Gateway.
Annotations: Replace controller-specific annotations with standardized fields in Gateway API resources.
Backend Configuration: Explicitly define backend services and weights for advanced load balancing.

Benefits of Gateway API

Flexibility: Supports complex routing rules, multi-protocol traffic, and multiple gateway controllers.
Decoupling: Separates route definitions from gateway controller implementation, enabling portability.
Extensibility: Allows for future API enhancements, custom filters, and innovation in traffic management.
Security: Explicit role-based separation of responsibilities and enhanced TLS support.
Observability: Integration with monitoring tools like Prometheus and Grafana for better traffic visibility.

Additional Considerations

Security: Gateways may require additional configuration for TLS termination, mutual authentication, and DDoS protection.
Monitoring: Monitor gateway and controller logs for troubleshooting. Use metrics to analyze traffic patterns and detect anomalies.
Scalability: Leverage Gateway controllers that support auto-scaling and high availability to handle varying traffic loads.
Compliance: Ensure adherence to organizational and regulatory requirements for traffic management and encryption.

Conclusion

The Kubernetes Gateway API represents a significant advancement in service networking within Kubernetes. Its role-oriented design, rich routing capabilities, extensibility, and improved TLS management make it a powerful tool for modern cloud-native applications. This guide provides a solid foundation for understanding and utilizing the Gateway API effectively. For further exploration, consult the official Kubernetes documentation and the documentation of your chosen Gateway controller.

Want to discuss cloud architecture? Find me on LinkedIn.

Kubernetes Gateway API: The Future of Ingress