FireboltEngine CRD reference

Spec reference

Field	Required	Default	Description
`spec.instanceRef`	Yes	-	Name of the `FireboltInstance` in the same namespace.
`spec.engineClassRef`	No	-	Name of a `FireboltEngineClass` 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 and 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-<key-id>). 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 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.
`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.

Short name: fireng.

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Spec reference

Firebolt Operator-owned fields on engine templates

Engine phases

Conditions

Status properties

​Spec reference

​Firebolt Operator-owned fields on engine templates

​Engine phases

​Conditions

​Status properties

Spec reference

Firebolt Operator-owned fields on engine templates

Engine phases

Conditions

Status properties