Architecture

How FireboltInstance, FireboltEngine, FireboltEngineClass, and FireboltEnginePreset work together.

The Firebolt Operator manages four custom resources:

• FireboltInstance provisions shared PostgreSQL, Metadata Service, and Gateway infrastructure in a namespace.
• FireboltEngine runs the compute nodes that serve queries.
• FireboltEngineClass provides optional shared defaults for Engines in the same namespace.
• FireboltEnginePreset is an optional ambient overlay merged under every Engine in the namespace (service account, storage, credential env, customEngineConfig). See FireboltEnginePreset overview.

Resource relationships

                         optional shared defaults
                  ┌──────────────────────────────┐
                  │ FireboltEngineClass          │
                  └──────────────┬───────────────┘
                                 │
                                 ▼
┌──────────────────────┐   1:N   ┌──────────────────────┐
│ FireboltInstance     │◄────────│ FireboltEngine       │
│                      │         │                      │
│ PostgreSQL           │         │ Stateful compute     │
│ Metadata Service     │         │ Query processing     │
│ Gateway              │         │ Per-Engine Service   │
└──────────────────────┘         └──────────────────────┘

Every Engine references one Instance in the same namespace through spec.instanceRef. The Instance must publish a ready Metadata Service before the Engine can start or materialize configuration in the stable, stopped, or creating phases. The Engine reports InstanceReady=False and waits when that gate fails. The switching, draining, and cleaning phases operate on already-rendered resources and finish without reading the Instance.

The same scheduling window applies to the fail-closed EngineClass and FireboltEnginePreset gates. When the class is not Ready for an operator-owned template path, or Preset is required and missing, or not Ready for an operator-owned path, the Engine stays not Ready and does not render a StatefulSet. The switching, draining, and cleaning phases finish that rollout anyway. The Firebolt Operator may still read the EngineClass while draining, for inherited drain settings (rollout, drainCheckEnabled, drain interval). It does not fail closed on those reads.

An Engine may also reference one EngineClass in the same namespace through spec.engineClassRef. Settings resolve Engine, then FireboltEnginePreset, then EngineClass, then Firebolt Operator defaults. See EngineClass configuration inheritance.

Query traffic

Clients connect to the Instance Gateway and select an Engine with the X-Firebolt-Engine header. The Gateway forwards traffic only to ready pods in the Engine’s active generation.

Internally, each Engine exposes a Service that the Gateway resolves at request time. The Gateway resolves that Service by its fully qualified name and never expands the pod’s DNS search domains: the name is already complete, and some environments inject infrastructure search domains whose expansions a DNS-filtering CNI can reject in a way that Envoy’s c-ares resolver treats as fatal for the whole lookup. Exact-name resolution applies to every per-Engine sub-cluster the dynamic forward proxy synthesizes. The Firebolt Operator switches the Service between generations during blue-green rollouts. It is an internal mechanism, not a client entry point: traffic that bypasses the Gateway is unsupported and loses Gateway features, including waking an auto-stopped Engine.

See Gateway overview for connection examples and Gateway query routing for routing behavior.

Engine availability

The Firebolt Operator applies Engine changes with blue-green generations:

1. It creates the desired generation.
2. It waits for all pods and readiness-aware sidecars to become ready.
3. It switches the Engine Service to the new generation.
4. For a graceful rollout, it waits for queries on the old generation to drain.
5. It removes the old generation.

The active generation remains available while the replacement starts. Plan cluster capacity for both generations to coexist during a rollout. See Engine scaling and Engine rollouts.

Instance-wide security

Authentication and listener TLS are configured on the Instance and apply consistently to its Engines:

• spec.auth configures local authentication and optional OIDC validation.
• spec.tls.engine configures TLS between the Gateway and Engines.
• spec.tls.gateway configures client-facing Gateway TLS and optional mutual TLS.

The Instance reports authentication and TLS readiness independently through AuthReady, EngineTLSReady, and GatewayTLSReady. See Security for configuration, certificate, Secret, and network-policy guidance.

Storage

Engine pod storage and managed-table object storage are separate settings:

• spec.storage selects the pod data volume backend: emptyDir, hostPath, or a persistent volume claim template.
• spec.customEngineConfig.storage configures the object store used for managed table data.

See the FireboltEngine CRD reference and the object storage guides.