Skip to main content
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:
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

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. The Gateway resolves the Engine Service by its fully qualified name, <engine>-service.<namespace>.svc.cluster.local, and does not expand the pod’s DNS search domains. If you enforce DNS-level network policies, allow queries for that name; the Gateway sends no other lookups for Engine routing. 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. Traffic that bypasses the Gateway is unsupported and receives none of these guarantees. See Engine rollouts for drain controls and Gateway sizing for memory and concurrency planning.