Kubernetes Gateway API Explained: The Modern Approach to Application Traffic
Learn Kubernetes Gateway API with GatewayClass, Gateway, HTTPRoute, GRPCRoute, traffic routing, cross-namespace security, troubleshooting and production best practices.
Kubernetes Gateway API Explained: The Modern Approach to Application Traffic
A practical guide to GatewayClass, Gateway, HTTPRoute, traffic routing, role separation, cross-namespace references and production design.
Introduction
Kubernetes Services provide stable endpoints for workloads, but exposing modern applications to external clients often requires more than a simple Service. Teams may need host-based routing, path-based routing, TLS termination, traffic splitting, protocol-aware routing and clear separation of infrastructure and application responsibilities.
Gateway API is a Kubernetes project that provides APIs for dynamic infrastructure provisioning and advanced traffic routing. It is designed to be role-oriented, expressive and protocol-aware, and it can be used for both north-south traffic and, with appropriate implementations, east-west traffic.
Gateway API does not replace the Kubernetes Service object. Instead, it provides a higher-level traffic-management model that can use Services as backends. This article explains the architecture and the core resources you need to understand before using Gateway API in production.
1. What Is Gateway API?
Gateway API is a collection of Kubernetes API resources for configuring traffic-handling infrastructure and routing traffic to backend Services. The core model separates infrastructure configuration from application routing rules.
The central resources are GatewayClass, Gateway and protocol-specific Route resources such as HTTPRoute and GRPCRoute.
2. Why Gateway API Was Introduced
Traditional Kubernetes Ingress provides a widely used API for HTTP/HTTPS ingress, but implementations have historically relied on annotations or implementation-specific extensions for many advanced features. Gateway API was designed as a more expressive and extensible model with explicit resources and clearer separation of responsibilities.
• Role-oriented configuration separates infrastructure and application concerns.
• Protocol-specific Route resources make routing intent explicit.
• A Gateway can have multiple listeners and can serve multiple Routes.
• Routes can express hostname, path, header, query-parameter and other protocol-specific matching.
• The API supports advanced traffic-management patterns while keeping the core model portable across implementations.
Gateway API is an add-on API project; installing Kubernetes alone does not automatically mean that a Gateway API implementation is present. A compatible Gateway controller or implementation must be installed and configured.
3. Gateway API Resource Model
A useful mental model is:
The resource model is intentionally separated. A GatewayClass identifies the implementation, a Gateway represents an actual traffic-handling instance, and Routes describe how incoming traffic is mapped to Services.
4. GatewayClass
GatewayClass is a cluster-scoped resource representing a class of Gateways with a common configuration and behavior. Each GatewayClass is associated with a controller through its controllerName.
The controllerName is not a value that should be invented for a real cluster. It must match the controller that implements Gateway API in your environment. The example above is illustrative.
A cluster may have more than one GatewayClass. For example, a platform team could provide different classes for different infrastructure or operational requirements.
5. Gateway
A Gateway represents an instance of traffic-handling infrastructure. It defines listeners, including the network port and protocol, and can be associated with one GatewayClass.
This example creates an HTTP listener on port 80. The exact external address and datapath are determined by the Gateway API implementation associated with the GatewayClass.
The allowedRoutes configuration is important in multi-team environments because it controls which Routes may attach to a listener.
6. HTTPRoute
HTTPRoute defines HTTP routing rules. It can match HTTP requests using information such as hostname, path, headers and query parameters, and it can forward matching requests to backend Services.
The Route attaches to the Gateway through parentRefs. The backendRefs identify the Service and port that should receive matching traffic.
7. Complete Example: Gateway + HTTPRoute + Service
The following example illustrates the relationship between the resources. The GatewayClass controller name is intentionally shown as a placeholder because real installations use the controller name required by the selected Gateway API implementation.
This is a conceptual example. Before applying it to a real cluster, replace the GatewayClass controllerName and ensure that a compatible Gateway API implementation is installed.
8. How Gateway API Traffic Flows
1. A client sends traffic toward the Gateway's external or internal address.
2. The Gateway listener accepts traffic matching its configured protocol, port and listener rules.
3. An attached Route evaluates the request against its routing rules.
4. A matching rule selects one or more backend references.
5. The Gateway implementation forwards traffic toward the referenced Kubernetes Service.
6. The Service provides the backend endpoint abstraction for the application Pods.
The precise datapath varies by Gateway implementation. Gateway API standardizes the Kubernetes API model and behavior, while the implementation is responsible for realizing that model in the data plane.
9. Gateway API vs Kubernetes Service
10. Gateway API vs Ingress
Ingress remains a valid Kubernetes API for exposing HTTP and HTTPS applications, and many production systems still use it. Gateway API provides a newer, more expressive model with explicit resources for infrastructure and routing responsibilities.
Gateway API is not simply a renamed Ingress object. It changes the resource model so that infrastructure, listeners and application routing can be managed independently.
11. Role-Oriented Architecture
One of Gateway API's most important design principles is separation by role.
This separation allows platform teams to provide approved Gateway infrastructure while application teams manage their own routing rules without needing to own the underlying load-balancing implementation.
12. Multiple Routes on One Gateway
A major benefit of Gateway API is that multiple Routes can attach to a Gateway. HTTPRoute can use hostnames and paths to multiplex applications over shared listeners.
This can allow a platform team to operate a shared Gateway while individual application teams own their Route objects, subject to the Gateway's attachment and namespace rules.
13. HTTPRoute Matching
HTTPRoute supports several ways to identify requests. Common routing dimensions include hostname, path, headers and query parameters.
This illustrates the expressive model, but the exact combination of matches and filters should be validated against the Gateway API version and implementation being used.
14. Traffic Splitting and Canary Patterns
Gateway API can express weighted backend references in supported Route types. This makes patterns such as gradual traffic shifting possible without creating a separate external entry point for every version.
The weights describe the intended distribution among eligible backends according to the Gateway implementation. Do not interpret a weight configuration as a guarantee of exact request percentages over a small sample.
15. TLS and HTTPS
Gateway listeners can be configured for TLS. Gateway API separates the listener definition from the HTTP routing rules, allowing the platform-level TLS endpoint and application-level HTTP routing to be managed independently.
The Secret reference and TLS behavior must be supported by the selected Gateway implementation. Cross-namespace Secret references require the appropriate ReferenceGrant when permitted by the API and implementation.
16. ReferenceGrant and Cross-Namespace Routing
Gateway API includes explicit controls for cross-namespace references. A Route referencing a backend Service in another namespace requires a ReferenceGrant in the target namespace, unless an API-defined exception applies.
The ReferenceGrant is an important security mechanism. Without an appropriate grant, a cross-namespace backend reference is not permitted by the Gateway API model.
This explicit trust relationship helps prevent an application team from silently reaching resources owned by another namespace.
17. GRPCRoute
Gateway API also defines GRPCRoute for idiomatic gRPC routing. GRPCRoute is a Standard Channel resource and provides gRPC-aware matching, including service and method information.
For basic gRPC routing, HTTPRoute can sometimes be sufficient because gRPC uses HTTP/2. GRPCRoute is preferable when you want the routing configuration to explicitly express gRPC semantics or use gRPC-specific functionality supported by the implementation.
18. Other Gateway API Route Types
Gateway API evolves through release channels. Always verify the current API documentation and the conformance level supported by the implementation before designing production dependencies on a particular Route type or feature.
19. Gateway API Does Not Automatically Provide a Data Plane
Defining GatewayClass, Gateway and HTTPRoute objects does not by itself create a working proxy or load balancer. A Gateway API implementation must watch these resources and translate them into the data-plane configuration used to process traffic.
Different implementations may use cloud load balancers, in-cluster proxies, dedicated gateways or other architectures. Therefore, operational commands and implementation-specific features differ between products.
20. Installing Gateway API
Gateway API is an add-on API project. The installation process depends on the chosen implementation. A production cluster should select an implementation that supports the Gateway API features and conformance levels required by the application.
• Choose a Gateway API implementation appropriate for the cluster environment.
• Install the implementation according to its official documentation.
• Verify that the required Gateway API CRDs are installed.
• Verify that at least one GatewayClass is available.
• Create a Gateway and Route only after the implementation is ready.
21. Troubleshooting Gateway API
Step 1: Check GatewayClass
Confirm that the GatewayClass exists and that its controller is available.
Step 2: Check Gateway Status
Inspect listener conditions and status fields. Conditions such as Accepted and Programmed are especially useful when diagnosing whether the implementation has accepted and realized the configuration.
Step 3: Check HTTPRoute
Check whether the Route is accepted by the Gateway and whether its backend references are resolved.
Step 4: Check Services and EndpointSlices
A Gateway can have a valid Route while the backend application itself is unavailable. Verify the Service selector, backend port and ready endpoints.
Step 5: Check Controller Logs
Controller logs are implementation-specific but can reveal configuration, listener, backend or programming errors.
22. Common Gateway API Problems
23. Gateway API vs LoadBalancer Service
A LoadBalancer Service and Gateway API solve related but different problems. A LoadBalancer Service exposes a Service through an external load balancer. Gateway API provides a richer API model for configuring listeners and protocol-aware routing to Services.
24. Gateway API and Service: They Work Together
Gateway API should not be viewed as a replacement for Services. The common pattern is:
Gateway handles the external or gateway-level traffic decision, while Service provides the stable backend abstraction for the application.
25. Security Considerations
• Control which namespaces can attach Routes to shared Gateways using listener allowedRoutes.
• Use ReferenceGrant deliberately for cross-namespace references.
• Avoid granting broad cross-namespace access when a narrow grant is sufficient.
• Treat TLS certificate references as sensitive configuration and apply appropriate namespace ownership controls.
• Use NetworkPolicy for workload-level traffic restrictions; Gateway API routing alone is not a replacement for network security controls.
• Review implementation-specific security controls, authentication, authorization, WAF and rate-limiting features separately from the core Gateway API specification.
26. Production Architecture Example
A platform team can operate a shared Gateway while application teams own Routes.
This architecture is especially useful when many teams need application routing but the organization wants centralized control over external infrastructure.
27. Hands-On Lab
The following lab assumes that a compatible Gateway API implementation is already installed and that the GatewayClass name is known.
After applying the Gateway and Route resources, inspect their status and test the Gateway address exposed by your implementation.
The exact external address, controller namespace and testing method depend on the Gateway implementation and cluster environment.
28. Best Practices
• Treat GatewayClass as platform infrastructure and avoid letting application teams modify it without appropriate authorization.
• Use shared Gateways when the platform architecture benefits from centralized entry points and controlled multi-team routing.
• Keep application routing in Route resources so application teams can own their traffic rules independently.
• Use listener allowedRoutes to explicitly control which Routes may attach.
• Use ReferenceGrant for narrowly scoped cross-namespace references.
• Prefer protocol-specific Route resources when they express application intent more clearly.
• Validate Gateway and Route status conditions during deployments.
• Test routing, TLS, failure behavior and backend changes before production rollout.
• Document which Gateway API implementation and feature/conformance versions the platform supports.
• Avoid relying on implementation-specific extensions unless their operational and portability trade-offs are understood.
29. Interview Questions
What is Gateway API?
Answer: A family of Kubernetes API resources for dynamic infrastructure provisioning and advanced traffic routing.
What is GatewayClass?
Answer: A cluster-scoped resource representing a class of Gateways and identifying the controller responsible for implementing them.
What is a Gateway?
Answer: A resource representing an instance of traffic-handling infrastructure with listeners and associated configuration.
What is HTTPRoute?
Answer: A Route resource that defines HTTP routing rules from a Gateway to backend Services.
How is Gateway API different from Ingress?
Answer: Gateway API uses a role-oriented multi-resource model and provides more expressive, protocol-specific routing APIs.
Does Gateway API replace Kubernetes Service?
Answer: No. Services remain the common backend abstraction; Gateway API provides traffic-handling and routing configuration.
Why is ReferenceGrant important?
Answer: It explicitly authorizes certain cross-namespace references and prevents unintended access across namespace boundaries.
What is the role of allowedRoutes?
Answer: It controls which Routes can attach to a Gateway listener, including namespace-based restrictions.
Can multiple HTTPRoutes share one Gateway?
Answer: Yes, subject to listener and attachment rules. This is a major use case for shared gateway infrastructure.
Does creating a Gateway resource automatically create a load balancer?
Answer: Not by itself. A compatible Gateway API implementation/controller must be installed and may provision or configure the underlying data plane.
When would you use GRPCRoute?
Answer: When you want gRPC-aware routing semantics and functionality supported by the implementation.
What should you check when an HTTPRoute is not working?
Answer: Check GatewayClass, Gateway status, parentRefs, listener attachment rules, Route status, backend Service/port, EndpointSlices and controller logs.
30. Production Checklist
• Is a supported Gateway API implementation installed?
• Does the required GatewayClass exist and have the correct controller?
• Are Gateway listeners configured for the intended protocols and ports?
• Are Route attachment permissions appropriately restricted?
• Are HTTPRoute/GRPCRoute backend references valid?
• Are cross-namespace references protected with ReferenceGrant?
• Are backend Services healthy and backed by ready endpoints?
• Are TLS certificates and Secret references valid and appropriately scoped?
• Are Gateway and Route status conditions monitored?
• Have implementation-specific features and conformance levels been verified?
• Is there a clear rollback plan for routing changes?
31. Summary
Gateway API provides a modern Kubernetes API model for application traffic. Its key idea is separation of infrastructure and routing responsibilities: GatewayClass identifies the implementation, Gateway represents traffic-handling infrastructure, and Route resources describe how requests reach backend Services.
For application teams, this model makes routing more expressive and easier to organize. For platform teams, it provides a clearer way to offer shared gateway infrastructure while controlling listener and cross-namespace access.
Gateway API is not a data-plane implementation by itself. Always evaluate the selected implementation, supported conformance levels and operational behavior before using advanced features in production.
The most important concept to remember is the traffic chain: Client → Gateway → Route → Service → backend endpoints. Once this model is clear, advanced routing, TLS, traffic splitting and multi-team application exposure become much easier to reason about.
32. Related BitCodeMatrix Topics
• Kubernetes Service Explained: ClusterIP, NodePort and LoadBalancer
• Kubernetes Ingress Explained
• Kubernetes NetworkPolicy Explained
• Kubernetes Pod Networking Explained
• Kubernetes Deployment Explained: Rolling Updates, Rollbacks and Revision History
• Kubernetes Container Probes: Liveness, Readiness and Startup Probes
• Kubernetes DNS and Service Discovery
Official References
• Kubernetes — Gateway API: https://kubernetes.io/docs/concepts/services-networking/gateway/
• Gateway API — Introduction: https://gateway-api.sigs.k8s.io/introduction/
• Gateway API — API Overview: https://gateway-api.sigs.k8s.io/concepts/api-overview/
• Gateway API — HTTPRoute: https://gateway-api.sigs.k8s.io/reference/api-types/httproute/
• Gateway API — GatewayClass: https://gateway-api.sigs.k8s.io/reference/api-types/gatewayclass/
• Gateway API — ReferenceGrant: https://gateway-api.sigs.k8s.io/reference/api-types/referencegrant/
• Gateway API — GRPCRoute: https://gateway-api.sigs.k8s.io/reference/api-types/grpcroute/