kubernetes

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.

By Shubhankar Tripathi • • 5 min read

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.

Resource

Primary responsibility

Typical owner

GatewayClass

Defines a class of Gateways and identifies the controller that implements it.

Infrastructure provider / cluster operator

Gateway

Represents an instance of traffic-handling infrastructure and its listeners.

Cluster operator / platform team

HTTPRoute

Defines HTTP routing rules from a Gateway to backend Services.

Application developer / application team

GRPCRoute

Defines gRPC-aware routing rules.

Application developer / application team

ReferenceGrant

Explicitly permits certain cross-namespace references.

Namespace/resource owner


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:

Infrastructure Provider
        |
        v
  GatewayClass
        |
        v
      Gateway
        |
        v
  +----+----------------+
  |                     |
HTTPRoute             GRPCRoute
  |                     |
  +----------+----------+
              |
              v
        Kubernetes Service
              |
              v
            Pods


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.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-gateway-class
spec:
  controllerName: example.net/gateway-controller


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.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same


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.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
spec:
  parentRefs:
    - name: web-gateway
  hostnames:
    - "www.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web-service
          port: 80


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.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-gateway-class
spec:
  controllerName: example.net/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: v1
kind: Service
metadata:
  name: web-service
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 8080
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
spec:
  parentRefs:
    - name: web-gateway
  hostnames:
    - "www.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web-service
          port: 80


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

Capability

Service

Gateway API

Stable backend abstraction

Core capability

Uses Services as common backends

Internal service discovery

Yes

Not its primary purpose

HTTP host/path routing

No

Yes, through HTTPRoute

TLS listener configuration

Limited at Service level

Yes, through Gateway listeners and Route resources

Traffic routing policy

Basic service forwarding

Advanced, protocol-aware routing

External traffic entry point

LoadBalancer can provide one

Gateway represents traffic-handling infrastructure

Role separation

Limited

Core design principle


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.

Area

Ingress

Gateway API

Main resource model

Ingress + IngressClass

GatewayClass + Gateway + Route resources

Role separation

Less explicit

Core design principle

Advanced routing

Often implementation-specific annotations/extensions

Expressed through standardized Route fields and filters where supported

Protocol model

Primarily HTTP/HTTPS ingress

Protocol-specific Routes and listeners

Multi-team delegation

Possible, but varies by implementation

Explicit attachment and namespace/reference controls

Migration position

Mature and widely deployed

Modern API model for advanced traffic management


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.

Role

Typical responsibility

Infrastructure Provider

Provides or operates the underlying networking/load-balancing infrastructure and GatewayClass implementations.

Cluster Operator

Creates and manages Gateways, listeners, policies and platform-level networking behavior.

Application Developer

Creates Routes that describe how application traffic reaches Services.

Application/Namespace Owner

Controls resources such as Services and, where required, ReferenceGrants in the namespace.


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.

Gateway
  |
  +-- HTTPRoute: shop.example.com
  |       |
  |       +-- / -> shop-service
  |
  +-- HTTPRoute: api.example.com
  |       |
  |       +-- /v1 -> api-v1-service
  |       +-- /v2 -> api-v2-service
  |
  +-- HTTPRoute: admin.example.com
          |
          +-- / -> admin-service


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.

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api
        headers:
          - name: x-environment
            value: canary
    backendRefs:
      - name: api-canary
        port: 80


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.

rules:
  - backendRefs:
      - name: web-v1
        port: 80
        weight: 90
      - name: web-v2
        port: 80
        weight: 10


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.

listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
        - name: example-tls


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.

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-web-route
  namespace: backend
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: frontend
  to:
    - group: ""
      kind: Service


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.

rules:
  - matches:
      - method:
          service: example.UserService
          method: GetUser
    backendRefs:
      - name: user-service
        port: 50051


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

Route

Protocol / purpose

Current Gateway API status

HTTPRoute

HTTP and HTTPS routing

Standard Channel / GA

GRPCRoute

gRPC routing

Standard Channel / GA

TLSRoute

TLS routing, including SNI-based routing

Standard Channel / GA

TCPRoute

TCP stream routing

Experimental Channel

UDPRoute

UDP traffic routing

Experimental Channel


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.

kubectl get gatewayclass
kubectl get gateway
kubectl get httproute


21. Troubleshooting Gateway API

Step 1: Check GatewayClass

kubectl get gatewayclass
kubectl describe gatewayclass <name>


Confirm that the GatewayClass exists and that its controller is available.

Step 2: Check Gateway Status

kubectl get gateway <gateway-name> -o yaml
kubectl describe gateway <gateway-name>


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

kubectl get httproute <route-name> -o yaml
kubectl describe httproute <route-name>


Check whether the Route is accepted by the Gateway and whether its backend references are resolved.

Step 4: Check Services and EndpointSlices

kubectl get svc
kubectl get 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

kubectl get pods -A
kubectl logs -n <gateway-namespace> <gateway-controller-pod>


Controller logs are implementation-specific but can reveal configuration, listener, backend or programming errors.

22. Common Gateway API Problems

Problem

Likely cause

What to check

Gateway has no external address

Gateway implementation is not installed, not configured, or cannot provision infrastructure.

GatewayClass, controller status, implementation logs, cloud/load-balancer resources.

HTTPRoute is not accepted

Gateway attachment rules do not permit the Route or parent reference is incorrect.

parentRefs, listener allowedRoutes, Route status.

Backend reference is unresolved

Service/port does not exist or cross-namespace access is not permitted.

Service name/port, namespace and ReferenceGrant.

Traffic reaches Gateway but not application

Backend Service, endpoints, NetworkPolicy or application listener issue.

Service, EndpointSlices, Pod readiness and network policies.

TLS listener is not programmed

Certificate reference or implementation-specific TLS configuration is invalid.

Gateway listener status, Secret and ReferenceGrant where applicable.

Route works for one host but not another

Hostname or listener matching is incorrect.

Gateway listeners, Route hostnames and HTTPRoute status.


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.

Use case

Typical choice

Simple external TCP service

LoadBalancer Service may be sufficient.

One public HTTP application with simple exposure

LoadBalancer Service or Gateway, depending on platform architecture.

Many HTTP applications sharing one entry point

Gateway + HTTPRoutes is a strong fit.

Host/path-based routing

Gateway + HTTPRoute.

gRPC-aware routing

Gateway + GRPCRoute where supported.

Advanced multi-team traffic management

Gateway API is designed for this role-oriented model.


24. Gateway API and Service: They Work Together

Gateway API should not be viewed as a replacement for Services. The common pattern is:

Internet / Client
      |
      v
  Gateway
      |
    HTTPRoute
      |
      v
    Service
      |
      v
  EndpointSlice
      |
      v
      Pods


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.

                Platform Team
                      |
                GatewayClass
                      |
                    Gateway
                  /    |                      /     |                      v      v       v
          HTTPRoute HTTPRoute HTTPRoute
            |         |          |
            v         v          v
          Service   Service    Service
            |         |          |
            Pods      Pods       Pods

Application teams own Routes.
Platform team controls Gateway infrastructure.
Namespace owners control their Services and
cross-namespace trust through ReferenceGrant.


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.

# Check available GatewayClasses
kubectl get gatewayclass

# Create an example application
kubectl create deployment web --image=nginx:1.27 --replicas=3

# Create the backend Service
kubectl expose deployment web --name=web-service --port=80 --target-port=80

# Apply a Gateway and HTTPRoute after replacing
# gatewayClassName with the class available in your cluster.


After applying the Gateway and Route resources, inspect their status and test the Gateway address exposed by your implementation.

kubectl get gateway
kubectl get httproute
kubectl describe gateway web-gateway
kubectl describe httproute web-route
kubectl get svc web-service
kubectl get endpointslices


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/