FireboltInstance CRD reference

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

Field	Required	Default	Description
`spec.id`	No	(auto-generated ULID)	Stable unique identifier for the instance, used as the metadata account ID. Immutable once set.
`spec.metadata`	Yes	-	Metadata service configuration (can be empty `{}` for defaults)
`spec.metadata.postgres`	No	(internal)	External PostgreSQL connection. If omitted, the Firebolt Operator deploys an internal PostgreSQL StatefulSet.
`spec.metadata.postgres.host`	Yes*	-	PostgreSQL hostname
`spec.metadata.postgres.port`	No	`5432`	PostgreSQL port
`spec.metadata.postgres.database`	Yes*	-	Database name
`spec.metadata.postgres.credentialsSecretRef.name`	Yes*	-	Secret with `username` and `password` keys
`spec.metadata.replicas`	No	`1`	Number of metadata service pods (only `1` is currently supported).
`spec.metadata.template`	No	(Firebolt Operator default)	Pod template merged with the Firebolt Operator-rendered metadata container. See Firebolt Operator-owned fields. Image: `spec.metadata.template.spec.containers[name=="metadata"].image`. When `imagePullPolicy` is unset, the Kubernetes tag rule applies, with the mutable `dev` tag treated like `latest`.
`spec.metadata.engineRegistration`	No	`false`	Register Engine objects in the metadata service for SQL-level RBAC.
`spec.gateway`	Yes	-	Envoy gateway proxy configuration (can be empty `{}` for defaults)
`spec.gateway.replicas`	No	`2`	Number of gateway pods. See Gateway sizing.
`spec.gateway.metricsPort`	No	`9090`	Container port exposing Envoy’s Prometheus metrics endpoint. The Firebolt Operator stamps a corresponding `metrics` port on the container.
`spec.gateway.template`	No	(Firebolt Operator default)	Pod template merged with the Firebolt Operator-rendered Envoy container. See Firebolt Operator-owned fields. Image: `spec.gateway.template.spec.containers[name=="envoy"].image`. When `imagePullPolicy` is unset, the Kubernetes tag rule applies.
`spec.auth`	No	disabled	Authentication configuration. Not enforced yet. Reserved for future engine-level auth.
`spec.auth.mode`	Yes*	-	`disabled`, `native`, or `openid`
`spec.auth.oidc`	Yes*	-	OIDC config (required when mode is `openid`)

* Required when the parent field is set.

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:

Pod-level field	Reason
`spec.template.spec.subdomain`	Firebolt Operator-owned for the headless-DNS contract.
`spec.template.spec.hostname`	Firebolt Operator-owned.
`spec.template.spec.restartPolicy`	Fixed by the Deployment / StatefulSet controller.
`spec.template.spec.activeDeadlineSeconds`	Incompatible with long-lived component pods.
`spec.template.spec.terminationGracePeriodSeconds`	Firebolt Operator-stamped per component (15s gateway, 30s metadata).
`spec.template.metadata.labels[firebolt.io/*]`	Reserved label prefix.
`spec.template.metadata.annotations[firebolt.io/*]`	Reserved annotation prefix (most importantly `firebolt.io/config-hash`, which drives pod rollouts).

Per-component primary container rejections:

Container field	Gateway (`envoy`)	Metadata (`metadata`)
`command`, `args`, `ports`, `readinessProbe`, `livenessProbe`, `startupProbe`	Rejected	Rejected
`lifecycle`	Rejected (the Firebolt Operator owns the bash `/dev/tcp` preStop drain hook)	Rejected
`securityContext`	Rejected (hardened defaults: non-root UID 101, drop ALL caps)	Rejected (RunAsUser pinned to the image’s `dedicated-pensieve` UID)
`env`	Rejected	Rejected (`POSTGRES_USERNAME_FILE` / `POSTGRES_PASSWORD_FILE` are Firebolt Operator-injected)
`envFrom`	Rejected	Rejected
`volumeMounts`	Rejected (`config-volume` / `tmp` are Firebolt Operator-rendered)	Rejected (`config` / `postgres-creds` / `tmp` are Firebolt Operator-rendered)
`image`, `imagePullPolicy`	Allowed	Allowed
`resources`	Allowed	Allowed

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.
Pod-template metadata.labels and metadata.annotations outside the firebolt.io/ reserved prefix.

A second container or initContainer using the Firebolt Operator-rendered primary name (envoy, metadata) is rejected as a duplicate. The authoritative rule sets live in api/v1alpha1/operatorauthority.go as GatewayPodTemplateRules and MetadataPodTemplateRules.

Instance phases

Phase	Meaning
`Provisioning`	Components are being deployed. Not yet ready.
`Ready`	Metadata service and gateway are healthy
`Degraded`	Was previously Ready, but one or more components became unhealthy
`Failed`	Terminal error requiring manual intervention (e.g., multiple accounts found in metadata)

Status properties

Field	Description
`status.phase`	Instance lifecycle phase. See Instance phases.
`status.metadataReady`	Whether the metadata service Deployment has a ready replica.
`status.gatewayReady`	Whether the gateway Deployment has a ready replica.
`status.metadataEndpoint`	In-cluster metadata gRPC endpoint (cleared when metadata is not ready).
`status.gatewayEndpoint`	In-cluster gateway HTTP endpoint (cleared when gateway is not ready).
`status.conditions`	`Ready`, `MetadataReady`, `GatewayReady`.

Short name: fire.

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Spec reference

Firebolt Operator-owned fields on component templates

Instance phases

Status properties

​Spec reference

​Firebolt Operator-owned fields on component templates

​Instance phases

​Status properties

Spec reference

Firebolt Operator-owned fields on component templates

Instance phases

Status properties