8.15 Introduction to Kubernetes Gateway API

Abstract

Gateway API is the next-generation Kubernetes API for traffic routing.

It improves the older Ingress model by providing structured, extensible, and role-oriented APIs for:

HTTP routing
HTTPS/TLS termination
TCP and UDP routing
gRPC routing
traffic splitting
redirects and rewrites
header manipulation
multi-team ownership

In production, Gateway API is useful when Ingress becomes too limited or too annotation-heavy.

Why Gateway API Was Introduced

Ingress works well for simple HTTP routing, but it has limitations in large production environments.

Common Ingress limitations:

weak multi-tenancy support
limited namespace isolation
no native traffic splitting
no native TCP/UDP routing
no native header manipulation
no native rate limiting
no native authentication
controller-specific annotations
inconsistent behavior across controllers

Warning

Ingress annotations are controller-specific.
An annotation that works with NGINX may not work with Traefik, HAProxy, Istio, or another controller.

Ingress Limitation Example

With Ingress, advanced features are usually configured using annotations.

Example NGINX annotation:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"

Example CORS configuration for NGINX:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://allowed-origin.com"
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"

Failure

Kubernetes does not deeply validate controller-specific annotations.
They are passed to the controller as strings.

Why Annotations Become a Problem

Annotations can make production traffic management difficult.

Problems:

hard to validate
hard to standardize
different syntax per controller
difficult for platform teams to govern
hidden behavior outside normal Kubernetes spec fields
poor portability between implementations

Bug

Annotation-heavy Ingress files can become difficult to audit and troubleshoot.

What Gateway API Solves

Gateway API provides native Kubernetes resources for traffic routing.

It gives a structured model for:

Feature	Ingress	Gateway API
HTTP routing	Yes	Yes
Host routing	Yes	Yes
Path routing	Yes	Yes
TCP routing	Limited / controller-specific	Native
UDP routing	Limited / controller-specific	Native
gRPC routing	Limited / controller-specific	Native
Traffic splitting	Annotation-based	Native
Header modification	Annotation-based	Native
TLS termination	Basic	Structured
Multi-tenancy	Limited	Stronger

Success

Gateway API moves many advanced routing features from annotations into proper Kubernetes API fields.

Gateway API Personas

Gateway API separates responsibilities across teams.

Persona	Resource	Responsibility
Infrastructure Provider	`GatewayClass`	Defines available gateway implementation
Cluster Operator	`Gateway`	Creates actual gateway instances
Application Developer	`HTTPRoute`, `TCPRoute`, `GRPCRoute`	Defines application routing

Note

This separation is useful in production because platform teams can control infrastructure while application teams manage routing for their own services.

Gateway API Core Resources

Main Gateway API resources:

Resource	Purpose
`GatewayClass`	Defines the gateway controller implementation
`Gateway`	Defines listeners, ports, protocols, and route attachment
`HTTPRoute`	Defines HTTP routing rules
`TCPRoute`	Defines TCP routing rules
`UDPRoute`	Defines UDP routing rules
`TLSRoute`	Defines TLS routing rules
`GRPCRoute`	Defines gRPC routing rules

Tip

Think of GatewayClass as the blueprint, Gateway as the entry point, and Route objects as application routing rules.

Gateway API Architecture

Client
  ↓
Gateway
  ↓
HTTPRoute / TCPRoute / GRPCRoute
  ↓
Service
  ↓
Pods

Production ownership model:

Infrastructure Provider
  ↓
GatewayClass

Cluster Operator
  ↓
Gateway

Application Developer
  ↓
HTTPRoute / TCPRoute / GRPCRoute

GatewayClass

A GatewayClass tells Kubernetes which controller manages Gateways of that class.

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

Explanation:

Field	Meaning
`metadata.name`	Name used by Gateways
`spec.controllerName`	Controller responsible for this class

Note

Like Ingress, Gateway API still requires a controller implementation.

Gateway

A Gateway defines how traffic enters the cluster.

Example HTTP Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx-gateway
  namespace: default
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All

Explanation:

Field	Meaning
`gatewayClassName`	Which GatewayClass/controller manages this Gateway
`listeners`	Ports and protocols exposed by the Gateway
`protocol`	HTTP, HTTPS, TCP, UDP, TLS
`allowedRoutes`	Which routes can attach to this Gateway

Tip

Use allowedRoutes carefully in multi-tenant clusters to control which namespaces can attach routes.

HTTPRoute

An HTTPRoute defines how HTTP traffic is forwarded to Services.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: basic-route
  namespace: default
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /app
    backendRefs:
    - name: my-app
      port: 80

Explanation:

Field	Meaning
`parentRefs`	Gateway this route attaches to
`matches`	Request matching rules
`path.type`	Match type such as `PathPrefix`
`backendRefs`	Service destination

Example

Requests matching /app are routed to the my-app Service on port 80.

Basic Gateway API Flow

Apply resources in this order:

kubectl apply -f gatewayclass.yaml
kubectl apply -f gateway.yaml
kubectl apply -f httproute.yaml

Check resources:

kubectl get gatewayclass
kubectl get gateway
kubectl get httproute

Describe resources:

kubectl describe gateway nginx-gateway
kubectl describe httproute basic-route

Installing NGINX Gateway Controller

Gateway API defines the resources, but a controller is required to implement them.

Example using NGINX Gateway Fabric:

kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.2" | kubectl apply -f -

kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.2" | kubectl apply -f -

helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --create-namespace \
  -n nginx-gateway

Warning

Use official installation instructions for your selected Gateway API controller in production.
Controller installation commands can change across versions.

HTTP to HTTPS Redirect

Gateway API supports redirects using proper spec fields.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: https-redirect
  namespace: default
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https

Success

This avoids controller-specific redirect annotations.

Path Rewrite

Rewrite /old to /new before forwarding traffic.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rewrite-path
  namespace: default
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /old
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          replacePrefixMatch: /new
    backendRefs:
    - name: my-app
      port: 80

Example

A request to /old/login can be rewritten before reaching the backend Service.

Header Modification

Gateway API supports request and response header modification.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-mod
  namespace: default
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
          x-env: staging
    backendRefs:
    - name: my-app
      port: 80

Tip

Header modification is useful for environment tagging, tracing, and routing metadata.

Traffic Splitting

Gateway API supports weighted backend routing.

Example canary release:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: traffic-split
  namespace: default
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - backendRefs:
    - name: v1-service
      port: 80
      weight: 80
    - name: v2-service
      port: 80
      weight: 20

Traffic behavior:

Service	Traffic
`v1-service`	80%
`v2-service`	20%

Success

Gateway API makes canary traffic splitting visible and portable without annotations.

Request Mirroring

Request mirroring sends a copy of traffic to another Service.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: request-mirror
  namespace: default
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: mirror-service
          port: 80
    backendRefs:
    - name: my-app
      port: 80

Note

The original request goes to my-app; a copy is sent to mirror-service.

Use cases:

testing new versions
traffic analysis
security inspection
migration validation

TLS Termination

A Gateway can terminate TLS using a Kubernetes Secret.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx-gateway-tls
  namespace: default
spec:
  gatewayClassName: nginx
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: tls-secret
    allowedRoutes:
      namespaces:
        from: All

Warning

Store TLS private keys securely. Do not commit TLS Secrets or private keys to Git.

TCP Gateway Example

Gateway API can expose TCP applications.

Example MySQL-style listener:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tcp-gateway
  namespace: default
spec:
  gatewayClassName: nginx
  listeners:
  - name: tcp
    protocol: TCP
    port: 3306
    allowedRoutes:
      namespaces:
        from: All

Danger

Be careful when exposing databases externally. Prefer private connectivity, NetworkPolicies, authentication, and encryption.

UDP Gateway Example

Example DNS-style listener:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: udp-gateway
  namespace: default
spec:
  gatewayClassName: nginx
  listeners:
  - name: udp
    protocol: UDP
    port: 53
    allowedRoutes:
      namespaces:
        from: All

Note

UDP support depends on the Gateway API implementation and controller capability.

gRPC Route Example

Gateway API can route gRPC traffic.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-route
  namespace: default
spec:
  parentRefs:
  - name: nginx-gateway
  rules:
  - matches:
    - method:
        service: my.grpc.Service
        method: GetData
    backendRefs:
    - name: grpc-service
      port: 50051

Tip

Use GRPCRoute for gRPC-specific routing instead of forcing everything through generic HTTP rules.

Gateway API vs Ingress

IngressGateway API

Good for:

simple HTTP routing
basic host and path routing
small environments
controller-specific features through annotations

Limitations:

annotation-heavy
weak multi-tenancy
limited protocol support
controller-specific behavior

Good for:

production traffic platforms
multi-team environments
HTTP, HTTPS, TCP, UDP, TLS, and gRPC
traffic splitting
structured TLS
better separation of responsibilities

Benefits:

portable API
stronger role separation
fewer annotations
clearer routing ownership

Production Best Practices

Recommended

Use a supported Gateway API controller
Define clear ownership for GatewayClass, Gateway, and Routes
Restrict allowedRoutes in shared clusters
Use TLS for public traffic
Store certificates in Kubernetes Secrets or external secret managers
Use weighted routing for canary deployments
Use request mirroring carefully for testing
Monitor controller health and route status
Apply NetworkPolicies behind the Gateway
Keep Gateway controller versions updated

Security Best Practices

Danger

Gateway API controls external traffic into the cluster. Misconfiguration can expose internal systems.

Security controls:

restrict which namespaces can attach routes
use least privilege RBAC
avoid exposing databases publicly
enable HTTPS
validate backend Services
avoid wildcard hostnames unless required
monitor route changes
protect TLS Secrets
use admission policies for shared clusters

Do's

Use Gateway API when Ingress becomes too limited
Use GatewayClass for infrastructure-level control
Use Gateway for listener and port configuration
Use Routes for application-owned routing
Use allowedRoutes for namespace governance
Use native filters instead of annotations where possible
Validate controller support before using advanced features
Document ownership between platform and application teams

Don'ts

Don't assume every controller supports every Gateway API feature
Don't expose sensitive Services without strict controls
Don't allow all namespaces to attach routes in production without governance
Don't store certificates in plain YAML inside Git
Don't use Gateway API only because it is newer
Don't skip monitoring and route status checks
Don't mix too many responsibilities into one team-owned resource

Troubleshooting Checklist

If Gateway API routing is not working, check:

Are Gateway API CRDs installed?
Is a Gateway API controller installed?
Is the GatewayClass accepted?
Does the Gateway reference the correct GatewayClass?
Are listeners configured on the correct protocol and port?
Is the Route attached to the correct Gateway?
Does allowedRoutes permit the Route namespace?
Does the backend Service exist?
Does the backend Service have endpoints?
Are TLS Secrets valid?
Does the controller support the feature being used?
Are route status conditions showing errors?

Useful Commands

kubectl get gatewayclass

kubectl describe gatewayclass <gateway-class-name>

kubectl get gateway -A

kubectl describe gateway <gateway-name>

kubectl get httproute -A

kubectl describe httproute <route-name>

kubectl get tcproute -A

kubectl get grpcroutes -A

kubectl get svc

kubectl get endpoints <service-name>

kubectl logs -n <gateway-controller-namespace> <gateway-controller-pod>

Common Mistakes

Mistake	Result
Gateway API CRDs missing	Gateway resources fail to create
Controller missing	Resources exist but no traffic flows
Wrong `controllerName`	GatewayClass not accepted
Wrong `gatewayClassName`	Gateway ignored
Route namespace not allowed	Route does not attach
Backend Service missing	Traffic fails
Backend has no endpoints	502 / 503-style errors
Feature unsupported by controller	Route condition shows failure
TLS Secret missing	HTTPS listener fails

Bug

Always check resource status conditions with kubectl describe. Gateway API provides useful acceptance and attachment status.

Summary

Quote

Gateway API is the next generation of Kubernetes traffic routing APIs
It improves Ingress with structured, extensible resources
GatewayClass is managed by infrastructure providers
Gateway is managed by cluster operators
Routes are managed by application developers
Gateway API supports HTTP, HTTPS, TCP, UDP, TLS, and gRPC
It reduces annotation-heavy configuration
It is better suited for production multi-tenant environments