Wiki · Concept · Last reviewed June 25, 2026

Kubernetes Gateway API

Gateway API is Kubernetes' role-oriented service-networking model for exposing and routing traffic through GatewayClass, Gateway, Route, and ReferenceGrant resources.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, Gateway API, routing, service networking, AI infrastructure

Definition

Kubernetes Gateway API is an official Kubernetes project for L4 and L7 routing in Kubernetes. Its introduction describes it as the next generation of Kubernetes Ingress, load balancing, and service mesh APIs, designed to be generic, expressive, and role-oriented. The Kubernetes documentation describes Gateway API as a family of API kinds for dynamic infrastructure provisioning and advanced traffic routing.

For Spiralism, the relevant point is not that Gateway API is another networking abstraction. It is that the API turns exposure, hostnames, listeners, routes, backends, and namespace trust into inspectable Kubernetes objects. When AI services and agent platforms become networked systems, routing configuration becomes part of the governance record.

How It Works

Gateway API resources live in the gateway.networking.k8s.io API group. The API overview names three primary roles: infrastructure provider, cluster operator, and application developer. That separation appears in the resource model. GatewayClass defines a class of gateways with shared behavior and a controller. Gateway requests a traffic-handling point and defines addresses and listeners. Route resources describe how traffic maps from a Gateway to Services or other backends.

Routes are protocol-specific. The API overview discusses HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, and UDPRoute. For AI systems, HTTPRoute and GRPCRoute are especially common because model APIs, embedding services, evaluation endpoints, and agent backends often speak HTTP, HTTPS, or gRPC. A Route attaches to a Gateway through parentRefs, while the Gateway listener controls what kinds of Routes and namespaces may attach.

ReferenceGrant handles cross-namespace references. The official ReferenceGrant page says Routes may forward traffic to backends in other namespaces, and Gateways may refer to Secrets in another namespace, but an owner in the referenced namespace must explicitly allow that reference. Without a valid ReferenceGrant, the cross-namespace reference is invalid.

Agent Context

Agent systems rarely stay inside one process. They call tools, model endpoints, vector stores, payment APIs, browser controllers, sandboxes, and internal services. Gateway API can make those ingress and service-routing choices visible as Kubernetes resources instead of scattering them across annotations, cloud load-balancer settings, and proxy-specific configuration.

That matters for AI governance because routes shape who can reach a model, which hostnames map to which backend Services, how traffic is split during migrations, which teams can expose routes through a shared Gateway, and where TLS termination happens. A public chatbot, an internal coding agent, a safety-evaluation service, and a high-risk tool gateway should not all be indistinguishable at the network edge.

Governance Use

A governance-grade Gateway API record should preserve GatewayClasses, controllers, Gateways, listeners, hostnames, ports, protocols, TLS configuration, allowedRoutes settings, Route objects, parentRefs, backendRefs, filters, ReferenceGrants, namespaces, owners, status conditions, implementation conformance, and change history. For AI services, it should also identify the routed service type: public model endpoint, internal inference service, agent tool gateway, evaluation service, retrieval backend, or administrative interface.

The review question is whether the routing objects express the institution's intended exposure policy. Which namespaces may attach Routes to a shared Gateway? Which hostnames point to production model backends? Which services can be referenced across namespace boundaries? Which route changes moved traffic to a new model, new tool server, or new data-plane implementation?

Limits

Gateway API does not evaluate model behavior, authenticate users by itself, prove prompt safety, classify data, inspect generated content, or establish that a backend is trustworthy. It can define routing structure and expose policy surfaces, but enforcement depends on the implementation, adjacent policy, TLS and identity configuration, authorization, rate limiting, observability, and incident response.

It also should not be confused with a complete AI gateway product. Gateway API is a Kubernetes service-networking API. Some implementations may add traffic filters, service mesh behavior, or provider-specific controls, but those claims require implementation-specific documentation.

Source Discipline

Claims about Gateway API should cite the official Gateway API introduction, API overview, roles and personas page, ReferenceGrant page, Kubernetes documentation, and release notes or Kubernetes blog posts for support-level claims. Claims about a particular controller, cloud load balancer, service mesh, external authentication filter, or AI gateway layer should cite that implementation separately.

The evidence to keep is operational: resource manifests, controller versions, conformance profile, Gateway and Route status, listener conditions, ReferenceGrant objects, audit logs, access logs, DNS records, TLS certificates, and change approvals.

Spiralist Reading

Spiralism reads Gateway API as a ledger of permitted passage.

The route is not merely a path. It is a statement that one namespace may expose, another namespace may be reached, a hostname may speak for a service, and traffic may be admitted into a machine system. The moral work is to keep that statement legible.

Sources

Return to Wiki