Kubernetes Gateway API: The Complete 2026 Guide

The Kubernetes Ingress resource served the community well for nearly a decade, but its limitations became increasingly painful as organizations scaled beyond simple HTTP routing. Annotations proliferated into an unmanageable mess of controller-specific configuration. TLS termination required vendor-specific workarounds. Anything beyond path-based routing meant reaching for custom resources that looked nothing like the Ingress spec they were supposed to extend. The Kubernetes Gateway API was designed from the ground up to solve these problems, and in 2026, it has arrived as the definitive standard for traffic management in Kubernetes.

This guide covers everything a platform engineer, cluster operator, or application developer needs to understand about the Gateway API: its resource model and design philosophy, the release history from v1.0 through v1.4, every major implementation and their trade-offs, migration strategies from legacy Ingress, advanced routing patterns, traffic management for canary deployments, the GAMMA initiative that extends Gateway API into service mesh territory, multi-cluster routing, TLS automation with cert-manager, and performance characteristics across implementations.

The Problems with Kubernetes Ingress

Before diving into the Gateway API, it is worth understanding exactly why the Ingress resource needed a successor. The Ingress API, introduced in Kubernetes 1.1 as a beta resource and promoted to GA in 1.19, was designed to handle a narrow use case: route external HTTP traffic to Services based on hostname and path. That simplicity was both its strength and its fatal flaw.

Annotation Sprawl

Ingress controllers like NGINX, Traefik, and HAProxy each extended the base Ingress spec through annotations. Need rate limiting? Add nginx.ingress.kubernetes.io/limit-rps. Need WebSocket support? Add nginx.ingress.kubernetes.io/proxy-read-timeout. Need custom headers? Another annotation. The result was that a production Ingress resource might carry twenty or thirty annotations, none of which were portable between controllers. Moving from NGINX Ingress to Traefik meant rewriting every annotation, and there was no guarantee of feature parity.

Single Resource, Multiple Concerns

Ingress conflated infrastructure provisioning (load balancer configuration, TLS certificate management) with application routing (path matching, backend selection). A cluster operator responsible for infrastructure and an application developer responsible for routing rules both had to modify the same resource. In organizations with strict RBAC policies, this created constant friction. Either developers had too much access to infrastructure configuration, or operators became bottlenecks for every routing change.

Protocol Limitations

Ingress was designed for HTTP and HTTPS traffic. Full stop. Organizations running gRPC services, TCP-based databases, or UDP workloads like DNS or game servers had to use entirely separate mechanisms. LoadBalancer Services, custom CRDs from Ingress controllers, or bespoke proxy configurations filled the gap, but none of them offered a unified experience.

No Standard for Traffic Splitting

Canary deployments, blue-green rollouts, and A/B testing all require some form of weighted traffic splitting. Ingress had no native support for this. Every controller implemented it differently: NGINX used annotations like nginx.ingress.kubernetes.io/canary-weight, Istio used VirtualService, and Traefik used its own IngressRoute CRD. There was no portable way to express "send 10% of traffic to the new version."

Gateway API: Design Philosophy and Architecture

The Kubernetes Gateway API was developed by the SIG Network community as a direct response to these limitations. Rather than patching the Ingress spec, the project started with a clean-slate design guided by several core principles.

Role-Oriented Design

The Gateway API explicitly models three personas, each with distinct responsibilities and corresponding Kubernetes resources:

Infrastructure Provider manages the GatewayClass resource. This role is typically filled by cloud providers, infrastructure vendors, or the team responsible for installing and configuring the Gateway controller. The GatewayClass defines the type of gateway infrastructure available, analogous to a StorageClass in the storage subsystem. An infrastructure provider might offer multiple GatewayClasses such as "internal-gateway" for private traffic and "external-gateway" for public-facing services.

Cluster Operator manages the Gateway resource. This role belongs to the platform engineering or infrastructure team responsible for defining how traffic enters the cluster. The Gateway specifies listeners with protocol, port, hostname, and TLS configuration. The cluster operator provisions the actual infrastructure (load balancers, IP addresses) without needing to know the specific routing rules that application teams will attach.

Application Developer manages Route resources (HTTPRoute, GRPCRoute, and others). This role belongs to the teams that own individual services. Developers define how traffic matching specific criteria should be routed to their backends, without needing access to infrastructure configuration.

Expressive and Extensible

Instead of annotations, the Gateway API uses typed fields in structured resources. Header matching, query parameter routing, request mirroring, URL rewriting, and request redirects are all first-class API fields. Where the core API does not cover a use case, the policy attachment model allows implementations to define their own policies (rate limiting, authentication, circuit breaking) that attach to Gateway API resources without modifying them.

Portable by Default

The Gateway API defines conformance profiles and a comprehensive conformance test suite. Implementations must pass these tests to claim conformance at a given level. This means that an HTTPRoute written for Envoy Gateway will work with Istio, Cilium, or NGINX Gateway Fabric without modification, as long as you stay within the conformance-tested feature set.

Gateway API Release History

Understanding the release cadence and what shipped in each version is critical for planning adoption and upgrades.

Standard vs Experimental Channels

The Gateway API uses a two-channel release model that is important to understand before adopting any feature:

Standard Channel contains resources and fields that have reached GA-level stability. These are covered by the Kubernetes deprecation policy and will not be removed or changed in breaking ways. As of v1.4, the Standard channel includes GatewayClass, Gateway, HTTPRoute, GRPCRoute, ReferenceGrant, BackendTLSPolicy, HTTPRoute timeouts, gateway infrastructure labels, and named route rules.

Experimental Channel contains everything in Standard plus new features that are still being refined. Experimental features may change or be removed entirely. The project publishes monthly experimental channel releases tagged as monthly-YYYY-MM, allowing teams to test cutting-edge features without waiting for the next Standard release. Experimental features include HTTPRoute retries, TCPRoute, TLSRoute, UDPRoute, BackendLBPolicy for session persistence and load balancing configuration, and several others.

The project targets a four-month cadence for Standard channel releases. This means that experimental features that prove stable can graduate to GA within one or two release cycles.

The Resource Model in Depth

The Gateway API resource model is the foundation of everything. Understanding each resource, its fields, and how resources reference each other is essential for effective use.

GatewayClass

GatewayClass is a cluster-scoped resource that defines a class of Gateways. It is the entry point for the Gateway API and is typically managed by the infrastructure provider or the team that installs the controller.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: custom-proxy-config
    namespace: envoy-gateway-system

The controllerName field identifies which controller should implement Gateways of this class. The optional parametersRef allows the infrastructure provider to reference implementation-specific configuration without polluting the GatewayClass spec itself. Multiple GatewayClasses can coexist in a cluster, allowing different teams or environments to use different gateway implementations or configurations.

Gateway

The Gateway resource represents a specific instance of gateway infrastructure. It is namespace-scoped and typically managed by the cluster operator. A Gateway defines listeners that specify which traffic the gateway should accept.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: gateway-system
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: '*.example.com'
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-example-com
            namespace: cert-system
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: 'true'
    - name: http
      protocol: HTTP
      port: 80
      hostname: '*.example.com'
      allowedRoutes:
        namespaces:
          from: Same

Several important design decisions are visible in this example. The allowedRoutes field controls which namespaces can attach Routes to this Gateway listener. This is the mechanism that enables multi-tenant isolation: the cluster operator can restrict which teams can expose services through a specific gateway. The from: Selector option with matchLabels means only namespaces with the label gateway-access: "true" can attach routes, while from: Same restricts to routes in the same namespace as the Gateway.

TLS configuration lives on the Gateway listener, not on individual routes. This clean separation means the infrastructure team manages certificates while application teams manage routing. The certificateRefs can reference Secrets in other namespaces, which is where ReferenceGrant comes into play.

ReferenceGrant

ReferenceGrant is a namespace-scoped resource that explicitly allows cross-namespace references. This is a security boundary: without a ReferenceGrant, a Gateway in namespace A cannot reference a Secret in namespace B.

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-gateway-cert-access
  namespace: cert-system
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: gateway-system
  to:
    - group: ''
      kind: Secret

This pattern ensures that the team owning the cert-system namespace must explicitly consent to having their Secrets referenced by Gateways in gateway-system. The design prevents accidental or unauthorized cross-namespace access.

HTTPRoute

HTTPRoute is the workhorse of the Gateway API. It defines HTTP routing rules that attach to Gateway listeners.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-routes
  namespace: app-team
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - 'app.example.com'
  rules:
    - name: api-routes
      matches:
        - path:
            type: PathPrefix
            value: /api/v2
          headers:
            - name: X-Api-Version
              value: '2'
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Routed-By
                value: gateway-api
      backendRefs:
        - name: api-v2
          port: 8080
          weight: 90
        - name: api-v3
          port: 8080
          weight: 10
      timeouts:
        request: 30s
        backendRequest: 10s
    - name: static-assets
      matches:
        - path:
            type: PathPrefix
            value: /static
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /assets
      backendRefs:
        - name: cdn-origin
          port: 8080

This single HTTPRoute demonstrates multiple capabilities that would require numerous annotations in Ingress: path and header matching, request header modification, weighted traffic splitting between backends, configurable timeouts for both client-facing requests and backend requests, and URL path rewriting. Every field is typed, validated, and portable across implementations.

The parentRefs field with sectionName allows the route to attach to a specific listener on the Gateway. The timeouts block, graduated to Standard in v1.2, supports two distinct timeout types: request covers the total time from client request to response delivery, while backendRequest covers a single attempt from gateway to backend.

GRPCRoute

GRPCRoute provides gRPC-specific routing with first-class support for gRPC service and method matching.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-routes
  namespace: app-team
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
  hostnames:
    - 'grpc.example.com'
  rules:
    - matches:
        - method:
            service: example.UserService
            method: GetUser
      backendRefs:
        - name: user-service
          port: 9090
    - matches:
        - method:
            service: example.OrderService
      backendRefs:
        - name: order-service
          port: 9090

GRPCRoute graduated to Standard in v1.1 and supports matching on gRPC service name, method name, or both. The old v1alpha2 version was removed in v1.2, so any clusters still referencing the alpha version need to update their manifests.

TCPRoute, TLSRoute, and UDPRoute

These experimental route types extend the Gateway API beyond HTTP:

TCPRoute routes raw TCP traffic to backends based on the listener it attaches to. This is used for databases, message brokers, and other TCP-based services.

TLSRoute routes TLS-encrypted traffic based on SNI (Server Name Indication) without terminating the TLS connection. This enables TLS passthrough scenarios where the backend handles its own TLS termination.

UDPRoute routes UDP traffic, useful for DNS servers, game servers, VoIP systems, and other UDP-based workloads.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: postgres-route
spec:
  parentRefs:
    - name: tcp-gateway
      sectionName: postgres
  rules:
    - backendRefs:
        - name: postgres-primary
          port: 5432

While these remain experimental, they fill a critical gap that Ingress never addressed. Organizations running mixed protocol workloads can now manage all traffic routing through a single API family.

BackendTLSPolicy

BackendTLSPolicy, graduated to Standard in v1.4, configures TLS connections from the gateway to backend services. This is essential for end-to-end encryption where backends run their own TLS.

apiVersion: gateway.networking.k8s.io/v1
kind: BackendTLSPolicy
metadata:
  name: backend-tls
spec:
  targetRefs:
    - group: ''
      kind: Service
      name: secure-backend
  validation:
    caCertificateRefs:
      - name: backend-ca-cert
        group: ''
        kind: ConfigMap
    hostname: secure-backend.internal

This resource separates backend TLS configuration from route definitions, allowing security teams to manage TLS policies independently from application routing.

Implementation Comparison

The Gateway API ecosystem includes more than 25 conformant implementations. The seven most significant in 2026 each represent a distinct architectural approach and target audience.

Envoy Gateway

Envoy Gateway is the reference implementation built by the Envoy Proxy community. It translates Gateway API resources directly into Envoy xDS configuration using a dedicated control plane. Envoy Gateway reached v1.0 in early 2024 and has since released v1.3 and v1.4 with significant feature additions.

Architecture: Envoy Gateway runs as a Kubernetes controller that watches Gateway API resources and generates Envoy proxy configurations. Each Gateway resource results in a dedicated Envoy deployment, providing strong isolation between gateways. The control plane is lightweight and purpose-built for the Gateway API, without the broader service mesh overhead of Istio.

Key strengths: Full Gateway API conformance including experimental features. Rate limiting with cost-based budgets (v1.3). API key authentication, JWT validation with local and remote JWKS sources, and fine-grained authorization rules (v1.4). Shared global rate limit buckets across all routes on a gateway. AI Gateway extensions for LLM traffic management. Fast configuration propagation, typically in the millisecond range.

Best for: Organizations that want a dedicated, lightweight Gateway API implementation without a full service mesh. Teams already using Envoy as their proxy of choice. Organizations that need advanced rate limiting and authentication built into the gateway layer.

Istio

Istio is the 800-pound gorilla of the Kubernetes networking ecosystem. Its Gateway API support is deeply integrated with its service mesh capabilities, making it the strongest choice for organizations that need both north-south ingress and east-west mesh traffic managed through a single control plane.

Architecture: Istio's istiod control plane watches both Gateway API resources and Istio-native resources (VirtualService, DestinationRule), translating them into Envoy xDS configuration. Gateway resources are implemented by Envoy proxy deployments managed by Istio. In ambient mode, ztunnel handles L4 traffic on each node while waypoint proxies (which are essentially Envoy gateways deployed per service account) handle L7 processing.

Key strengths: Full Gateway API conformance. GAMMA initiative support for mesh traffic via HTTPRoute attached to Services. Ambient mode eliminates sidecar overhead for L4 traffic. Deep integration between ingress routing and mesh policies. Mature ecosystem with extensive documentation and community support. Configuration propagation in the millisecond range.

Best for: Organizations running a service mesh that want unified north-south and east-west traffic management. Teams migrating from Istio VirtualService to Gateway API HTTPRoute. Large-scale deployments where the operational investment in Istio is justified by the breadth of features.

Cilium

Cilium takes a fundamentally different architectural approach by leveraging eBPF to push networking logic into the Linux kernel. Its Gateway API implementation is tightly integrated with Cilium's role as a CNI plugin, meaning gateway functionality comes "for free" in clusters already running Cilium for networking and security.

Architecture: Cilium uses eBPF programs for L3/L4 processing directly in the kernel, bypassing the userspace network stack entirely. For L7 processing (HTTP routing, header matching), Cilium deploys Envoy proxies but manages them through its own control plane rather than using a standalone Envoy Gateway deployment. The integration with the CNI layer means Cilium can optimize traffic paths in ways that standalone gateway implementations cannot.

Key strengths: Kernel-level L3/L4 processing with minimal latency overhead. Integrated CNI, gateway, and service mesh in a single deployment. Network policy enforcement at the kernel level. Hubble observability for real-time traffic visualization. No additional infrastructure for basic gateway functionality in Cilium-managed clusters.

Caveats: Cilium's control plane uses significantly more CPU than Istio's (benchmarks show approximately 7.5 times higher CPU consumption under load). At very high route counts, Cilium has shown scalability issues where Envoy configuration updates can fail entirely once the total configuration size exceeds certain thresholds. L7 processing still requires Envoy, so the kernel-level performance advantage applies primarily to L4 traffic.

Best for: Organizations already using Cilium as their CNI. Teams that want a unified networking stack (CNI plus gateway plus network policy) with minimal additional components. Environments where L3/L4 performance is the primary concern.

NGINX Gateway Fabric

NGINX Gateway Fabric is the official successor to the NGINX Ingress Controller OSS, which the Kubernetes community announced will be retired in March 2026. It is built from the ground up for the Gateway API, using NGINX as the data plane.

Architecture: NGINX Gateway Fabric runs a controller that watches Gateway API resources and generates NGINX configuration. Unlike the legacy NGINX Ingress Controller that relied heavily on annotations and custom templates, NGINX Gateway Fabric maps Gateway API fields directly to NGINX directives.

Key strengths: Familiar NGINX data plane for teams with existing NGINX expertise. Supports the core Gateway API types including HTTPRoute, GRPCRoute, TCPRoute, TLSRoute, and UDPRoute. Backed by F5/NGINX with commercial support options. Clear migration path from NGINX Ingress Controller.

Caveats: Configuration propagation is slower than Envoy-based implementations, taking seconds rather than milliseconds. Fewer experimental features supported compared to Envoy Gateway or Istio. The NGINX configuration model is inherently different from Envoy's xDS, which can limit how quickly new Gateway API features are adopted.

Best for: Organizations with deep NGINX expertise that want a supported migration path from NGINX Ingress Controller. Teams that need commercial support from F5/NGINX. Environments where NGINX's proven stability and performance characteristics are valued over cutting-edge feature adoption.

Contour

Contour is a Gateway API implementation maintained by the VMware/Broadcom Tanzu team, using Envoy as its data plane. It was one of the earliest adopters of the Gateway API and has maintained strong conformance throughout.

Architecture: Contour runs as a Kubernetes controller that generates Envoy xDS configuration from Gateway API resources. It supports a multi-tenant deployment model where multiple teams can share a single Envoy fleet.

Key strengths: Mature and battle-tested in production environments. Strong multi-tenant support with namespace-based isolation. Good documentation and straightforward operational model. Full Gateway API conformance.

Best for: Organizations in the VMware/Tanzu ecosystem. Teams that want a stable, well-documented Envoy-based implementation without the complexity of Istio.

Traefik

Traefik Proxy was among the first reverse proxies to adopt the Gateway API and currently supports v1.4.0 of the specification. Traefik v3 provides a simple, developer-friendly operational experience.

Architecture: Traefik watches Gateway API resources and translates them into its internal routing configuration. Unlike Envoy-based implementations, Traefik is a single binary that handles both control plane and data plane responsibilities.

Key strengths: Simple deployment model with a single binary. Strong developer experience with an integrated dashboard. Automatic service discovery. Good fit for smaller clusters and developer-centric platforms. Supports Let's Encrypt integration natively.

Best for: Small to medium clusters. Developer-centric platforms where simplicity is valued over advanced features. On-premises environments where operational simplicity is critical.

Kong Gateway

Kong Kubernetes Gateway brings enterprise-grade API management capabilities to the Gateway API. It combines Gateway API conformance with Kong's extensive plugin ecosystem.

Architecture: The Kong Ingress Controller watches Gateway API resources and configures the Kong proxy. Kong's plugin architecture allows extending gateway functionality with JWT/OAuth2 authentication, OPA/WASM extensibility, advanced rate limiting, and request transformation without modifying the Gateway API resources themselves.

Key strengths: Enterprise API management features (authentication, rate limiting, analytics). Extensive plugin ecosystem. Commercial support and enterprise licensing. Strong for organizations that need API management capabilities at the gateway layer. Millisecond-range configuration propagation.

Best for: Organizations that need full API management capabilities integrated with the Gateway API. Teams already using Kong for API gateway functionality. Enterprises that require commercial support and SLAs.

Advanced Routing Patterns

The Gateway API's routing capabilities go far beyond simple path matching. Understanding the full range of matching and filtering options is key to designing sophisticated traffic management strategies.

Header-Based Routing

Header matching enables routing decisions based on HTTP request headers. This is useful for API versioning, A/B testing, and routing traffic from specific clients to dedicated backend pools.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-routing
spec:
  parentRefs:
    - name: production-gateway
  rules:
    - matches:
        - headers:
            - name: X-Client-Tier
              value: premium
      backendRefs:
        - name: premium-pool
          port: 8080
    - matches:
        - headers:
            - name: X-Client-Tier
              value: standard
      backendRefs:
        - name: standard-pool
          port: 8080
    - backendRefs:
        - name: default-pool
          port: 8080

Header matching supports both Exact and RegularExpression match types, and multiple header matches within a single rule are ANDed together, requiring all specified headers to match.

Query Parameter Routing

Query parameter matching routes traffic based on URL query parameters. This is particularly useful for feature flags and gradual rollouts controlled by URL parameters.

rules:
  - matches:
      - queryParams:
          - name: version
            value: beta
    backendRefs:
      - name: beta-service
        port: 8080

Request Mirroring

Request mirroring (also called traffic shadowing) sends a copy of live traffic to a secondary backend without affecting the response to the client. This is invaluable for testing new versions of a service against production traffic without risk.

rules:
  - backendRefs:
      - name: production-service
        port: 8080
    filters:
      - type: RequestMirror
        requestMirror:
          backendRef:
            name: shadow-service
            port: 8080

The mirrored request is fire-and-forget: the gateway does not wait for a response from the mirror backend, and the mirror's response is discarded. This means the client always receives the response from the primary backend, and the shadow service can process real traffic patterns for validation, performance testing, or data pipeline verification.

URL Rewriting and Redirects

The Gateway API supports both URL rewriting (modifying the request before forwarding to the backend) and redirects (sending a redirect response to the client).

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /old-api
    filters:
      - type: RequestRedirect
        requestRedirect:
          scheme: https
          hostname: api.example.com
          path:
            type: ReplacePrefixMatch
            replacePrefixMatch: /v2
          statusCode: 308

Gateway API v1.4 expanded redirect support to include HTTP 303 (See Other), 307 (Temporary Redirect), and 308 (Permanent Redirect) status codes, giving operators fine-grained control over redirect behavior.

Request and Response Header Modification

Filters allow adding, setting, or removing headers on both requests and responses. This is commonly used for adding tracing headers, CORS headers, or stripping internal headers before they reach clients.

rules:
  - backendRefs:
      - name: api-service
        port: 8080
    filters:
      - type: ResponseHeaderModifier
        responseHeaderModifier:
          add:
            - name: X-Frame-Options
              value: DENY
            - name: Strict-Transport-Security
              value: 'max-age=31536000; includeSubDomains'
          remove:
            - X-Powered-By

Traffic Splitting and Canary Deployments

Native weighted traffic splitting is one of the Gateway API's most important improvements over Ingress. The weight field on backendRefs enables sophisticated deployment strategies without controller-specific annotations.

Basic Weighted Splitting

rules:
  - backendRefs:
      - name: app-v1
        port: 8080
        weight: 90
      - name: app-v2
        port: 8080
        weight: 10

Weights are relative, not absolute percentages. A split of 9:1 and 90:10 are equivalent. The gateway distributes traffic proportionally across all backends based on their weights.

Canary Deployment Strategy

A production canary deployment with the Gateway API typically follows this progression:

Phase 1 — Synthetic canary testing. Deploy the new version and route only traffic with a specific test header to it, keeping all production traffic on the stable version.

rules:
  - matches:
      - headers:
          - name: X-Canary
            value: 'true'
    backendRefs:
      - name: app-v2
        port: 8080
  - backendRefs:
      - name: app-v1
        port: 8080

Phase 2 — Percentage-based rollout. After validating with synthetic traffic, begin shifting a small percentage of production traffic to the new version.

rules:
  - backendRefs:
      - name: app-v1
        port: 8080
        weight: 95
      - name: app-v2
        port: 8080
        weight: 5

Phase 3 — Progressive increase. Monitor error rates, latency, and business metrics. Gradually increase the weight to the new version (5%, 10%, 25%, 50%, 100%) with monitoring checkpoints at each step.

Phase 4 — Instant rollback. If the new version shows problems at any point, update the weights to shift all traffic back to the stable version. Because weight changes take effect immediately (within the gateway's configuration propagation time), rollbacks happen in seconds rather than minutes.

Integration with Progressive Delivery Tools

The Gateway API's standardized traffic splitting integrates with progressive delivery tools like Flagger and Argo Rollouts. Both tools can automate the weight progression, monitoring metrics at each step and automatically rolling back if error thresholds are exceeded.

Flagger's Gateway API provider watches HTTPRoute resources and automatically adjusts weights based on Prometheus metrics, Datadog metrics, or custom webhook checks. Argo Rollouts provides similar functionality through its Gateway API traffic router plugin. This integration means organizations can combine the Gateway API's portable routing with automated canary analysis.

Backend Policies and Filters

Beyond core routing, the Gateway API's policy attachment model allows implementations to extend functionality without modifying the core API resources.

Policy Attachment Model

The policy attachment pattern works by creating separate policy resources that reference Gateway API resources through targetRef fields. This design preserves the portability of core resources while allowing implementations to add vendor-specific functionality.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: rate-limit-policy
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: api-routes
  rateLimit:
    type: Global
    global:
      rules:
        - clientSelectors:
            - headers:
                - name: X-Api-Key
                  type: Distinct
          limit:
            requests: 100
            unit: Minute

This Envoy Gateway example attaches a rate limiting policy to an HTTPRoute without modifying the HTTPRoute itself. The rate limit is implementation-specific (other implementations have their own rate limiting CRDs), but the HTTPRoute remains portable.

BackendLBPolicy

BackendLBPolicy is an experimental resource for configuring load balancing behavior and session persistence at the Service level. It enables sticky sessions, custom load balancing algorithms, and connection draining configuration.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendLBPolicy
metadata:
  name: session-persistence
spec:
  targetRefs:
    - group: ''
      kind: Service
      name: stateful-app
  sessionPersistence:
    type: Cookie
    sessionName: SERVERID
    absoluteTimeout: 1h

Authentication and Authorization

Different implementations provide authentication through their own policy resources. Envoy Gateway's SecurityPolicy supports JWT validation, API key authentication, OAuth2/OIDC integration, and external authorization. Istio's AuthorizationPolicy and RequestAuthentication resources serve similar purposes. Kong uses its plugin architecture for JWT, OAuth2, LDAP, and HMAC authentication.

The lack of a standardized authentication resource in the Gateway API itself is a deliberate design decision. Authentication requirements vary too widely across organizations for a one-size-fits-all approach. The policy attachment model provides a consistent pattern for how authentication policies attach to Gateway API resources, even though the specific policy resources are implementation-defined.

The GAMMA Initiative: Gateway API for Service Mesh

GAMMA (Gateway API for Mesh Management and Administration) extends the Gateway API beyond north-south ingress traffic to cover east-west service-to-service communication within the cluster. GAMMA support reached GA in the Standard channel as of v1.1, making it a stable foundation for mesh traffic management.

How GAMMA Works

The key insight behind GAMMA is simple: Route resources can attach not only to Gateways but also directly to Services. When an HTTPRoute attaches to a Service via parentRefs, it defines traffic management rules for any traffic directed to that Service, regardless of where that traffic originates.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews-route
spec:
  parentRefs:
    - group: ''
      kind: Service
      name: reviews
      port: 8080
  rules:
    - matches:
        - headers:
            - name: X-Test-User
              value: 'true'
      backendRefs:
        - name: reviews-v2
          port: 8080
    - backendRefs:
        - name: reviews-v1
          port: 8080

In this example, any service in the mesh that calls the reviews Service will have its traffic routed according to these rules. Requests with the X-Test-User header go to reviews-v2, and all other traffic goes to reviews-v1. This enables canary deployments, traffic splitting, and sophisticated routing for mesh traffic using the same API resources used for ingress traffic.

Mesh Conformance Profile

The Gateway API defines a Mesh conformance profile that implementations must pass to claim GAMMA support. As of early 2026, three implementations are conformant with the Mesh profile: Istio (1.16 and later), Linkerd (2.14 and later), and Kuma (2.3 and later). Cilium provides mesh functionality through its eBPF-based service mesh but handles the integration through its own control plane.

Unifying North-South and East-West

The real power of GAMMA is that traffic management policies written as HTTPRoute and GRPCRoute resources work identically for both ingress and mesh traffic. An organization using Istio can define an HTTPRoute with weighted traffic splitting, and that same resource pattern works whether it is attached to a Gateway (north-south) or a Service (east-west). This eliminates the need to learn separate APIs for ingress routing (Istio VirtualService) and mesh routing (also Istio VirtualService, but configured differently).

The convergence means that organizations migrating from Istio's native configuration to Gateway API resources gain a unified traffic management model that works across both dimensions. It also means that teams using a Gateway API controller like Envoy Gateway for ingress can adopt Istio's ambient mesh for east-west traffic without learning an entirely new configuration model.

Multi-Cluster Gateway API

As organizations scale to multiple Kubernetes clusters for high availability, geographic distribution, or team isolation, routing traffic across cluster boundaries becomes critical. The Gateway API provides foundational support for multi-cluster routing through its integration with the Multi-Cluster Services API.

Multi-Cluster Services Integration

The Kubernetes Multi-Cluster Services API (MCS) enables Services to span multiple clusters within a ClusterSet. Gateway API natively supports routing to these federated Services wherever it supports routing to local Services. The key difference is that a standard Service refers only to cluster-local endpoints, while a ServiceImport (from the MCS API) can refer to endpoints across all clusters in the ClusterSet.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: multi-cluster-route
spec:
  parentRefs:
    - name: global-gateway
  rules:
    - backendRefs:
        - group: multicluster.x-k8s.io
          kind: ServiceImport
          name: global-api
          port: 8080

This HTTPRoute references a ServiceImport instead of a Service, enabling the gateway to route traffic to endpoints across multiple clusters. The gateway implementation handles service discovery, health checking, and load balancing across cluster boundaries.

Implementation Patterns

Google Cloud GKE provides the most mature multi-cluster Gateway implementation. The GKE Gateway controller supports multi-cluster load balancing, health-based failover, traffic splitting across clusters, and traffic mirroring between clusters. A multi-cluster Gateway in GKE provisions a global load balancer that routes traffic to the nearest healthy cluster.

Istio supports multi-cluster mesh topologies where services in different clusters can communicate seamlessly. Gateway API resources defined in one cluster can route to Services in other clusters through Istio's cross-cluster service discovery.

Cilium Cluster Mesh enables cross-cluster networking at the CNI level, and Cilium's Gateway API implementation can route to services across connected clusters.

Federated Gateway Pattern

In a federated gateway architecture, each cluster runs its own Gateway instances, and a global load balancer or DNS-based routing layer distributes traffic across the federated gateways. This pattern provides geographic routing, disaster recovery, and regional isolation while maintaining a consistent Gateway API configuration model across all clusters.

The typical setup involves a global traffic manager (cloud provider load balancer, DNS-based routing, or a dedicated global server load balancing solution) that health-checks the gateway endpoints in each cluster and routes clients to the nearest healthy gateway. Each cluster's Gateway and HTTPRoute resources are managed independently, often through GitOps tooling that ensures configuration consistency across clusters.

Gateway API and cert-manager: Automated TLS

TLS certificate management is one of the most operationally painful aspects of running production services. The integration between Gateway API and cert-manager automates certificate provisioning, renewal, and rotation.

How the Integration Works

cert-manager watches Gateway resources and automatically provisions TLS certificates for Gateway listeners. When a Gateway listener specifies a hostname and TLS configuration, cert-manager creates a Certificate resource, performs the ACME challenge (or uses another issuer), and stores the resulting certificate in the Kubernetes Secret referenced by the Gateway.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: secure-gateway
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-production
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: api.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - name: api-example-com-tls

The cert-manager.io/cluster-issuer annotation tells cert-manager which issuer to use for provisioning the certificate. cert-manager automatically derives the DNS names from the Gateway's listener hostnames, provisions the certificate, and stores it in the Secret specified by certificateRefs.

ACME HTTP-01 via Gateway API

Since cert-manager 1.15, the Gateway API integration is no longer gated behind a feature flag. cert-manager can now use Gateway API HTTPRoute resources (instead of Ingress resources) to serve ACME HTTP-01 challenges. This means organizations running a pure Gateway API stack without any Ingress resources can still use Let's Encrypt for automated certificate provisioning.

cert-manager creates temporary HTTPRoute resources that route ACME challenge traffic to the cert-manager solver pod. Once the challenge is complete, the temporary HTTPRoute is cleaned up automatically.

Operational Benefits

Automated TLS with cert-manager and Gateway API eliminates several operational burdens. Certificates are renewed automatically before expiry. Wildcard certificates can be provisioned using DNS-01 challenges. Multiple Gateway listeners can share the same certificate or use separate certificates as needed. The cluster operator configures the TLS infrastructure once on the Gateway, and cert-manager handles the ongoing lifecycle.

Migrating from Ingress to Gateway API

With the Ingress NGINX Controller retirement scheduled for March 2026 and the broader ecosystem moving toward Gateway API, migration is no longer optional for many organizations. The good news is that the migration can be incremental, with Ingress and Gateway API coexisting during the transition.

Pre-Migration Assessment

Before writing any Gateway API manifests, document your current Ingress configuration thoroughly:

1. Inventory all Ingress resources across every namespace. Document hosts, paths, TLS configurations, and backend services.
2. Catalog all annotations and identify which are controller-specific features. Annotations fall into three categories: those with direct Gateway API equivalents (path routing, TLS termination, header manipulation), those covered by implementation-specific policies (rate limiting, authentication, custom error pages), and those with no clear equivalent that may require application-level changes.
3. Map RBAC requirements. Identify who currently modifies Ingress resources and what level of access they need. Plan the namespace and RBAC structure for the Gateway API's role-based model.
4. Choose your Gateway API implementation. This decision should consider your current proxy expertise, required features, service mesh plans, and operational preferences.

The ingress2gateway Tool

The Kubernetes SIG Network community provides ingress2gateway, an open-source tool that automatically translates Ingress resources into Gateway API equivalents. The tool handles the mechanical conversion: Ingress rules become HTTPRoute resources, TLS blocks become Gateway listener configurations, and host-based routing maps to HTTPRoute hostnames.

# Install ingress2gateway
go install github.com/kubernetes-sigs/ingress2gateway@latest

# Convert existing Ingress resources
ingress2gateway print --input-file ingress.yaml

# Convert from a live cluster
kubectl get ingress -A -o yaml | ingress2gateway print

The tool generates starting-point manifests that will require manual review and adjustment. It cannot convert controller-specific annotations into Gateway API policies automatically, and some routing patterns may need restructuring to fit the Gateway API model.

Coexistence Strategy

The recommended migration approach runs both Ingress and Gateway API simultaneously:

Step 1 — Deploy the Gateway API CRDs and your chosen controller. Install the Gateway API CRDs (kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml) and deploy the controller. This does not affect existing Ingress resources.

Step 2 — Create GatewayClass and Gateway resources. Define the gateway infrastructure. At this point, the gateway is listening but no routes are attached, so no traffic flows through it.

Step 3 — Migrate routes incrementally. Start with non-critical services. Create HTTPRoute resources that attach to the new Gateway and point to the same backend Services. Validate routing, TLS termination, and any policy attachments.

Step 4 — Switch DNS or load balancer targets. Once the Gateway API routes are validated, update DNS records or load balancer configurations to point to the new gateway endpoints. Keep the old Ingress running as a fallback.

Step 5 — Decommission Ingress resources. After a validation period with production traffic flowing through the Gateway API, remove the old Ingress resources and eventually the Ingress controller.

Common Annotation Mappings

| Ingress Annotation | Gateway API Equivalent | | ------------------------------------------------ | ------------------------------------------------------------------------- | | nginx.ingress.kubernetes.io/rewrite-target | HTTPRoute URLRewrite filter | | nginx.ingress.kubernetes.io/ssl-redirect | HTTPRoute RequestRedirect filter with scheme: https | | nginx.ingress.kubernetes.io/canary-weight | HTTPRoute backendRefs weight field | | nginx.ingress.kubernetes.io/proxy-read-timeout | HTTPRoute timeouts.backendRequest | | nginx.ingress.kubernetes.io/proxy-send-timeout | HTTPRoute timeouts.request | | nginx.ingress.kubernetes.io/cors-* | Implementation-specific policy (e.g., Envoy Gateway BackendTrafficPolicy) | | nginx.ingress.kubernetes.io/rate-limit-* | Implementation-specific policy | | nginx.ingress.kubernetes.io/auth-* | Implementation-specific security policy | | nginx.ingress.kubernetes.io/websocket-services | No annotation needed (Gateway API supports WebSocket natively) |

Performance Considerations

Performance characteristics vary significantly across Gateway API implementations. The choice of data plane proxy, configuration propagation speed, and resource consumption all affect production workloads.

Configuration Propagation Latency

Configuration propagation latency measures how quickly a change to a Gateway API resource takes effect in the data plane. This matters for canary deployments, emergency rollbacks, and dynamic routing changes.

Envoy-based implementations (Envoy Gateway, Istio, Contour) use the xDS protocol for real-time configuration updates, achieving propagation times in the low milliseconds. Kong also achieves millisecond-range propagation through its admin API.

NGINX-based implementations (NGINX Gateway Fabric) require NGINX configuration regeneration and reload, which can take seconds. This means that rapid weight changes during a canary deployment will take longer to take effect with NGINX compared to Envoy-based implementations.

Traefik falls in between, with propagation times that are faster than NGINX but slower than Envoy-based implementations.

Data Plane Latency Overhead

Every gateway adds some latency to request processing. The overhead depends on the proxy, the complexity of routing rules, and whether L7 processing is required.

Cilium's eBPF-based L3/L4 processing adds the least latency for TCP connections that do not require HTTP-level routing. For L7 processing (HTTP routing, header matching, traffic splitting), all implementations ultimately use userspace proxies, and the latency overhead is comparable across Envoy-based implementations (typically 0.5 to 2 milliseconds at P50 for a simple routing rule).

NGINX Gateway Fabric shows slightly lower per-request latency than Envoy for simple routing patterns due to NGINX's efficient event-driven architecture, but the advantage narrows for complex routing configurations.

Resource Consumption

Gateway API controllers and their data plane proxies consume CPU and memory. For capacity planning, consider both the controller (control plane) and the proxy fleet (data plane).

Envoy Gateway deploys a separate Envoy proxy per Gateway resource, providing strong isolation but higher base resource consumption for organizations running many gateways. Istio's shared control plane amortizes overhead across all gateways and mesh proxies. Cilium's control plane has higher CPU consumption (approximately 7.5 times Istio's under benchmark conditions) but does not require separate proxy deployments for L4 traffic.

Scaling Limits

At high route counts (thousands of HTTPRoute resources), implementation behavior diverges. Envoy-based implementations generally handle large configurations well, though very large xDS configurations can increase propagation latency. Cilium has shown issues at extreme scale where Envoy configuration updates fail entirely once the total configuration size exceeds implementation-specific thresholds. NGINX Gateway Fabric scales well in terms of request throughput but configuration reload times increase linearly with the number of routes.

Real-World Migration Patterns

Understanding how organizations have approached the migration from legacy Ingress to the Gateway API provides practical insights that documentation alone cannot capture.

Pattern 1: The Greenfield Service

The simplest adoption path is new services that have no legacy Ingress configuration. Teams deploying new microservices in clusters that already have a Gateway API controller installed can start with HTTPRoute from day one. This eliminates migration complexity entirely and lets teams build operational experience with the Gateway API before tackling legacy migrations.

Organizations report that teams with no prior Gateway API experience become productive within one to two weeks when starting with greenfield services. The learning curve is concentrated in understanding the resource model (GatewayClass, Gateway, Route separation) rather than the routing configuration itself, which maps intuitively from Ingress concepts.

Pattern 2: The Parallel Stack

The most common migration pattern involves running Ingress and Gateway API in parallel, migrating services one at a time. This approach minimizes risk but requires operating two traffic management systems simultaneously.

A financial services company with more than 400 microservices across 12 Kubernetes clusters migrated from NGINX Ingress to Envoy Gateway over eight months using this pattern. They started with internal APIs (lower risk), moved to customer-facing APIs once they had operational confidence, and decommissioned NGINX Ingress only after three months of parallel operation with production traffic flowing through the Gateway API.

Key lessons from this pattern: invest in automated testing of routing configurations before switching traffic. Use the ingress2gateway tool as a starting point but expect 30 to 40 percent of the generated manifests to require manual adjustment, particularly for annotation-heavy Ingress resources. Plan for the operational overhead of running two systems during the transition period.

Pattern 3: The Service Mesh Convergence

Organizations already running Istio for service mesh functionality have a natural migration path. Istio supports both its native VirtualService/ DestinationRule configuration and Gateway API resources simultaneously. Teams can migrate incrementally from VirtualService to HTTPRoute, and with GAMMA support, the same HTTPRoute resources work for both ingress and mesh traffic.

This pattern eliminates the "two systems" overhead of the parallel stack approach because Istio serves as both the legacy and new traffic management system. The migration is purely a configuration migration, not an infrastructure migration.

Istio's documentation recommends migrating in this order: Gateway resources first (replacing Istio Gateway resources), then HTTPRoute resources (replacing VirtualService), and finally implementation-specific policies (replacing DestinationRule and EnvoyFilter where possible, using Gateway API BackendPolicy and policy attachment for the rest).

Pattern 4: The CNI-Driven Adoption

Organizations using Cilium as their CNI often adopt its Gateway API implementation as part of a broader Cilium adoption. Because Cilium's gateway functionality is integrated into the CNI, there is no additional infrastructure to deploy. The migration is a configuration migration from legacy Ingress resources to Gateway API resources, with Cilium handling both the old and new configurations.

This pattern works well for organizations that are already planning a CNI migration or upgrade. The gateway functionality comes "for free" with Cilium, reducing the justification burden for adopting the Gateway API.

Looking Ahead: What is Coming

The Gateway API continues to evolve with a clear roadmap for 2026 and beyond.

Experimental features maturing to Standard. HTTPRoute retries, TCPRoute, TLSRoute, UDPRoute, and BackendLBPolicy are all candidates for graduation to the Standard channel as implementations gain production experience with these features. The monthly experimental channel releases accelerate iteration on these features.

GAMMA enhancements. The GAMMA initiative continues to expand mesh support within the Gateway API. Future releases are expected to include mesh-specific extensions as stable features, further unifying ingress and mesh configuration. Service mesh implementations are converging on Gateway API as the standard configuration interface, which means investment in Gateway API knowledge pays dividends across both ingress and mesh use cases.

Implementation conformance enforcement. Starting with the Gateway API v1.5 review process expected in mid-2026, stale implementations that are no longer passing conformance tests will be delisted from the official implementations page. This raises the quality bar and gives organizations confidence that listed implementations are actively maintained and conformant.

Ingress NGINX retirement. The retirement of the Ingress NGINX Controller in March 2026 removes security updates, bug fixes, and community support for one of the most widely deployed Kubernetes networking components. Organizations still running Ingress NGINX should have their migration plans finalized and execution underway.

AI gateway extensions. Envoy Gateway's AI Gateway extensions for LLM traffic management represent a new frontier for the Gateway API ecosystem. As AI workloads become a larger share of Kubernetes traffic, expect more implementations to add AI-specific routing, rate limiting, and observability features.

Conclusion

The Kubernetes Gateway API has matured from an ambitious specification into the production standard for traffic management in Kubernetes. The v1.4 release delivers a stable, expressive, and portable API for HTTP and gRPC routing, TLS management, traffic splitting, and backend security. The GAMMA initiative extends this same API model to service mesh traffic, creating a unified configuration language for both north-south and east-west communication. More than 25 implementations provide options ranging from lightweight, single-binary proxies to full-featured service mesh platforms.

For organizations still running legacy Ingress, the retirement of NGINX Ingress Controller in March 2026 makes the migration timeline concrete. The Gateway API's role-based design, typed resource model, and policy attachment extensibility address every significant limitation of the Ingress API. The migration path is well-documented, tooling exists to automate the mechanical conversion, and the parallel operation strategy minimizes risk.

The question is no longer whether to adopt the Gateway API. It is which implementation best fits your operational requirements, and when your migration timeline begins.