Introduction to Gateway API 2025 Updates

In this lesson we introduce the Gateway API and explain how it solves key limitations of the traditional Kubernetes Ingress. You’ll learn why Gateway API improves ownership boundaries, TLS configuration, multi-protocol support, canary/traffic-splitting, and filters — all in a controller-agnostic, declarative way. Why this matters

In multi-tenant or multi-team clusters, a single Ingress resource often becomes a points of conflict.
Advanced behaviors are typically implemented as controller-specific annotations, reducing portability and making validation difficult.
Gateway API provides a structured model that separates responsibilities across infrastructure operators and application teams while enabling first-class features for modern traffic management.

Ingress single-resource ownership problem Early Ingress implementations encouraged representing routing for many services inside a single resource. That single-resource model creates operational friction in multi-team environments because only one team can safely manage the Ingress at a time.

A schematic diagram titled "Ingress — Limitations" showing an ingress layer (green bar) routing traffic to two services labeled "wear-service" and "video-service." Each service connects down to groups of backend pods represented by circular nodes labeled "wear" and "Video."

Example: single Ingress handling multiple hosts Here is a common modern Ingress manifest where one resource defines host routing for two services — a pattern that can introduce ownership and coordination issues:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-wear-watch
spec:
  rules:
  - host: wear.my-online-store.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: wear-service
            port:
              number: 80
  - host: watch.my-online-store.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: watch-service
            port:
              number: 80

Controller-specific annotations reduce portability Advanced behaviors (TLS redirection, canary weights, CORS, header rewrites, rate limiting) are often expressed via annotations specific to a particular ingress controller (NGINX, Traefik, etc.). Kubernetes itself cannot validate these annotations, so configurations are not portable across controllers. Example: NGINX SSL redirect via annotations

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-wear-watch
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
spec:
  rules:
  - host: wear.my-online-store.com
    http:
      paths:
      - path: /foo
        pathType: Prefix
        backend:
          service:
            name: wear-service
            port:
              number: 80
  - host: watch.my-online-store.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: watch-service
            port:
              number: 80

Gateway API: multi-role, protocol-flexible, controller-agnostic Gateway API is a Kubernetes project designed for Layer 4 and Layer 7 routing. It replaces the single-resource Ingress model with multiple, focused resources and clear ownership:

Infrastructure providers define GatewayClass (which controller implementation will manage Gateways).
Cluster operators create Gateways (instances of a GatewayClass that represent tangible infrastructure endpoints).
Application developers create Route resources (HTTPRoute, TCPRoute, GRPCRoute, UDPRoute, TLSRoute, etc.) and attach them to Gateways.

A "Gateway API" diagram showing three stacked roles: Infrastructure Providers with GatewayClass, Cluster Operators with Gateway, and Application Developers with HTTPRoute and TCPRoute. Each role is represented by a small icon and rounded blue boxes for the components.

Separation of concerns

Gateways are owned and managed by infrastructure/cluster operators (exposing listeners, TLS settings, and binding to a controller).
Routes are owned by application teams; they reference Gateways via parentRefs to attach routing rules and backend destinations.
This model enables multi-tenancy with clearer ownership and safer delegation.

Canonical resource examples Below are canonical examples for the three primary Gateway API objects: GatewayClass, Gateway, and HTTPRoute (Gateway API v1). These examples illustrate how controller selection, listeners, and route attachment work together.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-class
spec:
  controllerName: example.com/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-httproute
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "www.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /login
    backendRefs:
    - name: example-svc
      port: 8080

How it works

GatewayClass determines which controller implementation will reconcile Gateways.
Gateway exposes listeners (for example, an HTTP listener on port 80) and binds to the chosen controller.
HTTPRoute references the specific Gateway via parentRefs, declares host/path matching, and points to backend services using backendRefs.

Supported route types Gateway API includes first-class support for many route kinds: HTTPRoute (L7), TLSRoute, TCPRoute, UDPRoute, GRPCRoute, and more — enabling native multi-protocol routing beyond HTTP. TLS termination and HTTPS redirection Ingress often encodes TLS in spec.tls and relies on controller annotations for redirection. Gateway API models listeners and TLS settings explicitly in the Gateway resource, eliminating annotation-based TLS setups for typical use cases. Ingress TLS (controller-specific annotation approach):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: secure-app
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
spec:
  tls:
  - hosts:
    - secure.example.com
    secretName: tls-secret

Gateway TLS (declarative, structured approach):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: secure-gateway
spec:
  gatewayClassName: example-gc
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: tls-secret
    allowedRoutes:
      kinds:
      - kind: HTTPRoute

Benefits of the Gateway approach

TLS termination is explicit and declarative.
The Gateway defines which route kinds are allowed to attach to a listener.
No controller-specific annotations are required for standard TLS termination and listener behavior.

Traffic splitting (canary) without annotations Canary and traffic splitting are often done with controller-specific annotations in Ingress. Gateway API makes traffic splitting a first-class capability using weight fields on backendRefs, which is portable across controllers. Ingress (NGINX canary via annotations):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: canary-ingress
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-v2
            port:
              number: 80

Gateway API HTTPRoute traffic split (explicit and controller-agnostic):

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

Because weights are native fields in HTTPRoute, any conformant Gateway controller can implement traffic splitting consistently. Filters and header manipulation (CORS example) Advanced features — CORS, header modification, response header injection — were commonly implemented via controller annotations. Gateway API introduces a filters model on routes that is consistent across controllers that implement the filter set. Ingress examples (controller-specific annotations):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cors-ingress
  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"
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: traefik-ingress
  annotations:
    traefik.ingress.kubernetes.io/headers.customresponseheaders: |
      Access-Control-Allow-Origin: '*'
      Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
      Access-Control-Allow-Headers: Content-Type,Authorization
      Access-Control-Allow-Credentials: true
      Access-Control-Max-Age: 3600

Gateway API HTTPRoute with ResponseHeaderModifier filter:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cors-route
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    filters:
    - type: ResponseHeaderModifier
      responseHeaderModifier:
        add:
        - name: Access-Control-Allow-Origin
          value: "*"
        - name: Access-Control-Allow-Methods
          value: "GET,POST,PUT,DELETE,OPTIONS"
        - name: Access-Control-Allow-Headers
          value: "Content-Type,Authorization"
        - name: Access-Control-Allow-Credentials
          value: "true"
        - name: Access-Control-Max-Age
          value: "3600"
    backendRefs:
    - name: api-service
      port: 80

This structured approach is portable: a conformant Gateway controller that implements ResponseHeaderModifier can honor these directives consistently. Ingress vs Gateway API — quick comparison

Area	Ingress (traditional)	Gateway API
Ownership model	Single resource often managed by one team	Separate GatewayClass/Gateway (infra) and Routes (apps)
TLS configuration	`spec.tls` + controller annotations	Structured TLS on Gateway listeners
Advanced behaviors	Controller-specific annotations	First-class filters and route fields
Traffic splitting	Annotations (controller-specific)	`weight` on backendRefs (portable)
Protocols	Primarily HTTP	HTTP, TLS, TCP, UDP, GRPC, etc.
Portability	Low for advanced features	Higher — controller-agnostic model

Gateway API adoption and controllers Many popular ingress and service-mesh projects and managed providers have implemented or are implementing Gateway API support. Examples include Amazon EKS, Azure Application Gateway, Contour, Envoy Gateway, GKE, HAProxy, Istio, Kong, Kuma, NGINX Gateway, and Traefik.

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

Introduction to Gateway API 2025 Updates

Watch Video