Understanding the Gateway API

The Kubernetes Gateway API is a specification for configuring HTTP and TCP routing in Kubernetes clusters. It provides a role-oriented, extensible model that separates infrastructure management from application routing configuration.

This page explains the Gateway API resource model and how Nantian Gateway implements it.

graph TD
    GC[GatewayClass] -->|defines| G[Gateway]
    G -->|listens on| L[Listener :80]
    L -->|routes to| HR[HTTPRoute]
    HR -->|backendRef| SVC[Service]
    RG[ReferenceGrant] -.->|allows cross-ns| HR
    BTL[BackendTLSPolicy] -->|secures| SVC
    BLP[BackendLBPolicy] -->|configures| SVC

Why Gateway API?

Before the Gateway API, Kubernetes provided the Ingress resource for exposing HTTP services. Ingress served its purpose but had significant limitations:

• Limited expressiveness — Ingress could only route based on host and path, with no support for header-based routing, traffic splitting, or request rewriting
• No role separation — infrastructure operators and application developers shared the same resource, leading to configuration conflicts
• Implementation-specific annotations — every ingress controller required different annotations for the same behavior, creating vendor lock-in

The Gateway API addresses these limitations with a multi-resource model that separates concerns and provides richer routing capabilities as a community standard.

The Resource Model

The Gateway API defines three primary resource types, each with a distinct role:

GatewayClass

A GatewayClass defines a class of gateway implementation — for example, nantian-gateway or envoy-gateway. It is typically configured by the infrastructure operator and referenced by Gateway resources to determine which controller manages them.

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

Gateway

A Gateway resource represents a point of network access — a listener that accepts connections on a specific address and port. Gateways are managed by infrastructure operators and define the shape of traffic entry, not the routing rules.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: external-gateway
spec:
  gatewayClassName: nantian-gw
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: tls-cert

Route

Route resources define how traffic is matched and forwarded to backend services. Different route types handle different protocols:

Route Type	Protocol	Use Case
HTTPRoute	HTTP/HTTPS	Web applications, REST APIs, gRPC-web
GRPCRoute	gRPC	gRPC services with method-level routing
TCPRoute	TCP	Non-HTTP protocols, database connections
TLSRoute	TLS passthrough	Services that handle their own TLS
UDPRoute	UDP	DNS, streaming, gaming

Example HTTPRoute that routes traffic based on path prefix:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-routes
spec:
  parentRefs:
    - name: external-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-service
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /web
      backendRefs:
        - name: web-service
          port: 3000

Role-Oriented Design

The Gateway API’s resource model is deliberately split across organizational roles:

• Infrastructure providers define GatewayClass resources (the how)
• Cluster operators create Gateway resources (the where)
• Application developers define Route resources (the what)

This separation means an application team can define routing rules for their service without needing to know how the gateway is deployed or which implementation is in use. The infrastructure team can change the underlying gateway implementation without requiring application teams to update their route configurations.

Nantian Gateway Implementation

Nantian Gateway targets the Gateway API v1.5.1 specification with 54 declared supported features. This includes:

• Core features: HTTPRoute, Gateway, GatewayClass, ReferenceGrant
• Extended features: HTTP header matching, query parameter matching, request mirroring, traffic splitting, URL rewriting, CORS, and more
• Mesh features: Gateway API Mesh resources for service mesh configurations

For a complete list of supported features, see the Gateway API Support matrix.

HTTPRoute Filters and Traffic Shaping

HTTPRoute supports a rich set of filters that modify requests and responses at the proxy layer. Filters are applied in the order they are defined in the route rule.

Request Modification

rules:
- matches:
    - path:
        type: PathPrefix
        value: /api
  filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
          - name: X-Custom-Header
            value: "true"
        remove:
          - "X-Deprecated-Header"
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /v2
  backendRefs:
    - name: api-service
      port: 8080

Traffic Splitting

Route traffic across multiple backends with weighted distribution:

backendRefs:
  - name: api-stable
    port: 8080
    weight: 90
  - name: api-canary
    port: 8080
    weight: 10

Redirect and CORS

filters:
  - type: RequestRedirect
    requestRedirect:
      scheme: https
      statusCode: 301
  - type: ExtensionRef
    extensionRef:
      group: gateway.networking.k8s.io
      kind: CORSFilter
      name: allow-origins

Policy Attachment Model

In addition to route-level filters, Gateway API provides policies — resources that attach configuration to gateways, routes, or backends independently of route definitions:

Policy	Attaches To	Purpose
BackendTLSPolicy	Service	TLS settings for backend connections
BackendLBPolicy	Service	Session persistence configuration
Nantian RoutePolicy	HTTPRoute, GRPCRoute	Timeout, retry, and circuit breaker overrides
Nantian TokenPolicy	HTTPRoute	Per-route token usage limits

This separation allows security and platform teams to apply policies without modifying application-owned route resources.

Next Steps

• Split-Plane Architecture — understand how Nantian Gateway processes Gateway API resources internally
• Getting Started — deploy your first Gateway API resources
• API Reference: Gateway API Resources — detailed resource reference