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

# 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

```text theme={"theme":{"light":"css-variables","dark":"css-variables"}}
                         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](./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](./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).