The Kubernetes Gateway API Explained

By Kokil Thapa | Last reviewed: September 2026

The Kubernetes Gateway API explained starts with a simple problem: classic Ingress was never enough for real platforms. One annotation soup, one controller dialect, and no clean split between platform teams and application teams. If you run microservices behind a load balancer today, you need a model that separates infrastructure from routing rules. That is what Gateway API delivers — a role-oriented, extensible successor to Ingress, now stable enough for production in 2026. This guide walks through the resources, a working HTTPRoute, how it compares to Ingress, and the mistakes I see on clusters that also host Laravel API workloads.

What is the Kubernetes Gateway API and why replace Ingress?

Ingress solved 2015-era HTTP routing. Platform teams pasted vendor-specific annotations onto one object. Application teams could not safely attach routes without touching shared infrastructure. Gateway API fixes that with three layers and clear ownership boundaries.

The model comes from the Kubernetes SIG Network community. It is not a single product — it is a set of CRDs that any conformant controller can implement. Popular implementations include Envoy Gateway, Istio, Cilium, Kong Gateway Operator, and Traefik. Your choice of controller determines which GatewayClass names you reference in manifests.

If you already understand the classic stack, read Kubernetes Ingress controllers explained first. Gateway API does not delete Ingress overnight. Many clusters run both during migration. The win is expressiveness: header-based routing, traffic splitting, cross-namespace references with ReferenceGrant, and TLS modes that Ingress never standardised.

Core resource families include:

• GatewayClass — names the controller implementation, like istio or envoy.
• Gateway — defines listeners (port, protocol, hostname, TLS).
• HTTPRoute, GRPCRoute, TCPRoute, TLSRoute, UDPRoute — attach rules to Gateway listeners.
• ReferenceGrant — allows cross-namespace backend or Gateway references.

That separation mirrors how real organisations work. Platform engineers install the controller once. Cluster operators create Gateways per environment. Product teams publish HTTPRoutes in their own namespaces. No shared Ingress object with forty annotation keys.

How do GatewayClass, Gateway, and HTTPRoute work together?

Think of traffic entering from the north-south edge. A cloud load balancer or MetalLB IP hits the Gateway listener. The controller matches host and path against HTTPRoute rules. Matching requests forward to Kubernetes Services and then Pods.

The binding is explicit. An HTTPRoute declares parentRefs pointing at a Gateway and listener section. The Gateway does not embed backend lists — routes attach from any allowed namespace.

GatewayClass — pick your controller once

GatewayClass is cluster-scoped. The controller vendor ships it, or you create one that matches their documentation. Example for a generic Envoy-based install:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

Only controllers whose controllerName matches will reconcile Gateways using this class. Pin one class per environment so staging never accidentally points at a production controller profile.

Gateway — listeners and TLS termination

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: infra
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: api.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - name: api-tls
            kind: Secret
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"

Listeners are typed. HTTPS listeners accept HTTPRoute attachments. TCP listeners accept TCPRoute. The allowedRoutes field is your guardrail — restrict which namespaces may attach routes.

HTTPRoute — application-level routing

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: orders-api
  namespace: commerce
spec:
  parentRefs:
    - name: public-gateway
      namespace: infra
      sectionName: https
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/orders
      backendRefs:
        - name: orders-svc
          port: 8080
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Forwarded-Proto
                value: https

Filters replace many Ingress annotations: redirects, header rewrites, URL rewrites, and request mirrors. For gRPC backends, swap HTTPRoute for GRPCRoute with the same parentRef pattern.

Status fields matter in operations. Run kubectl get gateway,httproute -A and inspect .status.parents on routes. A route showing Accepted=False usually means a hostname mismatch, a missing ReferenceGrant, or a listener that disallows the route namespace. That beats debugging a silent 404 from a mis-annotated Ingress.

How do you install and configure the Kubernetes Gateway API?

Installation has two parts: the CRDs (the API surface) and a controller (the data plane). Most teams install CRDs from the official release bundle, then deploy a controller Helm chart.

Step 1 — Install Gateway API CRDs

1. Pick a release channel. Standard channel CRDs are appropriate for most clusters in 2026.
2. Apply the manifest bundle published by SIG Network.
3. Verify CRDs exist with kubectl get crd | grep gateway.networking.k8s.io.

kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.2.0" | kubectl apply -f -

Check your controller docs for the minimum Gateway API version they support. Mismatch between CRD version and controller version is a common first-day failure.

Step 2 — Deploy a conformant controller

Envoy Gateway is a popular open-source choice with a dedicated data plane. Istio and Cilium fit if you already run those stacks. For teams comparing edge proxies, see Kong API Gateway guide and Traefik as an API Gateway — both have Gateway API conformance paths alongside classic Ingress modes.

After Helm install, confirm the controller created a GatewayClass:

kubectl get gatewayclass
kubectl describe gatewayclass envoy-gateway

Step 3 — Wire external access

Gateway status should expose an address. On cloud clusters that is often a managed LB hostname. On bare metal you may pair Gateway API with MetalLB or kube-vip — see Kubernetes on bare metal with MetalLB.

Step 4 — Enable cross-namespace routes with ReferenceGrant

When an HTTPRoute in namespace commerce references a Service in namespace payments, the payments namespace needs a ReferenceGrant:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-commerce-routes
  namespace: payments
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: commerce
  to:
    - group: ""
      kind: Service

Skip ReferenceGrant and the route stays rejected — by design. This is safer than Ingress backends that silently crossed namespaces through ambiguous annotation conventions.

Validate YAML structure with a JSON formatter when converting OpenAPI examples or controller output during debugging.

How does Gateway API compare to Ingress and service meshes?

Gateway API is not a service mesh replacement. It focuses on north-south entry. East-west traffic still belongs to mesh sidecars, Cilium network policies, or plain ClusterIP Services. Read Kubernetes networking model explained for the full picture and network policies for pod-level firewalls.

When should you stay on Ingress? Small clusters, one team, one controller, and no cross-namespace complexity — Ingress still works. When should you adopt Gateway API? Multiple teams, canary releases, gRPC, or you are standardising edge config across environments managed by GitOps tools like Argo CD GitOps for Kubernetes.

Compared to standalone API gateways at the edge, Gateway API keeps routing declarative inside the cluster. For a broader comparison of edge products, see API gateways for microservices and Kong vs Traefik vs AWS API Gateway.

What production patterns and mistakes should you watch for?

On clusters that host booking systems and APIs — like the Laravel + Livewire stack on Adventure Third Pole Trek — edge routing errors show up as intermittent 502s, not application exceptions. Gateway API makes status visible, but you still need discipline.

Canary and weighted backends

HTTPRoute supports weighted backendRefs for gradual rollouts:

backendRefs:
  - name: orders-v2
    port: 8080
    weight: 10
  - name: orders-v1
    port: 8080
    weight: 90

Pair this with horizontal pod autoscaling on both Deployments. Weights shift traffic before you scale down the old version.

TLS and certificate rotation

Prefer cert-manager Certificate resources referenced from Gateway TLS blocks. Rotate secrets before expiry; controllers hot-reload most data planes. Terminate TLS at the Gateway for north-south traffic unless compliance demands end-to-end encryption to Pods.

Observability hooks

Export controller metrics and access logs from the data plane — Envoy, Traefik, or Cilium each expose Prometheus endpoints. Correlate 5xx spikes with route attachment changes. When debugging Pod crashes behind bad routes, start with debugging CrashLoopBackOff and trace backward to Service port mismatches.

GitOps and tenancy

Store Gateway objects in an infra repo and HTTPRoutes in application repos. Argo CD ApplicationSets can template routes per team namespace. Restrict who may create GatewayClass objects — that is cluster-admin territory.

For Laravel services moving into Kubernetes, combine this edge layer with Kubernetes for Laravel getting started and solid API development practices. The Gateway does not replace application auth — use Sanctum or OAuth at the app layer and treat the Gateway as transport routing.

Official references worth bookmarking: the Gateway API SIG documentation for CRD specs and conformance profiles, and the Kubernetes Gateway concept page for core behaviour. The implementation compatibility table lists which controllers support GRPCRoute, TLSRoute, and extended filters before you commit to one vendor.

If you manage the full stack — cluster, CI, and app deploys — Linux system administration and support and maintenance cover the operational side when Gateway upgrades land in your change window. For end-to-end request tracing from kube-apiserver to Pod, read a Kubernetes API request end-to-end flow.

Key Takeaways

• Gateway API splits edge config into GatewayClass, Gateway, and route objects with clear team ownership.
• HTTPRoute parentRefs bind routes to listeners; always inspect .status.parents when routes fail.
• Install matching CRD and controller versions, then expose Gateway addresses via cloud LB or MetalLB.
• Use ReferenceGrant for cross-namespace Service backends — rejected routes are safer than silent misroutes.
• Gateway API handles north-south entry; pair it with network policies or a mesh for east-west security.
• Migrate incrementally: run Gateway API beside Ingress until every hostname moves to HTTPRoute.

People Also Ask

Is Gateway API stable for production in 2026?

Yes for core types — GatewayClass, Gateway, and HTTPRoute reached GA in the v1 API group. Controllers differ in advanced feature support, so check the conformance table for your vendor before relying on GRPCRoute or TCPRoute in production.

Do I need to remove Ingress to use Gateway API?

No. Both can coexist on the same cluster during migration. Point new hostnames at Gateway listeners and retire Ingress objects one service at a time. Controllers often ship dual-mode reconciliation for transitional clusters.

Which controller should I choose?

Pick the controller you already operate. Istio if you run a mesh, Cilium if you use it for networking policies, Envoy Gateway for a dedicated lightweight data plane, or Kong/Traefik if those already front your APIs. Conformance level matters more than brand name.

How is Gateway API different from a service mesh?

Gateway API routes external traffic into the cluster. A service mesh manages east-west traffic between Pods with mTLS and fine-grained policy. They complement each other — many Istio deployments use Gateway API for ingress and mesh rules internally.

Deploy Gateway API with confidence

The Kubernetes Gateway API explained above is the model modern platforms standardise on: typed routes, explicit permissions, and controller portability without annotation dialects. Start with one Gateway, one HTTPRoute, and a smoke-test Service — then expand to weighted canaries and cross-namespace ReferenceGrants as your teams grow. Need help designing edge routing for a Laravel API or multi-tenant platform? Contact us or explore custom software development and recent portfolio work on production web systems.