Gateway API v1.6: TCPRoute and UDPRoute Graduate to Standard

Gateway API v1.6.0, released on June 30 2026, extends the Kubernetes networking model from a production‑grade HTTP/TLS (L7) focus to a full‑stack L4 routing capability. By graduating TCPRoute and UDPRoute to the gateway.networking.k8s.io/v1 API, the project now offers a stable, role‑oriented abstraction for raw TCP and UDP traffic such as databases, DNS, VoIP, gaming, and IoT telemetry.

How L4 routing is expressed

A Gateway defines a listener that advertises the protocol and port. A TCPRoute (or UDPRoute) references that listener via parentRefs and forwards traffic to one or more backend services. The routing decision is based solely on protocol and port; no HTTP headers or TLS SNI are required.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
  - name: foo
    protocol: TCP
    port: 12345
    allowedRoutes:
      kinds:
      - kind: TCPRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
  name: tcp-app
spec:
  parentRefs:
  - name: example-gateway
    sectionName: foo
  rules:
  - backendRefs:
    - name: my-foo-service
      port: 6000

When traffic arrives on port 12345 of the gateway, it is proxied to the endpoints of my-foo-service on port 6000. Omitting sectionName attaches the route to every TCP listener on the gateway, providing flexible binding semantics.

Experimental API group separation

Resources that are still experimental have been moved to the gateway.networking.x-k8s.io API group and receive an X prefix (e.g., XBackend). This explicit grouping prevents accidental use of non‑GA types and clarifies upgrade paths: when an experimental type graduates, it is renamed into the standard group and loses the X prefix.

Adoption checklist for engineers

• Upgrade your controller to a version that implements the v1.6 conformance suite.
• Replace legacy Service-only L4 exposure with Gateway + TCPRoute/UDPRoute definitions.
• Validate that allowedRoutes on listeners include the appropriate route kind.
• Run the Gateway API conformance tests in your CI pipeline to ensure portability across implementations.
• If you need external host destinations, experiment with XBackend while acknowledging its experimental status and security considerations (e.g., potential confused‑deputy attacks).

By adopting the GA L4 routes, teams can consolidate ingress, egress, and service‑mesh configurations under a single, versioned API surface, reducing operational drift between controller implementations and simplifying policy enforcement across both L4 and L7 workloads.

With the release of Gateway API v1.6.0, TCPRoute and UDPRoute have officially graduated from the experimental channel to the Standard v1 API version. This transition provides enterprise engineers with a portable, stable mechanism for routing raw layer 4 (L4) traffic, eliminating the previous reliance on implementation-specific Custom Resource Definitions (CRDs) or standard Kubernetes Services for complex networking requirements.

Historically, Gateway API focused on layer 7 (L7) HTTP and TLS traffic. Workloads requiring raw protocol support—such as databases, DNS services, VoIP, and gaming backends—lacked a standardized interface. By migrating these routes to the v1 API, the community has established a consistent model for L4 traffic management that is portable across any conformant Gateway controller.

The technical implementation relies on attaching a route to a specific listener defined on a Gateway resource:

• Protocol-Specific Routing: A Gateway listener is configured with a specific protocol (TCP or UDP) and port. The corresponding TCPRoute or UDPRoute then attaches to this listener to handle traffic.
• Backend Forwarding: Routes define backendRefs to direct traffic to service endpoints. Traffic arriving on the Gateway listener port is transparently proxied to the target service port without requiring L7 inspection or protocol awareness.
• Attachment Granularity: Engineers can specify a sectionName in the parentRefs to bind a route to a specific listener. Omitting this field attaches the route to every listener of the specified protocol on that Gateway, simplifying configuration for broad service exposure.

The v1alpha2 versions of these resources are now deprecated and scheduled for future removal. By adopting the v1 API, engineering teams ensure long-term support and cross-platform compatibility for their L4 infrastructure, reducing operational overhead and dependency on platform-locked networking solutions.

The graduation of TCPRoute and UDPRoute to the v1 API in Gateway API 1.6.0 provides a standardized, portable mechanism for routing non-HTTP traffic, such as databases, DNS, and IoT telemetry. Unlike Layer 7 routing, these resources forward traffic to backends based strictly on protocol and port, decoupling infrastructure configuration from application-specific logic.

Implementing Layer 4 routing requires a dual-stage configuration pattern: defining protocol-specific listeners within a Gateway resource and attaching routes via parentRefs.

Listener Configuration

A Gateway must explicitly enable L4 traffic by defining listeners that specify the TCP or UDP protocol. The allowedRoutes.kinds field acts as a security boundary, restricting which route types can bind to the listener.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
  - name: tcp-listener
    protocol: TCP
    port: 12345
    allowedRoutes:
      kinds:
      - kind: TCPRoute

Attaching Routes

Routes interface with the Gateway through parentRefs. This reference points to the Gateway and, optionally, a specific sectionName (the listener name). Omitting the sectionName attaches the route to every matching protocol listener on the Gateway.

apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
  name: tcp-app
spec:
  parentRefs:
  - name: example-gateway
    sectionName: tcp-listener
  rules:
  - backendRefs:
    - name: my-service
      port: 6000

Key Implementation Considerations

• API Stability: TCPRoute and UDPRoute are now stable in v1. The legacy v1alpha2 versions are deprecated and subject to removal.
• Port Mapping: The backendRefs port is independent of the Gateway listener port; traffic arriving at the Gateway's ingress port is proxied to the target service port.
• Experimental Boundaries: As of v1.6.0, new experimental resources (e.g., XBackend) use the gateway.networking.x-k8s.io API group and are prefixed with X to differentiate them from standard resources.

The Gateway API release introduced a structural change in how experimental resources are exposed. Historically, experimental types such as TCPRoute and UDPRoute lived in the same API group as stable resources (gateway.networking.k8s.io) and were distinguished only by a v1alpha2 version string. This version‑based distinction required developers to inspect both apiVersion and kind to determine maturity, which often led to accidental use of non‑GA objects in production pipelines.

Starting with v1.6, all new experimental resources are defined in a dedicated group gateway.networking.x-k8s.io. The group name itself signals experimental status, and each type receives an X prefix (e.g., XBackend, XMesh). When a resource graduates to standard, the X prefix is removed and the object moves to gateway.networking.k8s.io. This explicit separation simplifies API discovery, version management, and policy enforcement.

Practical implications for engineers

• Discovery: kubectl api-resources --api-group=gateway.networking.x-k8s.io lists only experimental kinds, making it easy to audit usage.
• RBAC scoping: Role bindings can target the experimental group separately, preventing unintended privilege escalation.
• CI/CD gating: Pipelines can enforce a rule such as “no X* resources in production manifests” by scanning the apiVersion field.

Below is a minimal example of an experimental XBackend that routes HTTP traffic to an external hostname. Note the distinct apiVersion and the X prefix in the kind field.

apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XBackend
metadata:
  name: ai-provider-api
  namespace: ai-apps
spec:
  type: ExternalHostname
  externalHostname:
    hostname: api.ai-provider.com

The corresponding HTTPRoute references the experimental backend by specifying the group explicitly:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ai-route
spec:
  rules:
  - backendRefs:
    - name: ai-provider-api
      kind: XBackend
      group: gateway.networking.x-k8s.io

When XBackend graduates, the same manifest would change to apiVersion: gateway.networking.k8s.io/v1 and the kind would become Backend, eliminating the X prefix.

Adopting this pattern improves clarity in large clusters, aligns with Kubernetes’ version‑agnostic API design, and reduces the risk of mixing experimental and production‑grade resources.

The Gateway API v1.6 release introduces TCPRoute and UDPRoute as standard resources, expanding the API’s reach to layer‑4 traffic. Because the API is defined as a set of Custom Resource Definitions (CRDs), each controller that implements the spec must pass the upstream conformance test suite. Passing these tests guarantees that a deployment behaves consistently across clusters, which is essential for production‑grade service networking.

When you begin a new project, select a conformant implementation to ensure that the standard semantics of Gateway, HTTPRoute, TCPRoute, and UDPRoute are respected. The following controllers are listed as conformant with Gateway API v1.6 at the time of the release:

• Agentgateway
• Airlock
• Microgateway
• GKE Gateway
• kgateway
• NGINX Gateway Fabric
• Traefik Proxy

For example, a minimal TCPRoute using the GKE Gateway controller looks like this:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: gke-l7-gc
  listeners:
  - name: db
    protocol: TCP
    port: 5432
    allowedRoutes:
      kinds:
      - kind: TCPRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
  name: postgres-route
spec:
  parentRefs:
  - name: example-gateway
    sectionName: db
  rules:
  - backendRefs:
    - name: postgres-svc
      port: 5432

After applying the manifests, traffic sent to the Gateway’s port 5432 is proxied to the postgres-svc service, demonstrating a portable L4 routing configuration that works with any conformant controller.

Community involvement is a key part of maintaining and extending the API. Engineers can contribute in several ways:

• Slack: Join #sig-network-gateway-api on the Kubernetes Slack to ask questions, share experiences, and receive real‑time feedback.
• Meetings: Attend the weekly SIG Network community meetings; the calendar is published on the SIG Network website.
• GitHub: File issues, propose enhancements (GEPs), or submit pull requests in the kubernetes-sigs/gateway-api repository.

By selecting a conformant implementation and engaging with the SIG Network channels, engineers can quickly get a reliable gateway stack up and contribute to the evolving ecosystem.