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

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