Routing

The XTrinode gateway is the load balancer and reverse proxy for Trino client traffic. It receives queries from users, BI tools, notebooks, and applications, then selects the right backend coordinator. It sits behind an ingress, LoadBalancer Service, or internal Service; it is not itself an Ingress controller.

Route Inputs

Routes can be selected by:

• hostname;
• X-Trino-XTrinode header;
• default route;
• shared routing groups when multiple runtime backends should load-balance.

Routing priority is:

1. Hostname.
2. X-Trino-XTrinode header.
3. Default route.

A provided header that does not match a route should return an explicit failure rather than silently falling back to the default route.

Route definitions are stored in the trino-gateway-routes ConfigMap in the gateway namespace. The gateway keeps the last-good route set when a full config load is invalid.

Query Path

Client
  -> optional ingress
  -> XTrinode gateway
  -> selected coordinator service
  -> Trino coordinator
  -> Trino workers

Dedicated Runtime

Each runtime can get its own routing group and generated hostname.

apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: runtime-a
  namespace: production
spec:
  size: m
  routing:
    header: X-Trino-XTrinode=production/runtime-a
    hostnameDomain: trino.example.com

Result:

• routing group: production--runtime-a;
• header selector: production/runtime-a;
• hostname: production--runtime-a.trino.example.com;
• backend: the runtime-a coordinator.

Shared Pool

Multiple runtimes can join the same routing group for load balancing.

apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: runtime-shared-1
  namespace: production
spec:
  size: m
  routing:
    routingGroup: shared
    hostnameDomain: trino.example.com
---
apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: runtime-shared-2
  namespace: production
spec:
  size: m
  routing:
    routingGroup: shared
    hostnameDomain: trino.example.com

Result:

• routing group: shared;
• hostname: shared.trino.example.com;
• backends: runtime-shared-1 and runtime-shared-2.

Explicit Hostname

Use routing.hostname when the public hostname should not be generated from the routing group.

apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: analytics
  namespace: production
spec:
  size: l
  routing:
    hostname: analytics.example.com

Default Route

Mark one route as the fallback for requests without an explicit selector.

apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: default-runtime
  namespace: production
spec:
  size: s
  routing:
    default: true

Use default routes sparingly. They are convenient for early testing, but hostname routing is usually clearer for production-facing entrypoints.

Suspended Runtimes

When a selected route points at a suspended runtime, or when a coordinator is temporarily unreachable, the gateway can ask the API server to resume it. The client then retries after resume has started.

The API server uses a Kubernetes lease for each runtime or routing group so only one resume operation wins when many clients arrive at the same time.

Operational Checks

When routing fails, check:

• gateway logs;
• gateway route ConfigMap;
• runtime phase and status conditions;
• coordinator service DNS;
• the expected hostname or X-Trino-XTrinode header;
• API server resume responses;
• KEDA status when worker scaling is enabled.