Gateway overview

Overview

The Firebolt Operator Gateway is based on Envoy Proxy and responsible for query routing. It uses a Lua filter to pick the target Engine from the X-Firebolt-Engine request header or the engine query parameter and a dynamic forward proxy (DFP) to resolve the per-Engine headless Service at request time. The Gateway removes the routing-only query parameter before forwarding the request to the Engine.

Gateway query routing describes Envoy routing, retries, graceful shutdown, and why the Firebolt Operator does not gate on EndpointSlice updates.
Gateway sizing describes replica count, memory limits, and the 2 MiB per-connection buffer constraint.

Connect to engines

Instance gateway (recommended)

The recommended entry point is the instance gateway. The Envoy proxy routes requests based on the target engine name and handles retries during blue-green transitions. Pass the engine with the X-Firebolt-Engine header (raw HTTP clients) or the engine query parameter (the bundled firebolt CLI).

POST http://<instance-name>-gateway.<namespace>.svc.cluster.local/
Headers:
  X-Firebolt-Engine: my-engine
  Content-Type: text/plain
Body: <SQL>

With the Firebolt CLI from an engine pod:

firebolt client \
  --endpoint http://<instance-name>-gateway \
  --insecure \
  --set engine=my-engine \
  -c "SELECT 42" \
  --no-interactive

Per-engine service

Each engine also exposes a headless Service at <engine>-service.<namespace>.svc.cluster.local:3473. Use this when your client implements its own connection-level load balancing and DNS re-resolution. With this entry point the caller is responsible for:

Periodically re-resolving the Service hostname so that newly ready pods are picked up and draining pods are dropped.
Treating a request on a single endpoint that fails with a transport error as “pick another endpoint”, not “retry this request”.

Configuration

The gateway ConfigMap ({instance}-gateway-config) is a pure function of the FireboltInstance. The Firebolt Operator does not regenerate it on engine create, delete, scale, or blue-green events, so those events never trigger a gateway rollout.

Gateway custom service account

By default the Firebolt Operator creates a ServiceAccount, Role, and RoleBinding for the gateway under <instance>-gateway, granting get / list / patch on fireboltengines in the instance’s namespace. The gateway uses this identity to stamp the firebolt.io/wake-requested annotation on FireboltEngine resources when a request arrives for a stopped engine (the wake-on-zero protocol). See Auto-stop and wake-up. When spec.gateway.template.spec.serviceAccountName is set, the Firebolt Operator interprets this as the user taking ownership of the gateway’s identity and skips creating the SA / Role / RoleBinding entirely. You are then responsible for:

Creating the ServiceAccount in the instance’s namespace under the name you specified.
Granting it the verbs the gateway needs:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gateway-wake
  namespace: firebolt
rules:
  - apiGroups: ["compute.firebolt.io"]
    resources: ["fireboltengines"]
    verbs: ["get", "list", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gateway-wake
  namespace: firebolt
subjects:
  - kind: ServiceAccount
    name: my-gateway-sa
    namespace: firebolt
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: gateway-wake

The common reason to override is IRSA / Pod Identity: annotate the SA with the IAM role binding. For IRSA, you can also annotate the Firebolt Operator-managed SA (spec.gateway.template.metadata.annotations) and leave serviceAccountName unset. That path keeps the Firebolt Operator in charge of the RBAC. Missing or under-permissioned user service accounts do not fail at admission. The pod either fails to start (ServiceAccount … not found on the kubelet event stream) or starts but logs Forbidden 403s when it tries to patch a stopped engine’s wake annotation. Verify with:

kubectl auth can-i patch fireboltengines.compute.firebolt.io \
  --as=system:serviceaccount:<namespace>:<sa-name> -n <namespace>

Rolling update parameters

Gateway deployment

Parameter	Value	Rationale
`maxSurge`	`25%`	Standard Kubernetes default for gradual rollout
`maxUnavailable`	`0`	Maintain full capacity during image switches
PodDisruptionBudget	`maxUnavailable: 1`	Allow voluntary disruptions while maintaining availability

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Overview

Connect to engines

Instance gateway (recommended)

Per-engine service

Configuration

Gateway custom service account

Rolling update parameters

Gateway deployment

​Overview

​Connect to engines

​Instance gateway (recommended)

​Per-engine service

​Configuration

​Gateway custom service account

​Rolling update parameters

​Gateway deployment

Overview

Connect to engines

Instance gateway (recommended)

Per-engine service

Configuration

Gateway custom service account

Rolling update parameters

Gateway deployment