Gateway query routing

Select an Engine, understand retries, and preserve queries during cutovers.

The Instance Gateway is the supported zero-downtime entry point for client queries. It resolves ready Engine pods for every request and routes to the selected Engine.

Select an Engine

Use either the X-Firebolt-Engine header or the engine query parameter:

curl -H 'X-Firebolt-Engine: my-engine' \
  http://<gateway-address>:8080/

curl 'http://<gateway-address>:8080/?engine=my-engine'

If both selectors are present, they must name the same Engine. Engine names must be valid lowercase RFC 1123 DNS labels: letters, numbers, and hyphens, with no leading or trailing hyphen.

The Gateway removes the routing-only engine query parameter before forwarding the request.

Traffic path

Client -> Gateway Service -> Envoy -> Engine Service -> ready Engine pod

The Engine Service is headless and returns the ready pod IPs for the active generation. The Gateway performs active readiness checks and opens a new upstream connection for each request.

Creating, scaling, or rolling an Engine does not restart the Gateway. Engine destinations are resolved dynamically.

Retry behavior

The Gateway retries connection failures, refused streams, resets, and a shutdown response marked X-Firebolt-Drained. It does not retry arbitrary HTTP 5xx responses because the Engine might already have applied a request’s side effects.

Requests with bodies up to 2 MiB can be replayed during a retry. Larger request bodies are forwarded without retry buffering, so a cutover-related failure is returned to the client. Split large ingest or multi-statement requests if they must tolerate Engine cutovers.

Graceful Engine shutdown

During an Engine cutover or scale-down:

1. A terminating Engine pod becomes unready and stops accepting new work.
2. The Gateway removes the pod from its healthy upstream set.
3. A request that reaches the pod while shutdown begins receives a retry-safe X-Firebolt-Drained response before query execution starts.
4. The Gateway retries that request on another ready pod.
5. Queries accepted before shutdown continue until they finish or the Engine’s termination window expires.

The zero-downtime contract applies to traffic through the Gateway and to request bodies within the 2 MiB retry limit. Direct Engine Service connections bypass Gateway retry behavior.

See Engine rollouts for drain controls and Gateway sizing for memory and concurrency planning.