> ## 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. # 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`, `spec.uiSidecar`, `spec.storage`, `spec.customEngineConfig`, `spec.rollout`, `spec.drainCheckEnabled`, `spec.drainCheckInterval`, and `spec.autoStop`. Engine values take precedence over class values. | | `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 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). 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=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.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.conditions` | `InstanceReady`, `Ready`. See [Conditions](#conditions). | Short name: `fireng`.