Architecture

How FireboltInstance, FireboltEngine, and FireboltEngineClass work together.

The Firebolt Operator manages three 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.

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.

An Engine may also reference one EngineClass in the same namespace through spec.engineClassRef. Engine settings take precedence over matching class settings, and class settings take precedence over Firebolt Operator defaults. See EngineClass configuration inheritance.

Query traffic

Clients normally 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.

You can also connect directly to an Engine Service. Direct connections bypass 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.