Understanding Kubernetes Gateway API

What is Gateway API?

Gateway API is a Kubernetes SIG-Network project that defines a standardized, role-oriented model for managing ingress traffic in a cluster. It was designed to address the structural limitations of the original Ingress resource, which lacked native support for advanced routing behavior and relied heavily on vendor-specific annotations to fill the gaps.

Gateway API replaces that single-resource model with a set of purpose-built resources, each with a clearly defined scope of responsibility. This allows infrastructure teams and application teams to manage their respective concerns independently, while remaining portable across different ingress controller implementations.

Gateway API — Request Flow (GatewayClass → Gateway → HTTPRoute → Services)

---

Why Gateway API Exists

The Ingress resource was intentionally minimal, supporting only basic host and path-based routing. To support real-world requirements — TLS termination, header-based routing, traffic splitting, request/response transformation — vendors implemented these features through custom annotations. This created two persistent problems: configuration was not portable between controllers, and there was no clear separation between infrastructure-level configuration and application-level routing rules.

Ingress Model	Gateway API Model
Single resource for all routing concerns	Split into GatewayClass, Gateway, HTTPRoute
Feature support via vendor-specific annotations	Standardized fields supported across implementations
No clear ownership boundary	Infrastructure teams own Gateway; application teams own HTTPRoute
Limited routing expressiveness	Native support for header matching, traffic splitting, redirects

---

Core Resources

Gateway API defines three primary resource types, each with a distinct responsibility.

GatewayClass

A cluster-scoped resource that specifies which controller implementation is responsible for managing Gateways that reference it. This is typically defined once by the platform or infrastructure team and rarely changes.

Gateway

Defines the actual listener configuration — the port, protocol, hostname, and TLS certificate the proxy should use. This resource is generally owned and managed by infrastructure teams, since it represents shared entry-point configuration.

HTTPRoute

Defines the routing logic attached to a Gateway — path matching, header matching, traffic splitting across backend versions, and request/response modification. This resource is typically owned by application teams, since it governs routing behavior specific to their service.

---

Configuration vs. Execution

A critical distinction in Gateway API — one that is frequently omitted from introductory explanations — is that GatewayClass, Gateway, and HTTPRoute are purely declarative Kubernetes API objects. They do not process traffic themselves. They exist as state stored in etcd, in the same way a Deployment manifest exists as state before any Pod is actually running.

This is architecturally different from a Service, which kube-proxy actively converts into iptables or IPVS rules on every node. A Gateway object has no equivalent automatic mechanism baked into the API server. Something external must read this configuration and act on it — that responsibility belongs to the Controller, and the component that actually serves traffic is the Proxy.

This produces a clear separation between:

• Control Plane — where Gateway API resources are stored, and where the Controller watches for changes via the Kubernetes API
• Data Plane — where the Proxy terminates connections and serves live traffic based on configuration it has received

Control Plane (configuration, watched by the Controller) vs Data Plane (Proxy serving live traffic)

---

Request Flow: From Configuration to Live Traffic

1 — Resources are applied to the cluster

GatewayClass, Gateway, and HTTPRoute objects are submitted through the Kubernetes API server, validated, and persisted in etcd — identical to how any other Kubernetes resource is stored.

2 — The Controller detects the change

The Controller (e.g., Envoy Gateway, Istio, NGINX Gateway Fabric, Cilium) runs a continuous watch on the Kubernetes API for any GatewayClass, Gateway, or HTTPRoute object that references it.

3 — The Controller translates the configuration

The Controller converts the declarative Gateway API resources into a format the underlying proxy understands — for example, Envoy's xDS configuration, or an NGINX configuration file.

4 — The Controller pushes the configuration to the Proxy

This step is the one most diagrams omit. The Controller delivers the translated configuration to the data-plane Proxy, typically through a dynamic configuration protocol that allows updates without a restart.

5 — The Proxy serves live traffic

The Proxy is the component actually bound to the listening port, terminating TLS, and evaluating incoming requests against the rules it has received. Matched requests are forwarded to the appropriate backend Service, which load-balances across its Pods.

A Gateway or HTTPRoute object represents desired state, not an active process. Just as a Deployment manifest does nothing until the Controller Manager and kubelet act on it, a Gateway or HTTPRoute has no effect on traffic until a Controller compiles it into proxy configuration. Treating the Gateway object as though it directly serves traffic — the way a Service is often assumed to — is a common source of misunderstanding.

---

Component Reference

Component	Plane	Responsibility
GatewayClass	Control Plane	Specifies which controller implementation manages this Gateway
Gateway	Control Plane	Defines listener configuration: port, hostname, TLS
HTTPRoute	Control Plane	Defines routing rules: path/header matching, traffic splitting
Controller	Control Plane → Data Plane	Watches Gateway API resources, translates and delivers configuration to the proxy
Proxy	Data Plane	Terminates connections and serves live traffic based on delivered configuration
Service / Pods	Data Plane	Final backend receiving routed traffic

---

Key Features of Gateway API

• Role-oriented resource model — Infrastructure teams manage Gateway; application teams manage HTTPRoute, without requiring shared write access to a single resource.
• Portability across implementations — The same HTTPRoute configuration is expected to function consistently across supported controllers, reducing vendor lock-in.
• Native expressive routing — Path, header, and method-based matching, along with weighted traffic splitting for canary or blue-green deployments, are supported without custom annotations.
• Multi-protocol support — In addition to HTTPRoute, the API defines TCPRoute, TLSRoute, and GRPCRoute for non-HTTP traffic types.
• Defined extensibility points — Controllers can expose implementation-specific features through standardized extension mechanisms rather than arbitrary annotations.
• Shared Gateway support — Multiple HTTPRoute resources, potentially across different namespaces, can attach to a single shared Gateway, enabling multi-tenant traffic management.

---

Summary

Gateway API's primary contribution is not additional routing features on their own — it is the architectural separation between declared intent and executed behavior. Configuration is defined through GatewayClass, Gateway, and HTTPRoute; the Controller translates that configuration; and the Proxy is the component that actually executes it against live traffic.

This configuration-versus-execution pattern is consistent with the rest of Kubernetes' design — a Deployment does not run a container, a Controller Manager and kubelet do; a Gateway does not route a request, a Controller and Proxy do. Understanding this distinction clarifies not only Gateway API, but the broader model underlying Services, kube-proxy, and Ingress controllers as well.