Skip to main content

Spec reference

Pod configuration for the gateway and metadata components lives on a raw PodTemplateSpec under spec.gateway.template and spec.metadata.template respectively. They use the same shape as FireboltEngineClass.spec.template. The validating webhook restricts what users may set on those templates. See Firebolt Operator-owned fields and Customize component pods. * Required when the parent field is set.

Instance IDs

Omit spec.id to generate an ID automatically. An explicit non-empty value must be a 26-character Crockford Base32 ULID, with the first character in 0–7 and no i, l, o, or u in either case. The API server enforces this even when admission webhooks are disabled. Use lowercase for current engine images. Uppercase and mixed-case ULIDs remain accepted so instances pinned to older images can retain their identity. The operator lowercases them after metadata and every bound engine image meet the canonicalize floor. Installing the CRD does not repair malformed IDs already stored in the cluster. On clusters with validation ratcheting, unrelated updates can retain an unchanged malformed ID; without it, those updates can be rejected. Ratcheting is enabled by default from Kubernetes 1.30. Identity remains immutable except for case: replacing an account ID requires an explicit recovery plan for its metadata and data.

Firebolt Operator-owned fields on component templates

spec.gateway.template and spec.metadata.template are full PodTemplateSpec embeds. The validating webhook (vfireboltinstance.compute.firebolt.io) walks every template at admission time and rejects user input on fields the Firebolt Operator manages end-to-end. The same set of pod-level fields is rejected on both components: Per-component primary container rejections: Per-component pass-through (allowed without restriction):
  • All pod-level scheduling fields: nodeSelector, tolerations, affinity, topologySpreadConstraints, priorityClassName.
  • Pod-level: securityContext (PodSecurityContext), imagePullSecrets, serviceAccountName, additional volumes (names that do not collide with Firebolt Operator-owned volume names).
  • Additional containers (sidecars): Appended after the Firebolt Operator-rendered primary container.
  • Additional initContainers: Passed through verbatim.
  • Sidecars and init containers may mount the Firebolt Operator-rendered config-volume / config and tmp volumes, but not the Secret-backed ones: tls-gateway, client-ca, engine-ca, engine-crl, client-crl, and wake-agent-token on the gateway; postgres-creds and postgres-ca on the metadata pod.
  • Pod-template metadata.labels and metadata.annotations outside the firebolt.io/ reserved prefix.
A second container or init container using the Firebolt Operator-rendered primary name (envoy or metadata) is rejected as a duplicate.

Instance phases

Status properties

Conditions

Short name: fire.