#kubernetes#envoy-gateway#gateway-api#httproute#grpcroute#tcproute#tlsroute

Envoy Gateway Route Type Cheatsheet: HTTPRoute, GRPCRoute, TCPRoute, or TLSRoute?

5 min read

If you've read the previous posts, the question that's most likely blocking you now isn't "I don't understand Gateway API" — it's:

"Okay but which one do I actually write — HTTPRoute, GRPCRoute, TCPRoute, or TLSRoute?"

This post exists specifically to untangle that. Keep it as a pocket reference. When a new service comes up, consult this first — it'll save you from writing YAML blindly and getting a lesson from condition statuses.

The Conclusion First: Four Route Types, Four Purposes

Route Type Traffic Layer What It Inspects Best For Not For
HTTPRoute L7 HTTP/HTTPS host, path, header, query, method Websites, REST APIs, general web traffic Raw TCP, TLS passthrough
GRPCRoute L7 gRPC hostname, service, method, header gRPC service/method routing General REST APIs, raw TCP
TCPRoute L4 TCP Listener and connection-level info Databases, custom TCP protocols, non-HTTP services Scenarios needing path/header inspection
TLSRoute L4/L5 TLS TLS SNI hostname TLS passthrough, preserving end-to-end encryption Needing to inspect HTTP details after decryption

If you want an ultra-short version:

  • Inspect path or header → HTTPRoute
  • Inspect gRPC service/method → GRPCRoute
  • Just forwarding TCP connections → TCPRoute
  • No TLS termination, SNI routing only → TLSRoute

Three-Step Decision: Stop Guessing

Use this order:

  1. Will the Gateway parse HTTP semantics from this traffic?
  2. If yes, is it regular HTTP/REST, or gRPC?
  3. If no, is it raw TCP, or TLS passthrough?

Mapped out:

  • Has HTTP path/header/method to inspect → HTTPRoute
  • Has gRPC service/method to inspect → GRPCRoute
  • No L7 rules, just TCP forwarding → TCPRoute
  • Want TLS preserved to the backend → TLSRoute

This decision matters a lot. Many people instinctively write HTTPRoute first, then realize halfway through that they're dealing with database traffic. The entire YAML enters "what am I even doing" mode.

Minimal YAML Examples: Recognize Each at a Glance

Here are the shortest, most recognizable versions of each.

HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
spec:
  parentRefs:
    - name: eg
      sectionName: http
  hostnames:
    - "app.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-service
          port: 8080

If you see path, hostnames, and backendRefs — it's this one.

GRPCRoute

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: user-grpc
spec:
  parentRefs:
    - name: eg
      sectionName: grpc
  hostnames:
    - "grpc.example.com"
  rules:
    - matches:
        - method:
            service: com.example.User
            method: Login
      backendRefs:
        - name: user-grpc-service
          port: 50051

If you see method.service and method.method — you're matching gRPC semantics, not regular HTTP.

TCPRoute

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

TCPRoute has almost no path/header concepts — because it doesn't look at those. It's closer to: "TCP connections arriving at this listener go to this backend."

TLSRoute

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: passthrough-route
spec:
  parentRefs:
    - name: eg
      sectionName: tls
  hostnames:
    - "db.example.com"
  rules:
    - backendRefs:
        - name: db-service
          port: 5432

It's typically paired with a protocol: TLS listener. The focus isn't decryption — it's SNI-based routing.

💡 TCPRoute and TLSRoute often live in the experimental channel across Gateway API versions. Verify the CRD version installed in your cluster before applying.

Four Common Pitfalls

1. gRPC Doesn't Necessarily Require GRPCRoute

If you just need gRPC traffic to flow, some implementations may support it via HTTPRoute since gRPC runs over HTTP/2. But if you want to match on gRPC service/method semantics, GRPCRoute is the more correct and readable choice.

2. TLSRoute Is Not "HTTPS but Advanced"

This is the most common misconception.

  • HTTPS listener + HTTPRoute: Gateway terminates TLS, then applies HTTP rules
  • TLS listener + TLSRoute: Gateway does NOT terminate TLS, routes based on SNI only

One decrypts and plays at L7. The other keeps traffic encrypted and does passthrough. Completely different worlds.

3. TCPRoute Cannot See Path/Header

If your requirement is:

  • /api goes to A
  • /admin goes to B

That's not TCPRoute's job. TCPRoute doesn't understand HTTP details. Forcing those requirements into it is just setting yourself up for frustration.

4. parentRefs.sectionName Is Important

When a Gateway has multiple listeners, use sectionName:

parentRefs:
  - name: eg
    sectionName: https

This ensures your route attaches precisely to the listener you intend. Without it, you might think you're booking a VIP room and end up in the wrong hall entirely.

One-Line Summary

First identify what you're working with: HTTP, gRPC, TCP, or TLS passthrough — then pick the right route type. Get the route right and 80% of your YAML flows naturally. Get it wrong and you're trapped in a battle with condition statuses.

Next Step

Once you understand route types, the next common sticking point is: When the same Gateway has many listeners, how do you structure them without creating chaos?

Next post covers multi-listener design: 👉 Listener Design Guide