> ## Documentation Index
> Fetch the complete documentation index at: https://firebolt-aggregate-helm-docs-pr-79.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -H 'X-Firebolt-Engine: my-engine' \
  http://<gateway-address>:8080/
```

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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

```text theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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](../../engine/engine-rollouts) for drain controls and [Gateway sizing](./gateway-sizing) for memory and concurrency planning.