Architecture

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

The Firebolt Operator manages five 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.
• ClusterFireboltEngineClass is an optional cluster-scoped SKU catalog (instance type, resources, node setup). See ClusterFireboltEngineClass CRD reference.
• 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          │
                  │ (namespaced, wins same name) │
                  └──────────────┬───────────────┘
                                 │
                  ┌──────────────┴───────────────┐
                  │ ClusterFireboltEngineClass   │
                  │ (cluster SKU catalog)        │
                  └──────────────┬───────────────┘
                                 │
                                 ▼
┌──────────────────────┐   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 a namespaced class is not Ready for an operator-owned template path, a ClusterFireboltEngineClass live spec fails the SKU-only or operator-owned check, 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 set spec.engineClassRef to a class name. The Firebolt Operator resolves that name namespaced-first: a FireboltEngineClass in the Engine’s namespace if present, otherwise a ClusterFireboltEngineClass of the same name. Settings resolve Engine, then FireboltEnginePreset, then the resolved class, then Firebolt Operator defaults. See EngineClass configuration inheritance.

External metadata PostgreSQL

When FireboltInstance.spec.metadata.postgres is present, the Firebolt Operator does not create the internal PostgreSQL StatefulSet. It renders the supplied host, port, database, and schema into the Metadata Service configuration and mounts the referenced Secret directly; credential bytes are not copied into the Instance or ConfigMap.

The optional spec.metadata.postgres.tls block requires libpq verify-full certificate and hostname verification. The Firebolt Operator projects only the selected key from a same-namespace CA Secret into the Metadata container and sets PGSSLMODE and PGSSLROOTCERT; sidecars cannot mount the operator-owned CA volume.

The Instance controller watches referenced credential and CA Secrets. It folds their resourceVersion values into the Metadata Service pod-template hash, so an in-place credential or CA rotation rolls the single metadata pod even though the Secret names and rendered configuration remain unchanged. The hash never contains Secret bytes.

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.