Why Gateway API?

Why Gateway API instead of Ingress?

The Kubernetes project recommends using the Gateway API instead of the traditional Ingress resource because the Ingress API has been frozen and will no longer receive new features or updates.

While Ingress provided a simple abstraction for exposing HTTP and HTTPS routes, its simplicity became a bottleneck for complex modern deployments. The Ingress object lacked native fields for advanced traffic routing, meaning that to achieve common use cases—such as header-based matching, traffic weighting, or fine-grained request filtering—users were forced to rely heavily on custom, controller-specific annotations (such as those used by the NGINX Ingress Controller). This over-reliance on annotations made configurations highly brittle, difficult to validate, and non-portable across different ingress implementations.

To solve these architectural flaws, the Gateway API was designed from the ground up to be expressive, extensible, and fundamentally role-oriented. It breaks the monolithic Ingress object into a hierarchy of independent API resources, each mapping to a specific organizational persona.

The Architectural Split

The Gateway API model separates infrastructure provisioning from application routing using three primary resources:

1. GatewayClass (Managed by the Infrastructure Provider) This resource acts as a template that defines a set of gateways with a common configuration, specifying exactly which underlying controller should implement the class. It allows a cloud provider or infrastructure team to offer standardized infrastructure profiles that can serve multiple tenants across isolated clusters.

2. Gateway (Managed by the Cluster Operator) A Gateway represents a physical or logical instance of traffic-handling infrastructure, such as a cloud load balancer or an in-cluster proxy server. Cluster operators use this resource to define network listeners, ports, and protocols (such as listening for HTTP traffic on port 80) independently of the workloads that will eventually use them.

3. HTTPRoute (Managed by the Application Developer) The HTTPRoute specifies the actual application-level routing behavior, mapping traffic from a Gateway listener down to backend network endpoints (like a Kubernetes Service). Application developers use this resource to define specific match rules based on hostnames, paths, or HTTP headers, and to configure filters that can modify the request before it reaches the backend. (Note: The API also provides resources like GRPCRoute for natively routing gRPC traffic).

How This Solves the Limitations of Ingress Annotations

This decoupled architecture elegantly resolves the pain points of the traditional Ingress model:

• Native Expressiveness Over Annotations: Instead of stuffing complex routing logic into unstructured string annotations, Gateway API elevates these concepts into first-class, strongly-typed API fields. Traffic splitting, header matching, and request modification are now defined cleanly inside the HTTPRoute schema, allowing the API server to perform strict schema validation and prevent misconfigurations.
• Separation of Concerns & Bidirectional Trust: In the old model, both infrastructure operators and application developers had to edit the same Ingress object, creating friction and security risks. The Gateway API decouples these lifecycles. The cluster operator manages the Gateway and can explicitly configure which HTTPRoute resources are permitted to attach to its listeners (for example, only allowing routes from the same namespace). This establishes a bidirectional trust model: the Gateway filters the routes it accepts, and the HTTPRoute specifies the Gateway it wants to attach to.
• Portability and Extensibility: Because the API relies on standardized Custom Resources rather than vendor-specific annotations, routing configurations are highly portable across different Gateway API implementations. If deep customization is still required, the API allows extension resources to be explicitly linked at specific layers, providing granularity without breaking the core structure.