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 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. 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 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.

Short name: fireng.