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 (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 and 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 onspec.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
labelsandannotations. - Labels or annotations under the
firebolt.io/prefix.
containers[name=="engine"]:
name,command,args,ports, probes, reservedFIREBOLT_*env keys.restartPolicy,stdin,stdinOnce,tty.
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 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. |
status.currentGeneration | Active blue-green generation index. |
status.drainingGeneration | Generation being drained, if any. |
status.conditions | InstanceReady, Ready. See Conditions. |
fireng.