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

The Kubernetes SIG Network community released Gateway API v1.6.0 on June 30, marking a significant maturation of the standard for role-oriented, expressive service networking. While previous iterations established a robust, production-grade foundation for Layer 7 (HTTP and TLS) routing, v1.6.0 expands the API's scope to include standard Layer 4 protocol routing, providing a portable interface for non-HTTP workloads.

The release introduces two primary structural changes designed to improve API clarity and stability:

• Graduation of TCPRoute and UDPRoute: Both resources have moved from the Experimental channel to the Standard channel (v1 API). This enables consistent, protocol-aware routing for databases, DNS, VoIP, and IoT telemetry without requiring implementation-specific Custom Resource Definitions (CRDs).
• Experimental API Group Separation: To provide clear boundaries between stable and experimental features, experimental resources now reside under the gateway.networking.x-k8s.io group and utilize an "X" prefix (e.g., XBackend).

TCPRoute and UDPRoute allow for traffic forwarding based on protocol and port. A TCPRoute attaches to a Gateway listener as demonstrated below:

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

By defining sectionName, traffic arriving at the specific listener is proxied to the defined backend service. If sectionName is omitted, the route attaches to all TCP listeners on the specified Gateway.

The introduction of the experimental XBackend resource addresses limitations in the standard Service object. It acts as a decorator, enabling features like ExternalHostname destinations—previously excluded to prevent security vulnerabilities such as confused deputy attacks—while providing a structured path for future enhancements like session persistence and TLS origination. Engineers should treat resources within the gateway.networking.x-k8s.io group as subject to breaking changes, as they remain in the experimental development phase.

Until Gateway API v1.6, the stable routing model covered HTTP and TLS layer 7 traffic. Workloads that speak raw protocols over TCP or UDP—databases, DNS, VoIP, gaming, IoT telemetry—had no portable API to attach to a Gateway. Operators fell back to plain Kubernetes Services or implementation-specific CRDs that do not transfer between Gateway controllers. TCPRoute and UDPRoute close that gap.

TCPRoute and UDPRoute route traffic to backends based on protocol and port alone. They do not parse payloads and require no L7 awareness, which makes them applicable to any L4 workload:

• Database replication and client connections
• DNS resolvers
• VoIP and media signaling
• Gaming servers
• IoT telemetry ingestion

Both resources graduated from the Experimental channel to Standard and moved to the v1 API version. They were specified in GEP-2644 (TCPRoute) and GEP-2645 (UDPRoute), led by Nick Young, Ricardo Katz, and Zac Nixon. The v1alpha2 versions are deprecated as of v1.6 and will be removed in a future release.

To use TCPRoute, a Gateway first declares a TCP listener with an allowedRoutes kind:

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

A TCPRoute then attaches to that listener and forwards to a backend service:

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

Traffic arriving on Gateway port 12345 is proxied to the endpoints of my-foo-service on port 6000. Omitting sectionName and port from parentRefs attaches the route to every TCP listener on the Gateway. UDPRoute follows the same pattern with protocol: UDP and kind: UDPRoute.

For new L4 routing configurations, use the v1 API version rather than v1alpha2. Migration requires updating apiVersion to gateway.networking.k8s.io/v1 and verifying that your Gateway controller implements v1.6 conformance for TCPRoute and UDPRoute.

The Kubernetes Gateway API provides a standardized, portable method for routing Layer 4 (L4) traffic, bridging the gap for workloads that rely on raw TCP or UDP streams—such as databases, VoIP, or IoT telemetry—rather than Layer 7 (HTTP/TLS) protocols. By utilizing TCPRoute and UDPRoute resources, engineers can configure gateways to proxy traffic based strictly on protocol and port, ensuring consistent behavior across different controller implementations.

A TCPRoute attaches to a Gateway through parentRefs. Consider a Gateway configured with a listener named foo on port 12345, restricted to TCPRoute traffic:

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

To route traffic from this listener to a specific service, a TCPRoute is defined. By specifying the sectionName: foo within parentRefs, the route binds exclusively to that listener. When traffic arrives on port 12345 of the Gateway, it is proxied to the endpoints of my-foo-service on port 6000:

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

Key routing behaviors include:

• Granular Binding: Specifying sectionName attaches the route to a specific listener. Omitting both sectionName and port attaches the route to every TCP listener on the Gateway.
• UDP Parity: UDPRoute functions identically to TCPRoute. By changing the listener protocol to UDP and the resource kind to UDPRoute, the same attachment pattern applies.
• Standardization: Since the v1.6.0 release, these resources are part of the standard v1 API, ensuring they are no longer restricted to experimental channels and provide a stable foundation for L4 traffic management.

XBackend, a new Gateway API resource introduced in v1.6 and led by Keith Mattix II, arrives in the Experimental channel via GEP-4894. It is a general-purpose decorator for Service and other backend types within Gateway API, building on ideas from the upstream EndpointSelector KEP. Because experimental resources now live in a separate API group with an X prefix, XBackend is defined in gateway.networking.x-k8s.io. It still targets the backend application, but is designed to let the community extend backend configuration in ways that Service cannot accommodate.

Service is a stable and flexible object, but those attributes carry costs:

• Flexibility creates edge cases that Gateway API must handle.
• Stability prevents new concepts from being added to Service itself.

XBackend provides a Gateway API-native object for backend behavior while avoiding those constraints. The first version supports ExternalHostname destinations, a capability previously ruled out for Gateway API Service backends due to the risk of confused deputy attacks. In XBackend, this support is an Extended/Optional feature, so implementations and users can opt in after understanding the security tradeoffs. This is particularly valuable for egress use cases, such as cluster-hosted agentic workloads calling cloud AI APIs.

Example configuration:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: egress-gateway
spec:
  listeners:
  - name: https
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: gateway-cert

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

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

Note that XBackend is experimental and not ready for production; its behavior may change. The community is also considering migrating Session Persistence configuration from XBackendTrafficPolicy into XBackend, along with retries, TLS origination, and similar settings that are better expressed per-application than per-Route.

Previously, experimental Gateway API resources were served from the same API group as stable resources — gateway.networking.k8s.io — and were distinguished only by a v1alpha2-style version string. This meant a cluster could simultaneously serve a stable v1 resource and an experimental v1alpha2 resource in the same group, with the version as the sole maturity indicator. TCPRoute and UDPRoute were the last resources to graduate under that scheme, moving from experimental v1alpha2 to standard v1 in Gateway API v1.6.0, at which point their v1alpha2 versions were deprecated.

Going forward, the experimental/standard boundary is explicit at the API group level. New experimental resources are defined in a dedicated group, gateway.networking.x-k8s.io, and their API type names carry an X prefix — for example XBackend and XMesh. When an experimental resource graduates to Standard, it is renamed into the standard group gateway.networking.k8s.io and drops the X prefix; XMesh is expected to become Mesh.

This separation has direct implications for how you reference APIs:

• An experimental backend must be referenced with its explicit group, e.g. group: gateway.networking.x-k8s.io and kind: XBackend, in a route's backendRefs.
• A standard resource uses gateway.networking.k8s.io and a non-prefixed kind, such as TCPRoute or UDPRoute at v1.
• Version strings alone no longer signal maturity; the API group and type prefix do.

Consider an HTTPRoute referencing an experimental XBackend for an external hostname destination:

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

Here the route is stable, but the backend type is experimental and explicitly namespaced by group. When evaluating experimental Gateway API features, check the API group and type prefix first: if you see gateway.networking.x-k8s.io or an X-prefixed kind, treat the resource as pre-GA behavior that may change before it graduates into the standard group under its final name.

With Gateway API v1.6.0, TCPRoute and UDPRoute have graduated to Standard, extending the API's stable routing model beyond HTTP and TLS to raw layer 4 protocols. Previously, workloads such as databases, DNS, and IoT telemetry lacked a portable way to attach to a Gateway, often falling back to plain Services or implementation-specific CRDs. Both route types now target the v1 API version; the v1alpha2 versions were deprecated at v1.6 and will be removed in a future release.

TCPRoute routes traffic to backends based on protocol and port alone, with no layer 7 awareness required. For example, a Gateway exposes a TCP listener on port 12345 and allows TCPRoute attachment; the route references the listener by name and forwards traffic to a backend Service on port 6000. A UDPRoute follows the same pattern with the listener protocol and route kind swapped. Omitting sectionName and port in parentRefs attaches the route to every matching listener on the Gateway.

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

For CRD installation and a full list of changes, see the Gateway API Documentation and the v1.6.0 Release Notes. The conformance test suite ensures consistent, portable behavior across implementations; implementations conformant with v1.6 at publication time include:

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

Gateway API is an open, community-driven project under Kubernetes SIG Network. Join #sig-network-gateway-api on Kubernetes Slack, attend weekly community meetings via the SIG Network Calendar, and contribute by filing issues, proposing enhancements, or submitting pull requests at kubernetes-sigs/gateway-api.

The graduation of TCPRoute and UDPRoute is an essential step toward a complete universal ingress and mesh networking API across layer 4 and layer 7. Thanks to all contributors, reviewers, maintainers, and implementation authors who made Gateway API v1.6.0 possible.