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

# 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](./crd-reference/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](./enginepreset/overview).

## Resource relationships

```text theme={"theme":{"light":"css-variables","dark":"css-variables"}}
                         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](./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](./instance/gateway/overview) for connection examples and [Gateway query routing](./instance/gateway/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](./engine/engine-scaling) and [Engine rollouts](./engine/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](./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](./crd-reference/engine-crd-reference) and the [object storage guides](./engine/object-storage/amazon-s3).