Kubernetes Gateway API Architecture Diagram: Gateways Routes & Policies

The Kubernetes Gateway API concept page describes an add-on family of custom resources for dynamic infrastructure and advanced traffic routing. Kubernetes does not implement the kinds itself. The design is role-oriented, portable, expressive where Ingress often needed annotations, and extensible by linking further custom resources. The SIG homepage, fetched directly, is only a redirect shell to /docs. It lists no kinds. The boxes below follow the concept page.

What this Kubernetes Gateway API architecture diagram shows

The four stable kinds are the ones this diagram uses. GatewayClass names a controller. Gateway is one piece of traffic infrastructure, a cloud load balancer or an in-cluster proxy. HTTPRoute and GRPCRoute map a listener to backends, often a Service. A Gateway references exactly one GatewayClass, then one or more routes associate to it. The Gateway can filter which routes attach to its listeners, which the page calls a bidirectional trust model. The controller is an implementation box, not a fifth stable kind.

The problem this architecture is solving

Ingress often needed implementation-specific annotations for routing the concept page now treats as ordinary. It names header-based matching and traffic weighting. The same page separates roles, and those roles are not fields in the sample YAML. An infrastructure provider manages infrastructure that lets multiple isolated clusters serve multiple tenants, for example a cloud provider. A cluster operator is typically concerned with policies, network access, and application permissions. An application developer is typically concerned with application-level configuration and Service composition.

Gateway API is the successor to the Ingress API and does not include the Ingress kind, so moving is a one-time conversion, not a rename. You install the CRDs or follow one implementation, then read that implementation's caveats. Conformance covers release channels, support levels, and tests. This page publishes no pass rate.

Main components and trust boundaries

A minimal GatewayClass is gateway.networking.k8s.io/v1 with a controllerName such as example.com/gateway-controller. The page says different controllers often use different configuration, which is why the class exists. Gateways of that class are managed by the implementation's controller.

The sample Gateway is in example-namespace, points at example-class, and listens as http on HTTP port 80 for www.example.com. allowedRoutes.namespaces.from is Same. With addresses omitted, the implementation’s controller fills in a Gateway address or hostname. That is not the route-backend endpoint. The page's picture of a Gateway is filtering, balancing, and splitting for a Service, either as a cloud load balancer or an in-cluster proxy. It points at a TLS guide for HTTPS and does not include certificate fields here.

Same-namespace attachment is the default. Cross-namespace routes need allowedRoutes. That is the trust boundary between the platform listener and an application namespace. The cluster operator's policy concern, in the design principles, is this kind of control. The page never names a policy CRD and never says a policy object owns the load balancer. Extensibility is only "custom resources linked at various layers."

The sample HTTPRoute parents example-gateway, matches host www.example.com and path prefix /login, and backends Service example-svc port 8080. A Service backend may be the Service IP or its EndpointSlices. A new route may program the load balancer or proxy. It does not create the Gateway.

GRPCRoute parents a Gateway the same way. Supporting it requires HTTP/2 with no initial upgrade from HTTP/1. One sample sends svc.example.com to example-svc:50051. Another matches service: com.example and method: Login toward foo-svc:50051. The next sentence says only com.example.User.Login is forwarded. Those strings disagree. Other RPCs miss that route.

Request or data path, step by step

The concept page's reverse-proxy example has six steps. The client prepares http://www.example.com. DNS resolves one or more Gateway addresses. The client sends the request to that IP. The proxy matches the Host header to configuration from the Gateway and the attached HTTPRoute. It may also match headers or the path. It may add or remove headers from the route's filter rules. It then forwards to one or more backends.

On the sample HTTPRoute, host www.example.com and path /login select example-svc:8080. A gRPC call uses the same attachment, plus the HTTP/2 rule, and only the matched method is forwarded. This page does not describe a mesh path, GAMMA, or a TCP listener.

The diagram: labeled boxes and failure or isolation edges

Client and DNS go to the Gateway. The listener inside that Gateway holds the allow-list. The route boxes are HTTPRoute and GRPCRoute, then Service or EndpointSlices. Gateway address is the arrow label into the Gateway, not its own box. GatewayClass sits below the Gateway, and the controller name is text inside that box.

• Namespace: default is same namespace. The sample sets from: Same.
• Attach filter: a route the listener does not allow does not attach.
• No match: wrong host, path, or gRPC method misses the rule.
• Empty addresses: the implementation’s controller fills a Gateway address or hostname. The diagram does not show a fixed VIP.
• No Ingress object on the diagram. Conversion stays off to the side.

What the source does not claim (preview, case study, or limits)

This is an evergreen concept page, not a preview or a case study. It names four stable kinds and stops. It does not document TCPRoute, GAMMA, or a mesh profile, and it gives no latency or conformance score. Header matching and traffic weighting are named, not fully specified, beyond the samples. Implementation caveats stay with the implementation you installed. The SIG URL does not add a resource model. The fetch is only a redirect to /docs.

How this differs from a nearby pattern on ByteDiagram

The Kubernetes cluster architecture diagram is the primer for how a cluster is shaped. This post is only the Gateway API role split: one GatewayClass, one Gateway as the load balancer or proxy, routes that attach under allowedRoutes, and a controller that programs that instance. It is not a control-plane or node diagram, and it is not an Ingress annotation map.

FAQ

Who owns the Gateway versus an HTTPRoute?

The concept page splits roles and does not add an owner field. Infrastructure providers run tenant infrastructure. Cluster operators handle policies, network access, and application permissions. Application developers handle app configuration and Service composition. A Gateway is the load balancer or in-cluster proxy and must reference one GatewayClass. An HTTPRoute attaches with parentRefs and names a Service. The page does not say a policy object owns the load balancer.

Can a route in another namespace attach to a Gateway by default?

No. A Gateway accepts Routes only from the same namespace unless allowedRoutes is set. The sample uses allowedRoutes.namespaces.from: Same. The Gateway may also filter which routes attach to a listener. The page calls that a bidirectional trust model.

Does Gateway API include the Ingress kind, TCPRoute, or GAMMA?

The concept page calls Gateway API the successor to Ingress and says it does not include the Ingress kind, so existing Ingress objects need a one-time conversion. It lists four stable kinds: GatewayClass, Gateway, HTTPRoute, and GRPCRoute. It does not name TCPRoute or GAMMA. Gateway API is an add-on of custom resources, not kinds implemented natively by Kubernetes. The SIG homepage, when fetched, only redirects to /docs and does not add those kinds.

Conclusion

The Gateway and GatewayClass are the platform instance. The route names the Service. Cross-namespace attachment stays closed until allowedRoutes opens it. On this page, policy is the cluster operator's concern, not a CRD to invent. Cite the Kubernetes Gateway API page and the SIG site. More diagrams are on the ByteDiagram blog.