Spec reference
Every field exceptspec.template is an optional default that a referencing engine inherits when it does not set the matching field itself. Resolution is always the engine value first, then the class value, then the operator default. The engine owns the value when it sets it. The class supplies it otherwise. The operator default sits beneath both.
| Field | Required | Default | Description |
|---|---|---|---|
spec.template | Yes | – | PodTemplateSpec merged under each engine’s spec.template (engine wins). See Firebolt Operator-owned fields and FireboltEngineClass design. |
spec.uiSidecar | No | false | Default UI sidecar toggle. When it resolves to 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 engine spec.uiSidecar wins when set. |
spec.storage | No | {} (emptyDir) | Default per-pod data volume. An engine that names any backend (persistentVolumeClaim, emptyDir, or hostPath) on its own spec.storage owns it. Otherwise the class backend applies. Backend selection is whole-struct, so the three backends stay mutually exclusive. See the FireboltEngine CRD reference. |
spec.customEngineConfig | No | – | Free-form config.yaml fragment deep-merged beneath each engine’s spec.customEngineConfig. The merge order is the operator base, then the class, then the engine, so an engine key wins over the same key on the class. The Firebolt Operator strips its owned paths (schema_version, instance.*, engine.id, engine.nodes, and engine.termination_grace_period) from the class layer too, so the class cannot override identity, routing, or topology. |
spec.rollout | No | graceful | Default rollout strategy, graceful or recreate. The engine spec.rollout wins when set. |
spec.drainCheckEnabled | No | true | Default drain-check toggle. The engine spec.drainCheckEnabled wins when set. |
spec.drainCheckInterval | No | – | Default drain-poll interval. The engine spec.drainCheckInterval wins when set. |
spec.autoStop | No | – | Default auto-stop policy. This is whole-struct. An engine that sets spec.autoStop owns the entire policy with no field-merge, and the class policy applies only when the engine omits it. See the FireboltEngine CRD reference. |
spec.uiSidecar, spec.storage, or spec.customEngineConfig reshapes the rendered engine pod, so it rolls a new blue-green generation on every bound engine. Changes to spec.rollout, spec.drainCheckEnabled, spec.drainCheckInterval, and spec.autoStop are read live and do not by themselves trigger a rollout.
Firebolt Operator-owned fields on class templates
The validating webhook rejects user input on paths the Firebolt Operator owns end-to-end. Everything else underspec.template is allowed. The same
allowlist applies to FireboltEngine.spec.template.
Pod template metadata
| Path | User-allowed | Notes |
|---|---|---|
spec.template.metadata.labels | Yes | Keys under firebolt.io/ are rejected. Engine labels win on conflict. |
spec.template.metadata.annotations | Yes | Keys under firebolt.io/ are rejected. Engine annotations win on conflict. |
spec.template.metadata.{name,namespace,ownerReferences,...} | No | Assigned by the StatefulSet controller. |
Pod-level fields under spec.template.spec
| Path | User-allowed | Notes |
|---|---|---|
serviceAccountName | Yes | Engine spec.template.spec.serviceAccountName wins. |
nodeSelector | Yes | Map-merge; engine keys win. |
tolerations | Yes | Class + engine, concatenated. |
affinity | Yes | Engine wins if non-nil; no field-merge. |
topologySpreadConstraints | Yes | Class + engine, concatenated. |
priorityClassName, runtimeClassName, schedulerName | Yes | Engine wins when set. |
dnsPolicy, dnsConfig | Yes | Engine wins when set. |
preemptionPolicy | Yes | Engine wins when set. |
readinessGates, resourceClaims, hostAliases | Yes | Class + engine, concatenated. |
os, overhead | Yes | Engine wins when set. |
imagePullSecrets | Yes | Class + engine, concatenated. |
volumes | Yes | Operator volumes first; class and engine volumes appended (collisions with operator names dropped). |
securityContext | Yes | Engine wins if non-nil; operator fsGroup defaults always stamped. |
initContainers[*] | Yes | Class + engine, concatenated. Init container named engine is rejected. |
containers[name=="engine"] | Limited | See engine container table below. |
containers[name!="engine"] | Yes | Sidecars: user-owned, except the reserved engine-web name (the operator’s UI sidecar), which is rejected. |
terminationGracePeriodSeconds | No | Hardcoded to 60s (same on engine template). |
subdomain, hostname | No | Headless-DNS contract. |
restartPolicy, activeDeadlineSeconds | No | StatefulSet semantics. |
hostNetwork, hostPID, hostIPC, shareProcessNamespace, hostUsers | No | Isolation contract. |
Engine container (containers[name=="engine"])
| Field | User-allowed | Notes |
|---|---|---|
image, imagePullPolicy | Yes | Engine container image wins when set on the engine. |
resources | Yes | Engine wins wholesale if it sets requests/limits/claims; else class. Bounds checked on the merged value. |
env | Yes | Operator-injected vars first; class then engine appended (reserved keys rejected). |
envFrom | Yes | Class + engine, concatenated. |
volumeMounts | Yes | Operator mounts first; class then engine (collisions dropped). |
securityContext | Yes | Engine wins if non-nil. |
lifecycle | Yes | Engine wins if non-nil. |
workingDir | Yes | Engine wins when set. |
terminationMessagePath, terminationMessagePolicy | Yes | Engine wins when set. |
volumeDevices | Yes | Class + engine, concatenated. |
resizePolicy | Yes | Class + engine, concatenated. |
name, command, args, ports | No | Hardcoded by the Firebolt Operator. |
readinessProbe, livenessProbe, startupProbe | No | /health/ready contract. |
restartPolicy | No | Dropped by the kubelet on non-init containers. |
stdin, stdinOnce, tty | No | Non-interactive workload. |
engine is rejected (duplicate of the operator-rendered container).
Status properties
| Field | Description |
|---|---|
status.observedGeneration | metadata.generation last reconciled. |
status.boundEngines | Count of FireboltEngine resources in this namespace referencing the class. The deletion gate uses a live list, not this cache. |
status.conditions[type=Ready] | True when spec.template has no operator-owned fields. False/Reason=OperatorOwnedFieldSet is defense-in-depth for classes admitted under an older operator. |
firengc.