> ## Documentation Index > Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt > Use this file to discover all available pages before exploring further. # FireboltEngine CRD reference > Spec, phases, and conditions for the FireboltEngine custom resource. ## Spec reference | Field | Required | Default | Description | | ------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `spec.instanceRef` | **Yes** | - | Name of the `FireboltInstance` in the same namespace. | | `spec.engineClassRef` | No | - | Name of a [`FireboltEngineClass`](./fireboltengineclass-crd-reference) in this Engine's namespace. Resolution is Engine, then [`FireboltEnginePreset`](./fireboltenginepreset-crd-reference), then class, then Firebolt Operator default. See [configuration inheritance](../engineclass/configuration-inheritance). | | `spec.requirePreset` | No | `false` | When `true`, the Engine stays not Ready until the namespace has a Ready `FireboltEnginePreset` object (named `firebolt`; the CRD pins the name). Unset keeps existing Engines working in namespaces with no Preset object. | | `spec.replicas` | **Yes** | - | Number of engine nodes. `0` stops the engine; the CR is preserved. | | `spec.template` | No | - | `PodTemplateSpec` for per-Engine overrides. Configure the Engine container at `spec.template.spec.containers[name=="engine"]`, including a per-Engine `image` or `imagePullPolicy`. Define a readiness probe on any sidecar container you add: a container without a probe counts as ready as soon as its process starts, and pod readiness controls blue-green promotion and Service endpoints. See [Firebolt Operator-owned fields](#firebolt-operator-owned-fields-on-engine-templates) and [EngineClass configuration inheritance](../engineclass/configuration-inheritance). | | `spec.uiSidecar` | No | `false` | When `true`, the Firebolt Operator injects a built-in, operator-owned `nginx` container named `engine-web` (serving the Engine Web UI, listening on port `9100`) into each engine pod. The `engine-web` container name is reserved, so a user-supplied container or init container with that name is rejected. The container carries an HTTP readiness probe on the UI port, so the pod only reports Ready (and rollouts only promote) when the UI is actually serving. The sidecar follows the Kubernetes default pull policy for its image (`Always` while the UI image is tracked at `:latest`); an explicit `imagePullPolicy` on the `engine` container (in this template or the class template) applies to the sidecar too. Inherited from the class when unset. Changes force a new generation. | | `spec.rollout` | No | `graceful` | `graceful` waits for drain. `recreate` deletes immediately. Inherited from the class when unset. | | `spec.drainCheckEnabled` | No | `true` | `false` skips the Firebolt Operator drain check (engine `shutdown_wait_unfinished` still runs on SIGTERM). Inherited from the class when unset. | | `spec.drainCheckInterval` | No | `5s` | Poll interval for old-pod drain status. Inherited from the class when unset. | | `spec.storage` | No | `emptyDir` | Per-pod data volume (distinct from `customEngineConfig.storage`). One of `persistentVolumeClaim`, `emptyDir`, or `hostPath`. Unset defaults to `emptyDir`. Inherited from Preset, then the class, when this engine names no backend. Changes force a new generation. | | `spec.customEngineConfig` | No | - | Deep-merged into engine `config.yaml` beneath Preset and class config (engine keys win). Operator-owned paths are stripped. Changes force a new generation. | | `spec.autoStop` | No | disabled | When `enabled`, auto-stop owns `spec.replicas`. Inherited whole-struct from the class when unset. | | `spec.metadataEndpointOverride` | No | - | Override instance-derived metadata endpoint. | ## Firebolt Operator-owned fields on engine templates The validating webhook rejects user input on paths the Firebolt Operator owns on `spec.template` (and the same rules apply to `FireboltEngineClass.spec.template` when referenced). **Rejected on the pod template:** * StatefulSet-bound fields: `terminationGracePeriodSeconds`, `subdomain`, `hostname`, `restartPolicy`, `activeDeadlineSeconds`. * Footgun fields: `hostNetwork`, `hostPID`, `hostIPC`, `shareProcessNamespace`, `hostUsers`. * Pod-template metadata except `labels` and `annotations`. * Labels or annotations under the `firebolt.io/` prefix. **Rejected on `containers[name=="engine"]`:** * `name`, `command`, `args`, `ports`, probes, reserved `FIREBOLT_*` env keys. * `restartPolicy`, `stdin`, `stdinOnce`, `tty`. **Allowed on the engine container (engine template wins over class):** `image`, `imagePullPolicy`, `resources`, `env`, `envFrom`, `volumeMounts`, `securityContext`, `lifecycle`, `workingDir`, `terminationMessagePath`, `terminationMessagePolicy`, `volumeDevices`, `resizePolicy`. Sidecar containers (any name other than `engine`) and additional `initContainers` pass through verbatim, with one restriction: they may not mount the Secret-backed operator volumes (`auth-admin`, `tls-engine`, `auth-signing-`). The `engine-config`, `data`, and `runtime` volumes are mountable — mounting `data` from an init container is the supported way to prepare the data directory before the engine starts. See [FireboltEngineClass CRD reference](./fireboltengineclass-crd-reference) for the full class-side allowlist. ## Engine phases | Phase | Meaning | | ----------- | ------------------------------------------------------------------------------ | | `stable` | Terminal. All resources match spec, `replicas > 0`, engine is serving traffic. | | `creating` | New generation being created. Waiting for pods to be ready. | | `switching` | Traffic being switched to the new generation. | | `draining` | Waiting for old generation pods to finish serving queries. | | `cleaning` | Deleting old generation resources. | | `stopped` | Terminal. `spec.replicas == 0`. CR and active-generation resources preserved. | ## Conditions | Condition | Meaning | | -------------------------------------------------- | ------------------------------------------------------------------------------------ | | `InstanceReady=True` | Referenced `FireboltInstance` is ready and providing metadata. | | `InstanceReady=False` | Instance is missing, not ready, or lacks metadata endpoint / instance ID. | | `Ready=True, Reason=EngineReady` | Engine is serving traffic with all replicas ready. | | `Ready=False, Reason=Initializing` | First reconcile of a freshly created CR. Transient. | | `Ready=False, Reason=Rolling` | Blue-green transition in progress. | | `Ready=False, Reason=PodsNotReady` | Phase is `stable` but some pods are not yet ready. | | `Ready=False, Reason=Stopped` | `spec.replicas == 0`. Intentionally parked. | | `Ready=False, Reason=InstanceNotReady` | Referenced `FireboltInstance` is not ready. | | `Ready=False, Reason=DrainCheckFailing` | Drain probe cannot reach or parse metrics on a draining pod. | | `Ready=False, Reason=TemplateRejected` | `spec.template` contains a reserved or unsupported field. | | `Ready=False, Reason=FireboltEngineClassUnready` | The referenced EngineClass is not ready. Inspect the class condition. | | `Ready=False, Reason=FireboltEnginePresetRequired` | `spec.requirePreset` is true and the namespace has no `FireboltEnginePreset` object. | | `Ready=False, Reason=FireboltEnginePresetUnready` | The namespace Preset object is not Ready. Inspect the Preset condition. | | `Ready=False, Reason=ResourceBoundsExceeded` | Engine resources exceed the limits configured on the Firebolt Operator. | | `Ready=False, Reason=ExternalFinalizer` | Engine deleting; non-operator finalizers remain on owned children. | ## Status properties | Field | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status.observedGeneration` | Latest `metadata.generation` fully reconciled to a stable Engine. | | `status.phase` | Engine lifecycle phase. See [Engine phases](#engine-phases). | | `status.currentGeneration` | Latest blue-green generation index allocated for the desired state. Resource creation can follow on the next reconciliation. | | `status.activeGeneration` | Generation currently serving traffic. | | `status.drainingGeneration` | Generation being drained, if any. | | `status.readyReplicas` | Pods of the active generation that are running and passing their readiness probe. Observed, not desired: it trails `spec.replicas` while a generation comes up, and reads `0` for a stopped Engine or one whose first generation has not cut over yet. During a blue-green rollout it stays with the generation still serving and steps to the new one at cutover, so a roll does not appear here as capacity dropping away; pods of a generation coming up or draining are not counted. | | `status.lastReconciled` | Time of the most recent reconciliation. | | `status.lastActivityTime` | Most recent Engine activity used by auto-stop. | | `status.lastScaledAt` | Most recent auto-stop replica change. | | `status.autoStopReason` | Most recent auto-stop decision. | | `status.appliedPresetName` | Name of the `FireboltEnginePreset` last applied to the serving generation. Empty when that generation was rendered without a Preset, or when no generation is serving yet. | | `status.appliedPresetHash` | Content hash of that Preset spec stamped on the serving StatefulSet (`firebolt.io/engine-preset-hash`). Trails a live Preset edit until the generation that carries the new hash is promoted. | | `status.conditions` | `InstanceReady`, `Ready`. See [Conditions](#conditions). | Short name: `fireng`.