Gateway API — Next-Generation Ingress

Replace classic Ingress with the role-oriented Gateway API: GatewayClass, Gateway, and HTTPRoute.

intermediate60 minRead → Lab → Quiz → Practice

🧠 Brain Warm-Up

🧠 Brain Warm-Up: Classic Kubernetes Ingress routes HTTP traffic, but it has no standard way to split traffic 90/10 between two backends, or route based on HTTP headers. Why do you think that is — and what would you need to add to the API to support it? Think before reading.

Why Gateway API Exists

Classic Ingress was designed for a simple use case: route HTTP hostnames to Services. As teams tried to do more — canary deployments, header-based routing, gRPC, TCP — they discovered that Ingress annotations were the only escape hatch. Every controller (nginx, traefik, haproxy) invented its own annotation namespace, making configs non-portable.

Gateway API (GA since Kubernetes 1.28) solves this with a structured, role-oriented API that is expressive enough to cover these use cases without annotations.

Resource Hierarchy

Cluster-scoped:
  GatewayClass  ←── names the controller (e.g. nginx, istio, cilium)

Namespace-scoped:
  Gateway       ←── defines listeners: protocol (HTTP/HTTPS/TCP) + port
    └── HTTPRoute ←── defines routing rules → backend Services

Role Separation

Resource	Owner	Scope
GatewayClass	Infrastructure admin	Cluster
Gateway	Infrastructure admin	Namespace
HTTPRoute	Application developer	Namespace

This separation means app developers can attach routes to a shared Gateway without needing cluster-admin privileges — a major improvement over Ingress.

Ingress vs Gateway API Comparison

Feature	Ingress	Gateway API
Traffic splitting	Annotation-only (non-standard)	`weight` field in HTTPRoute
Header routing	Annotation-only	`matches.headers` in HTTPRoute
TCP/gRPC	Not standard	TCPRoute / GRPCRoute
Role separation	None	GatewayClass / Gateway / Route
Multi-controller	One controller per Ingress	Multiple Gateways per class

HTTPRoute Key Fields

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
spec:
  parentRefs:          # which Gateway(s) to attach to
    - name: my-gateway
      namespace: default
  hostnames:           # replaces Ingress host
    - "app.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:     # where to send traffic
        - name: api-service
          port: 8080
          weight: 90
        - name: api-service-v2
          port: 8080
          weight: 10

The weight field enables canary deployments natively — no annotations needed.

←

PersistentVolumes — Storage Lifecycle

RBAC (Role-Based Access Control)

→