> ## 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. The class supplies defaults this engine inherits when it leaves the matching field unset: `spec.template` (merged under this engine's template, engine wins), `spec.uiSidecar`, `spec.storage`, `spec.customEngineConfig`, `spec.rollout`, `spec.drainCheckEnabled`, `spec.drainCheckInterval`, and `spec.autoStop`. Engine image comes from the class template. There is no per-engine image field on this CR. | | `spec.replicas` | **Yes** | - | Number of engine nodes. `0` stops the engine; the CR is preserved. | | `spec.template` | No | - | `PodTemplateSpec` for per-engine overrides. Engine container: `spec.template.spec.containers[name=="engine"]`. See [Firebolt Operator-owned fields](#firebolt-operator-owned-fields-on-engine-templates) and [Pod template merge](../engine/engine-reconciliation#pod-template-merge). | | `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. 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 the class when this engine names no backend. Changes force a new generation. | | `spec.customEngineConfig` | No | - | Deep-merged into engine `config.yaml` beneath the class config (engine keys win). **Required** for start, from this field or the class. 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. 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=ExternalFinalizer` | Engine deleting; non-operator finalizers remain on owned children. | ## Status properties | Field | Description | | --------------------------- | ------------------------------------------------------------ | | `status.phase` | Engine lifecycle phase. See [Engine phases](#engine-phases). | | `status.currentGeneration` | Active blue-green generation index. | | `status.drainingGeneration` | Generation being drained, if any. | | `status.conditions` | `InstanceReady`, `Ready`. See [Conditions](#conditions). | Short name: `fireng`.