> ## 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"]`. Define a readiness probe on any sidecar container you add: a probe-less container counts as ready as soon as its process starts, and pod readiness feeds both blue-green promotion and Service endpoints. 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. 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 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`.