Kubernetes Gateway API Explained: Routes, Gateways, and Ingress

Kubernetes Gateway API is a set of resources for describing how traffic enters a cluster and reaches services. It gives platform teams, application developers, and network operators a more structured way to share control over listeners and routes than a single, controller-specific Ingress configuration. This guide explains the resource model, how it relates to Ingress and load balancing, and how to validate a basic HTTP route.

What Is Kubernetes Gateway API?

Gateway API is a Kubernetes project that defines a family of resources for modeling service networking. A controller watches those resources and configures a data plane, such as a cloud load balancer, reverse proxy, or Kubernetes networking implementation. The API describes the intended traffic behavior; it does not itself forward packets or install a controller.

The main HTTP resources separate infrastructure from application routing. A GatewayClass identifies a controller and the kind of gateways it manages. A Gateway requests listeners such as HTTP or HTTPS on a particular address. An HTTPRoute describes how matching requests should be directed to backends, usually Kubernetes Services. The Gateway API documentation describes the resource model and supported protocol-specific routes.

Gateway API is not simply a newer spelling for an Ingress object. It uses related concepts, but its role-oriented resource hierarchy makes the ownership of infrastructure, listeners, and application routes more explicit. The API is extensible, and implementations advertise support for particular capabilities; a manifest using an optional feature is not guaranteed to work with every controller.

The Problem Gateway API Solves

The Kubernetes Ingress API provides a common way to describe HTTP routing, but it has a limited set of portable fields. Operators often rely on annotations or controller-specific configuration for features such as advanced rewrites, timeouts, traffic splitting, or TLS behavior. Moving an application between controllers can therefore mean translating configuration that looked portable but was not.

Ingress also combines responsibilities that different teams may own. A platform team may operate the public address and TLS listener, while application teams need permission to define host and path rules for their own services. A single resource makes that boundary harder to express consistently, especially when many teams share one cluster edge.

The Kubernetes Ingress documentation notes that the Ingress API is frozen and recommends Gateway API for future development. Frozen does not mean removed: existing Ingress resources and controllers continue to work. Gateway API addresses the model’s limits with separate resources, explicit attachment rules, and a broader set of route types.

How Gateway API Routes Traffic

A typical HTTP request passes through several layers:

client
  -> address exposed by a Gateway
  -> listener selected by protocol, port, and hostname
  -> attached HTTPRoute matches host, path, or headers
  -> backend reference selects a Kubernetes Service
  -> Service sends traffic to ready workload endpoints

The controller identified by the GatewayClass reconciles the desired resources into its implementation. It may provision an external load balancer, configure a proxy, assign an address, or perform another implementation-specific action. The Gateway’s status reports whether the controller accepted and programmed it; a resource being stored in the Kubernetes API alone does not prove that traffic is flowing.

Listeners determine what a Gateway accepts, including protocol, port, optional hostname, and which namespaces may attach routes. An HTTPRoute refers to a Gateway through parentRefs. Its rules can match request attributes such as hostnames, paths, and headers, then forward to one or more backend references. Routes and Gateways can live in different namespaces when listener policy permits attachment. Cross-namespace references to backend objects require the appropriate grant rather than being implicitly allowed.

This separates control of the shared edge from control of application routing. The Gateway owner can expose a carefully defined listener and restrict which namespaces may use it. An application team can then own an HTTPRoute for its service without editing the shared infrastructure object. Status conditions make attachment and reference errors visible to both sides.

Gateway API also defines routes for protocols beyond HTTP, including gRPC and other transport patterns. The available resources and maturity of particular features depend on the installed API version and controller. Its design is compatible with HTTP’s request semantics; the HTTP Semantics specification defines concepts such as methods, fields, and status codes that an HTTP-aware proxy can inspect.

Gateway API primarily describes north-south traffic: requests arriving at a cluster edge and being routed to a service. It does not replace the CNI plugin, pod-to-pod routing, or the Kubernetes Service abstraction. The controller translates a route into its own data-plane configuration, while the Service and cluster network still provide the path to ready endpoints. Keep those responsibilities distinct when tracing a failed request: a route can be accepted while the backend is unhealthy or unreachable.

TLS is another boundary to design explicitly. A listener can request HTTPS behavior and refer to certificate material, but certificate attachment and secret handling must follow the implementation’s supported rules. Decide where TLS terminates, how traffic is protected after termination, who may attach a route to a public listener, and which hostnames it may claim. A successful HTTPRoute match should not be treated as an access-control policy for the application itself.

These are API model differences, not a guarantee that one implementation is faster or more reliable. Compare the exact features, conformance claims, operational behavior, and lifecycle of the controllers you plan to run.

Gateway API Components and Key Concepts

• GatewayClass: A cluster-scoped resource associated with a controller. It represents a class of managed Gateways; the controller name and optional parameters depend on the implementation.
• Gateway: A namespaced request for network infrastructure and listeners. Its status can report addresses, accepted configuration, and whether the controller programmed it.
• Listener: A protocol and port on a Gateway, optionally constrained by hostname and allowed route namespaces. Separate listeners can provide distinct policies on one Gateway.
• Route: A protocol-specific resource that attaches to a Gateway and describes matches and actions. HTTPRoute is the common choice for web traffic; other route kinds cover different protocols.
• Backend reference: A destination, often a Service and port, used by a route rule. A missing service, unsupported kind, or unauthorized cross-namespace reference can prevent a route from resolving.
• ReferenceGrant: A resource that explicitly permits certain cross-namespace references. It helps keep namespace boundaries meaningful instead of making every route able to target arbitrary objects.

Controllers publish supported features and conformance information, but conformance does not make all optional features universal. Check the controller’s documentation and observed status conditions before depending on a particular filter, route kind, or policy attachment.

Real-World Uses

A shared cluster edge can use one Gateway for public HTTP traffic while teams maintain separate routes for their applications. Listener policies can constrain the hosts and namespaces that attach, while application teams change path matches and service backends through their own resources.

Gateway API is also useful when a platform needs to standardize a boundary between teams, move away from a large collection of Ingress annotations, or express routes through different implementations. A gradual adoption can leave existing Ingress resources serving traffic while new applications use Gateway API. The container networking guide explains the pod network and Service layers that sit behind these edge-routing resources, while the L4 and L7 load balancing guide distinguishes transport forwarding from HTTP-aware routing.

For service-to-service traffic, a service mesh may address a different layer of the problem. Compare the scope with the Istio service mesh implementation guide before treating an ingress Gateway as a replacement for east-west traffic policy.

Getting Started: Define an HTTP Gateway and Route

Gateway API resources are reconciled only when compatible CRDs and a controller are installed. Follow the controller’s installation instructions, then confirm it has created a GatewayClass. Installing CRDs alone makes the resource kinds available to Kubernetes but does not create a data plane or provide an address. This example assumes a web namespace, a Service named web on port 8080, and a controller-managed class named shared-edge.

Plan an Ingress migration

Start by listing existing Ingress resources, their classes, TLS secrets, annotations, and any controller-specific configuration. Translate the intended behavior rather than copying annotations: the shared listener may belong in a Gateway, while host and path rules usually belong in one or more HTTPRoutes. Confirm that the chosen controller supports every required match, filter, TLS option, and policy before moving production traffic.

There is no universal one-step conversion that preserves every controller’s behavior. Some fields map directly, while annotation features may need a Gateway API filter, a policy supported by the implementation, or a different design. Test the route and its status in a non-production namespace first. For a low-risk rollout, migrate one hostname or service at a time, validate DNS and certificate behavior, monitor the actual data plane, and keep the old Ingress available until rollback is no longer needed. The API resource being accepted is necessary but not sufficient evidence that users can reach the application.

Check the API resources, class, and backend before applying the manifest:

kubectl api-resources --api-group=gateway.networking.k8s.io
kubectl get gatewayclass
kubectl get service web -n web

Create a Gateway with an HTTP listener and an HTTPRoute that sends requests for app.example.com to the existing Service:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: edge
  namespace: web
spec:
  gatewayClassName: shared-edge
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
  namespace: web
spec:
  parentRefs:
    - name: edge
      sectionName: http
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web
          port: 8080

Save the resources as gateway.yaml and apply them:

kubectl apply -f gateway.yaml
kubectl get gateway,httproute -n web
kubectl describe gateway edge -n web
kubectl describe httproute web -n web

Inspect the status conditions and events. The Gateway should be accepted and programmed, and the route should be accepted with its references resolved. If the Gateway has no address, check controller logs, the class name, and the controller’s address-provisioning requirements. If the route is not attached, verify the listener’s allowed routes, the route’s parentRefs and hostname, and whether its backend Service and port exist.

When an address has been assigned, test the HTTP listener. In PowerShell, replace the host if your route uses a different hostname:

$address = kubectl get gateway edge -n web -o jsonpath='{.status.addresses[0].value}'
curl.exe -H "Host: app.example.com" "http://$address/"

For production, add TLS according to the controller’s supported listener and certificate configuration, publish DNS for the Gateway address, and review which namespaces can attach routes. Use the controller’s feature documentation and conformance profile before relying on advanced routing behavior.

Common Misconceptions

“Gateway API is a load balancer.” It is an API model. A controller and data plane must implement the resources and provide the actual forwarding path.

“Every Gateway API controller supports every feature.” Implementations differ. Core features have defined conformance profiles, but optional capabilities and extensions must be checked against the chosen controller.

“Ingress is obsolete and must be deleted.” The Ingress API is frozen, not removed. Existing deployments can continue using it. Migration should be based on needed capabilities and a tested controller plan, not on an assumption that old resources have stopped working.

Related Articles

• Container networking explained
• L4 vs. L7 load balancing
• Kubernetes architecture explained
• Istio service mesh implementation guide

Changelog

• 2026-09-30: First publication.